API 参考
错误码
每个错误都带 request_id，反馈问题时请一并提供。
01错误结构
{
"error": {
"type": "invalid_request_error",
"code": "insufficient_credits",
"message": "余额不足",
"param": "duration",
"request_id": "req_..."
}
}type 是大类，code 是可编程判断的具体原因，message 面向人、不要用它做逻辑判断。
02HTTP 状态码
| 状态 | type | 含义 |
|---|---|---|
| 400 | invalid_request_error | 参数不合法、JSON 解析失败、模式与素材不匹配 |
| 401 | authentication_error | 缺少或无效的 API Key |
| 402 | invalid_request_error | 余额不足 |
| 403 | invalid_request_error | 地域限制：所在区域被模型许可证排除 |
| 404 | not_found_error | 任务、素材或 Key 不存在（也可能不属于你） |
| 413 | invalid_request_error | 素材超过大小上限 |
| 415 | invalid_request_error | 素材类型不在白名单内 |
| 429 | rate_limit_error | 超出速率或在途任务数上限，响应带 Retry-After |
| 500 | api_error | 平台内部错误，请附 request_id 反馈 |
| 503 | api_error | 存储等依赖暂时不可用 |
404 有两种含义
任务不存在、以及任务存在但不属于你，都返回 404。 这是刻意的：用 403 区分会泄漏"这个 ID 确实存在"。03错误码一览
| code | 含义 |
|---|---|
| invalid_parameter | 某个字段不合法，具体字段在 param 中给出 |
| invalid_json | 请求体不是合法 JSON |
| invalid_api_key | Key 无效或已吊销 |
| insufficient_credits | 余额不足以冻结本次任务所需额度 |
| region_blocked | 出站 IP 判定为许可证排除区域 |
| rate_limit_exceeded | 触发速率限制 |
| too_many_inflight_tasks | 单 Key 在途任务数达到上限 |
| task_not_found | 任务不存在或不属于当前 Key |
| task_not_cancellable | 任务已进终态，无法取消 |
| task_not_terminal | 任务尚未进终态，此操作要求终态 |
| output_not_available | 成片尚未就绪或已过期 |
| file_not_found | 素材不存在、不属于你，或已过保留期被删除 |
| file_too_large | 素材超过大小上限 |
| unsupported_media_type | 素材类型不在白名单内 |
| key_not_found | 指定的 API Key 不存在 |
| storage_unavailable | 存储后端暂时不可用 |
04重试建议
- 429：按
Retry-After等待后重试。 - 500 / 503：指数退避重试，务必带
Idempotency-Key，否则可能重复建任务。 - 400 / 401 / 402 / 403 / 404：重试不会改变结果，请先修正请求或账户状态。
任务失败 ≠ 请求失败
POST /v1/videos 返回 202 只表示受理成功。 生成本身可能失败（status: failed 与 fail_reason）， 那不是 HTTP 错误。这类失败不计费，可直接重新提交。 常见的 fail_reason 之一是长时间无节点认领，见接口一览的 awaiting_capacity 说明。