错误响应格式
当任务执行失败(status: "failed")时,响应中会包含一个 error 对象:
| 字段 | 类型 | 说明 |
|---|---|---|
error.code | string | 错误码标识符,详见下方完整列表 |
error.message | string | 用户友好的错误说明与排错建议 |
错误码总览
客户端错误(可自行修复)
客户端错误(可自行修复)
| 错误码 | 含义 | 可重试 |
|---|---|---|
content_policy_violation | 内容违反安全策略 | 修改内容后重试 |
invalid_parameters | 请求参数不合法 | 修正参数后重试 |
image_processing_error | 图片处理失败 | 更换图片后重试 |
image_dimension_mismatch | 图片尺寸与请求不匹配 | 调整尺寸后重试 |
request_cancelled | 请求被取消 | 重新提交 |
服务端错误(建议稍后重试)
服务端错误(建议稍后重试)
错误码详解
content_policy_violation
内容政策违规
请求内容触发了安全审核机制,被系统拦截。这是最常见的错误类型,覆盖以下场景:
| 子类型 | 说明 | 典型错误消息 |
|---|---|---|
| 写实人物 | 上传了包含真实人脸的照片 | photorealistic people detected |
| 名人肖像 | 涉及名人或公众人物 | celebrity detected in image |
| 版权/商标 | 涉及品牌 Logo、商标、受版权保护的角色 | third-party content violation |
| 成人/NSFW | 包含裸露、性暗示内容 | nudity detected |
| 暴力/自残 | 包含暴力、血腥、自残内容 | violence content blocked |
| 未成年保护 | 涉及未成年人的敏感内容 | minor content not allowed |
| 通用策略 | 其他违反内容政策的情况 | content policy violation |
generation_failed_no_content
生成失败
模型无法根据当前请求生成内容。虽然请求本身格式正确,但模型在处理过程中未能产出有效结果。
- Prompt 质量不足:描述过于模糊或矛盾,模型无法理解意图
- 模型能力限制:当前 prompt 超出了模型的生成能力范围
- 上游服务异常:底层模型服务返回了空结果
- 受保护内容检测:提示词或参考图可能涉及水印去除或受保护内容(Logo、商标等)
invalid_parameters
参数错误
请求参数不符合模型要求。
| 子类型 | 说明 | 示例 |
|---|---|---|
| Prompt 过长 | 提示词超出模型允许的最大长度 | Prompt is too long |
| 图片尺寸超范围 | 图片宽高或宽高比不在支持范围内 | image dimensions must be between 240 and 7680 |
| 文件过大 | 上传的文件超出大小限制 | file size exceeds 10MB |
| 文件格式不支持 | 上传了不支持的文件格式 | unsupported file type |
| 视频时长超范围 | 视频时长超出模型支持范围 | Video duration must be between 1-30 seconds |
image_processing_error
图片处理失败
系统无法正常处理输入的图片。
- 图片 URL 无法访问(权限不足、CDN 限制、链接过期)
- 图片格式不被支持(如 HEIC、AVIF)
- 图片文件已损坏
- 网络连接问题导致图片下载失败
image_dimension_mismatch
图片尺寸不匹配
输入图片的尺寸与请求参数中指定的尺寸不一致。常见于图生视频场景。
aspect_ratio=1280x720(16:9)时需要上传 1280×720 的横版图片aspect_ratio=720x1280(9:16)时需要上传 720×1280 的竖版图片
service_error
服务错误
上游服务内部出现问题。这通常是暂时性的,系统会自动切换到其他可用线路。
- 上游模型服务暂时不可用
- 服务器过载、高流量
- 升级维护中
- 网络连接中断
generation_timeout
生成超时
任务在规定时间内未能完成处理。
- 当前系统负载较高,排队时间过长
- 任务复杂度过高(高分辨率、长视频等)
- 上游服务响应缓慢
quota_exceeded
配额/频率超限
请求频率或并发数超出限制。
- 短时间内发送了过多请求(触发限流)
- 同时有多个任务在处理中(并发限制)
- 账户配额已用尽
resource_exhausted
资源耗尽
上游服务的计算资源暂时被耗尽。通常发生在模型使用高峰期。
resource_not_found
资源未找到
请求的任务 ID 不存在或已过期。
request_cancelled
请求被取消
任务在处理过程中被取消或中断。
service_unavailable
服务暂时不可用
服务内部出现认证或连接问题。此错误已被系统自动记录,通常会快速修复。
unknown_error
未知错误
无法归类的错误。系统未能识别该错误的具体类型。
最佳实践
错误处理建议
可重试 vs 不可重试
需要修改请求后重试
content_policy_violation— 修改内容invalid_parameters— 修正参数image_processing_error— 更换图片image_dimension_mismatch— 调整尺寸
可直接重试
generation_failed_no_content— 可换 prompt 重试service_error— 等待后重试generation_timeout— 等待后重试resource_exhausted— 等待后自动恢复quota_exceeded— 降低频率后重试