5 分钟接入
拿到密钥，创建任务，再取回视频。
API 是异步的：创建后会先返回任务 ID。每隔 5～10 秒查一次，看到 succeeded 后读取视频链接。
先跑通一条任务
先在 API 密钥页创建项目密钥，再替换示例中的 Bearer 密钥。
查询这条任务
看到 status: "succeeded" 后，从 content.video_url 读取最终视频。storage.persistent 为 true 时表示视频已经保存到本服务器。
接口一览
所有业务接口都需要 Authorization: Bearer 你的密钥。
| 方法 | 地址 | 用来做什么 |
|---|---|---|
POST | /v1/videos/generations/tasks | 创建视频任务 |
GET | /v1/videos/generations/tasks/{任务ID} | 查询单条任务和最终结果 |
GET | /v1/videos/generations/tasks | 分页查询当前密钥所属客户的任务 |
GET | /healthz | 检查服务是否在线，无需密钥 |
查询任务列表
列表支持 page_num、page_size（1～100）、status 和 model 筛选。
创建任务参数
页面上能设置的能力，API 都可以传。只写提示词时，最少传 model 和 content。
可用模型与能力
| 模型 | 输入 | 画面比例 | 时长 | 输出 | 价格 |
|---|
通用参数
| 参数 | 是否必填 | 怎么填 | 默认值 |
|---|---|---|---|
model | 必填 | 填写上表中的模型标识 | — |
content | 必填 | 按所选模型支持的输入类型传入内容 | — |
ratio | 选填 | 以所选模型目录为准 | 该模型首个可用值 |
duration | 选填 | 以所选模型目录为准 | 该模型首个可用值 |
resolution | 选填 | 以所选模型目录为准 | 该模型首个可用值 |
模型限制：参数会随服务端模型目录更新。
提示词和参考图怎么传
提示词必须填写；参考图只接受浏览器能直接访问的 HTTP(S) 图片 URL。
| 素材 | content.type | role | 数量规则 |
|---|---|---|---|
| 文字 | text | 不用传 | 内容不能为空，最多 10,000 字符 |
| 参考图片 | image_url | reference_image | 0～9 个公开 HTTP(S) URL |
参考图示例
返回结果和任务状态
创建成功返回 HTTP 201；相同 Idempotency-Key 重试时返回同一任务，避免重复扣费。
正在生成视频，已冻结该模型的预计费用。
已完成，按所选模型与时长结算。
失败原因在 error，冻结金额会自动退回。
成功结果示例
billing.amount 是本次积分实付数量；usage.total_tokens 是上游返回的视频生成用量。上游未提供用量时还会返回 usage_unavailable: true。
需要长期链接时：任务成功后继续查询，直到 storage.persistent 为 true。此时 content.video_url 已经是本服务器的持久地址。
常见错误
接口错误都会返回 {"success":false,"error":{"code":"...","message":"..."}}。
| HTTP | 错误码 | 怎么处理 |
|---|---|---|
| 400 | BAD_REQUEST | 参数不符合规则，直接看 message 修改 |
| 401 | UNAUTHORIZED | 检查 Bearer 密钥是否完整、有效 |
| 402 | INSUFFICIENT_BALANCE | 积分余额不足，请联系管理员充值 |
| 404 | NOT_FOUND | 任务不存在，或任务不属于当前客户 |
| 429 | RATE_LIMITED | 请求太快，稍等后重试 |
| 502 | UPSTREAM_ERROR | 上游暂时不可用；创建失败会自动退回预占金额 |
| 500 / 502 | STORAGE_ERROR | 结果保存失败，稍后查询或重试 |
建议：每次创建都传一个业务唯一的 Idempotency-Key，最长 128 个字符。网络超时后可以安全重试，不会重复创建任务或重复扣费。