错误响应格式
当任务执行失败(status: "failed")时,响应中会包含一个 error 对象:
错误码总览
客户端错误(可自行修复)
客户端错误(可自行修复)
错误码详解
content_policy_violation
内容政策违规
请求内容触发了安全审核机制,被系统拦截。这是最常见的错误类型,覆盖以下场景:
generation_failed_no_content
生成失败
模型无法根据当前请求生成内容。虽然请求本身格式正确,但模型在处理过程中未能产出有效结果。
- Prompt 质量不足:描述过于模糊或矛盾,模型无法理解意图
- 模型能力限制:当前 prompt 超出了模型的生成能力范围
- 上游服务异常:底层模型服务返回了空结果
- 受保护内容检测:提示词或参考图可能涉及水印去除或受保护内容(Logo、商标等)
invalid_parameters
参数错误
请求参数不符合模型要求。
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— 降低频率后重试