快速开始
错误
HTTP 状态码、错误响应结构以及任务失败状态。
错误响应结构
每个失败的请求都会返回非 2xx 状态码，以及同一结构的 JSON 响应体：
{
"ok": false,
"error": "NOT_ENOUGH_CREDITS",
"message": "Not enough credits: this generation costs 12."
}error 是稳定的机器可读错误码；message 面向人类，措辞可能变化。请根据 error 分支处理，不要依赖文案。
状态码
| 状态码 | 错误码 | 说明 |
|---|---|---|
| 400 | INVALID_REQUEST | JSON 请求体格式错误或缺少字段。 |
| 400 | INVALID_IMAGE_REQUEST | 图片参数无效：模型不存在、画面比例不合法、参考图过大或参考图过多。 |
| 400 | INVALID_VIDEO_REQUEST | 视频参数无效：模型或变体不存在，时长、尺寸或比例不受支持。 |
| 401 | UNAUTHORIZED | API Key 缺失、无效、已被撤销或已过期。 |
| 402 | NOT_ENOUGH_CREDITS | 账号余额不足以支付本次生成费用。 |
| 403 | UNAUTHORIZED | 账号已被停用。 |
| 404 | GENERATION_NOT_FOUND | 任务不存在，或属于其他账号。 |
| 429 | CONCURRENCY_LIMIT | 该账号套餐的并发任务已达上限。 |
| 500 | INTERNAL_ERROR | 服务器内部错误。 |
| 503 | SERVICE_CONFIGURATION | 服务器未配置所请求的能力。 |
| 503 | MODEL_UNAVAILABLE | 所请求的视频模型暂时不可用。 |
任务失败不是 HTTP 错误
任务被接受后如果执行失败，轮询接口依然返回 200。请检查任务字段：
{
"ok": true,
"generation": {
"id": "gen_2f1c9a...",
"status": "failed",
"error": "The model rejected this prompt (content policy).",
"durationMs": 3200,
"imageUrls": []
}
}status | 说明 |
|---|---|
generating | 仍在运行，继续轮询。 |
success | 已完成，读取 imageUrls 或 videoUrls。 |
failed | 已失败结束，读取 error。 |
失败任务的积分会自动退回。失败的任务不会被重试：想再试一次就提交新请求。
安全地重试
429和5xx响应可以用指数退避重试。- 不要在未改动请求的情况下重试
400、401/403、402或404，它们会再次失败。 - 每个被接受的
POST都会创建新任务并扣除积分，所以超时后盲目重试可能重复扣费。先读错误：如果请求在受理前就被拒绝，重试是安全的。