跳转到主要内容

错误响应格式

当任务执行失败(status: "failed")时,响应中会包含一个 error 对象:

错误码总览

客户端错误(可自行修复)


错误码详解

content_policy_violation

内容政策违规

请求内容触发了安全审核机制,被系统拦截。这是最常见的错误类型,覆盖以下场景:
常见触发场景:
如何避免:
  • 避免上传真人照片,改用插画风格或卡通风格
  • 移除品牌 Logo、商标、受版权保护的 IP 角色
  • 避免成人、暴力、自残等敏感主题
  • 使用通用的人物描述(如 “a person”),不要引用具体名人

generation_failed_no_content

生成失败

模型无法根据当前请求生成内容。虽然请求本身格式正确,但模型在处理过程中未能产出有效结果。
常见原因:
  • Prompt 质量不足:描述过于模糊或矛盾,模型无法理解意图
  • 模型能力限制:当前 prompt 超出了模型的生成能力范围
  • 上游服务异常:底层模型服务返回了空结果
  • 受保护内容检测:提示词或参考图可能涉及水印去除或受保护内容(Logo、商标等)
如何处理:
  • 调整 prompt,使描述更清晰具体
  • 更换参考图片,避免带有水印或 Logo 的图片
  • 简化请求(减少分辨率或复杂度),降低模型处理难度
  • 直接重试,部分情况下重试即可成功

invalid_parameters

参数错误

请求参数不符合模型要求。
常见子类型:
如何处理:
  • 检查各模型文档中的参数说明,确保参数值在允许范围内
  • 图片支持格式:JPG、PNG、WebP、GIF(不支持 HEIC、AVIF、TIFF)
  • 图片大小限制:通常 < 10MB,部分模型 < 30MB
  • 缩短 prompt 长度,或将长 prompt 拆分为核心描述

image_processing_error

图片处理失败

系统无法正常处理输入的图片。
常见原因:
  • 图片 URL 无法访问(权限不足、CDN 限制、链接过期)
  • 图片格式不被支持(如 HEIC、AVIF)
  • 图片文件已损坏
  • 网络连接问题导致图片下载失败
如何处理:
  • 确保图片 URL 可公开访问,没有认证或地域限制
  • 使用标准格式:JPG、PNG、WebP
  • 尝试使用 文件上传接口 替代 URL 方式
  • 检查图片是否完整可打开

image_dimension_mismatch

图片尺寸不匹配

输入图片的尺寸与请求参数中指定的尺寸不一致。常见于图生视频场景。
示例:
  • aspect_ratio=1280x720(16:9)时需要上传 1280×720 的横版图片
  • aspect_ratio=720x1280(9:16)时需要上传 720×1280 的竖版图片
如何处理: 调整图片尺寸使其与请求的 aspect_ratio 参数匹配,或更改 aspect_ratio 参数以适应图片尺寸。

service_error

服务错误

上游服务内部出现问题。这通常是暂时性的,系统会自动切换到其他可用线路。
常见原因:
  • 上游模型服务暂时不可用
  • 服务器过载、高流量
  • 升级维护中
  • 网络连接中断
如何处理:
  • 等待 30-60 秒后重试,系统通常会自动恢复
  • 如果持续出现,联系技术支持
  • 不需要修改请求内容,重试相同请求即可

generation_timeout

生成超时

任务在规定时间内未能完成处理。
常见原因:
  • 当前系统负载较高,排队时间过长
  • 任务复杂度过高(高分辨率、长视频等)
  • 上游服务响应缓慢
如何处理:
  • 稍后重试,选择低峰时段
  • 降低任务复杂度:减少分辨率、缩短视频时长
  • 简化 prompt 描述

quota_exceeded

配额/频率超限

请求频率或并发数超出限制。
常见原因:
  • 短时间内发送了过多请求(触发限流)
  • 同时有多个任务在处理中(并发限制)
  • 账户配额已用尽
如何处理:
  • 降低请求发送频率,建议每次请求间隔 1-2 秒
  • 等待进行中的任务完成后再提交新任务
  • 如果是配额用尽,请到 账户充值页面 充值

resource_exhausted

资源耗尽

上游服务的计算资源暂时被耗尽。通常发生在模型使用高峰期。
如何处理:
  • 等待 1-5 分钟后自动恢复
  • 系统会自动在多条线路间切换,稍后重试通常即可成功

resource_not_found

资源未找到

请求的任务 ID 不存在或已过期。
如何处理:
  • 检查任务 ID 是否正确拼写
  • 任务结果有有效期,过期后将无法查询
  • 如确认 ID 正确,稍后重试

request_cancelled

请求被取消

任务在处理过程中被取消或中断。
如非主动取消,直接重新提交相同请求即可。

service_unavailable

服务暂时不可用

服务内部出现认证或连接问题。此错误已被系统自动记录,通常会快速修复。
如何处理:
  • 等待几分钟后重试
  • 如果持续出现,请联系技术支持并提供任务 ID

unknown_error

未知错误

无法归类的错误。系统未能识别该错误的具体类型。
如何处理:
  • 稍后直接重试
  • 如果问题持续,请联系技术支持并提供完整的任务 ID

最佳实践

错误处理建议

可重试 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 — 降低频率后重试