开始使用

快速开始

四步发出第一个视频任务并把 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–7000 字	必填
duration	5–15，默认 5	成片秒数，计费按它。实际成片会略长（帧数对齐到模型栅格），多出的部分不收钱
resolution	`768p` / `2k` / `4k`	2K、4K 通过超分输出
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` 是加速档，与标准档同价：适合试验提示词；速度与效果取决于实际模型方案和可用算力
seed	整数	固定随机种子；结果也受模型与运行参数影响
use_context_ir	boolean，初始默认 false	官方 Context IR，可选；实际应用成功后按次收费
webhook_url	URI	终态回调，见下

控制台可以在账户中保存 Context IR 默认状态，在每次任务中单独修改。高级参数是否显示及未修改时的默认值由管理后台配置，H3 不支持反向提示词。费用与算例见定价。

幂等键

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

04轮询与下载

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

# status: queued → encoding → rendering → [upscaling] → packaging → succeeded
# awaiting_capacity 是等待资源的附加字段，不是 status
# 到 succeeded 后取成片
curl -L $H3_BASE/v1/videos/vid_xxx/content -H "Authorization: Bearer $H3_API_KEY" -o out.mp4

awaiting_capacity 表示当前在等待可用资源，结合 reason 区分算力、加速能力或编码器。无此字段并不等于任务已经完成；请继续读取 status。失败时查看 fail_reason 与 fail_detail。

成片是否带可见水印以 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":"镜头缓慢推近"}'

素材不留过夜

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