开始使用

快速开始

四步发出第一个视频任务并把 mp4 拿到手。

01取得 API Key

在控制台 · API Key 页创建。明文只在创建时出现一次（平台只存哈希），当场没抄走就只能吊销重建。

请勿在浏览器中使用 Key

Key 等同于账户余额的支配权。请只在服务端使用，不要写进前端代码、仓库或任何会被分发的产物里。泄漏了立即在控制台吊销。

02配置 Base URL 与鉴权

所有请求走 Bearer 鉴权：

export H3_BASE="https://api.456.com.cn"
export H3_API_KEY="sk-..."   # 控制台创建，只出现一次

# 每个请求都带上
Authorization: Bearer $H3_API_KEY

03发起任务

生成类操作一律异步。这个调用只做受理——鉴权、余额冻结、幂等、入队—— 然后立刻返回 202，绝不等生成。

curl -X POST $H3_BASE/v1/videos \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-request-0001" \
  -d '{
    "prompt": "一只猫在雨中的霓虹街头行走，电影质感",
    "duration": 5,
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "acceleration": "auto"
  }'

常用参数（完整列表见接口一览）
字段	取值	说明
prompt	1–2000 字	必填
duration	5–15，默认 5	成片秒数，计费按它。实际成片会略长（帧数对齐到模型栅格），多出的部分不收钱
resolution	`768p` / `2k`	2k 档尚未实现
aspect_ratio	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9`	默认 16:9。画面大小随画幅变（1:1 最小 768×768，16:9 与 21:9 最大）
acceleration	`auto` / `off`	已由 `service_tier` 接管，只在 `draft` 档有意义；实际结果看返回里的 `accelerated`
service_tier	`draft` / `standard` / `pro` / `dedicated`	`draft` 是加速档，与标准档同价：约 2.3 倍出片速度，运动连贯性有折损，适合试 prompt
seed	整数	复现同一结果
webhook_url	URI	终态回调，见下

幂等键

带上 Idempotency-Key，同一个键重复提交返回同一个任务，不会重复计费。网络抖动时的重试请务必带它。

04轮询与下载

# 轮询
curl $H3_BASE/v1/videos/vid_xxx -H "Authorization: Bearer $H3_API_KEY"

# status: queued → awaiting_capacity → rendering → encoding → succeeded
# 到 succeeded 后取成片
curl -L $H3_BASE/v1/videos/vid_xxx/content -o out.mp4

awaiting_capacity 表示还没有节点接单，与"正在跑"是两回事，可以据此给用户不同的提示。30 分钟仍无人认领会失败，且全额不计费。

成片带可见水印，output.watermarked 如实反映实际情况。详见生成内容标识。

05用 Webhook 替代轮询

建任务时传 webhook_url，任务进终态时平台会 POST 事件过去。带 HMAC 签名、至少一次投递、退避重试。验签与幂等写法见 Webhook。

06图生视频

先上传素材，再用返回的 file_ id 建任务：

# 1) 上传
curl -X POST $H3_BASE/v1/files \
  -H "Authorization: Bearer $H3_API_KEY" \
  -F purpose=input_image -F file=@first-frame.png
# → { "id": "file_9f2c...", "expires_at": "..." }

# 2) 用它建任务
curl -X POST $H3_BASE/v1/videos \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"image_to_video","input_image":"file_9f2c...","prompt":"镜头缓慢推近"}'

素材不留过夜

上传的素材有保留期，过期后字节会被真正删除，而非仅拒绝访问。过期后再以该文件创建任务将被拒绝。见隐私政策。