开发者文档

01 / QUICKSTART

先创建受限 Key。

在服务器环境中保存 Key，并通过 Authorization: Bearer … 发送。浏览器、客户端应用和公开仓库都不应持有该 Key。

curl https://YOUR_ORIGIN/v1/models \
  -H "Authorization: Bearer fw_…"

以当前实例返回的数据为准；目录不包含上游密钥、上游成本或内部任务标识。

03 / CREATE

创建视频任务

每个有费用的请求都应包含稳定的 Idempotency-Key。在网络重试时复用同一个 key；只有业务参数改变时才生成新的 key。

POST /v1/video/generations
Authorization: Bearer fw_…
Idempotency-Key: 7e2d…
Content-Type: application/json

{
  "prompt": "黄昏海岸的银色跑车",
  "duration": 5,
  "resolution": "480p",
  "aspect_ratio": "16:9"
}

请求会返回任务记录或同一幂等键之前创建的记录。不要把来自客户端的价格、积分或时段字段提交为业务参数。

04 / WAN 2.2 ANIMATE

动作迁移先上传，再请求。

先将参考图和 MP4/WebM 参考视频上传到 /api/upload，使用返回的私有 asset:<id>。建议上传 multipart 与 base64 JSON 都明确携带 kind（image、audio 或 video）；MP4 用作音频参考时必须是 kind=audio，动作视频应使用 kind=video。

POST /api/upload
Authorization: Bearer fw_…
Content-Type: multipart/form-data

kind=video
file=@motion.mp4

{"reference":"asset:video-id"}

POST /v1/video/generations
Authorization: Bearer fw_…
Idempotency-Key: motion-2026-0001
X-Max-Credits: 45
Content-Type: application/json

{
  "mode": "motion_retargeting",
  "model": "wan2.2-animate",
  "ref_image": "asset:image-id",
  "ref_video": "asset:video-id",
  "resolution": "464*832px(竖版)",
  "max_duration": 15,
  "seed": 0
}

max_duration 是预扣上限，不会要求上游裁剪视频。按实际产物时长向上取整到秒结算（不足 1 秒按 1 秒），完成后退回差额；若实际时长超出上限则进入人工对账，绝不静默多扣。X-Max-Credits 可设为调用方愿意接受的最高预扣积分，超过时服务器拒绝创建。

对应 MCP 工具为 create_video_generation：传入相同的 mode、model、ref_image、ref_video、resolution、max_duration、可选 seed、idempotency_key 和可选 max_credits；不要混入 H3 的 prompt、duration 或 aspect_ratio。

真实模式的远程视频仅接受管理员允许列表中的 HTTPS 域名，服务器会先下载、本地缓存并用 ffprobe 探测时长，再将受控素材交给上游。因此服务器必须安装 ffprobe，并配置可公开访问的 HTTPS PUBLIC_ORIGIN。只有任务成功并完成账本结算后结果才可下载；排队、处理中或待对账的未结算输出不提供下载。

05 / ASYNC STATUS

轮询你的任务，而非重新提交。

GET /v1/tasks/TASK_ID
Authorization: Bearer fw_…

排队与处理中可安全轮询。任务若进入对账状态，表示上游接受结果不明；请保留请求记录，等待管理员以证据处理，切勿盲目重新创建。