Skip to content

错误处理与轮询 ​

区分三类失败 ​

表格较宽时,可左右滑动查看完整内容。

层次判断方法处理方式
HTTP / 网络失败非 2xx、连接中断、超时查看 HTTP 状态和错误体;超时不等于服务端未执行
请求业务失败原生 code != 0;兼容接口 error 对象修正 Key、模型、参数或余额后再提交
已创建任务执行失败原生 data.status = 4;兼容 status = "failed"读取任务错误信息,停止轮询

原生任务失败信息位于 data.errorCode、data.errorMessage;兼容任务位于 error.code、error.message。请求成功与任务成功是两个不同阶段,不能只检查 HTTP 200。

常见问题排查 ​

表格较宽时,可左右滑动查看完整内容。

问题排查和处理
Key 无效检查 Authorization: Bearer ...,确认 Key 未删除、禁用且没有多余引号;停止使用失效 Key 重试
模型不存在或 model_ambiguous重新拉取配置或模型列表;兼容接口传完整 channel:model ID,测试模型除外
参数不支持从所选模型的配置中选择画幅、质量、时长和素材数量,避免照抄结构示例
积分不足查询账号积分,核对生成费用;素材上传的完成确认也会单独扣费
素材无法读取确认公网可访问、签名未过期、完整保留 URL 查询参数;平台上传须完成确认
找不到任务使用创建响应中的 ID,确认 Key 属于同一账号,不混用两套协议的字段
任务尚未完成时下载继续查询;兼容内容接口要求 status=completed

429 与 Retry-After ​

平台对同一客户端 IP 的连续无效 API Key 请求有保护措施。达到限制后会返回 HTTP 429,并通过 Retry-After 响应头给出等待秒数;限制期间换成有效 Key 也可能仍需等待。

这项机制属于鉴权失败保护,不能据此推导正常调用的固定 QPS 配额。先修正鉴权问题,再等待响应头指定的时间后重试,不要持续发送失败请求。

兼容接口的这类响应示例:

http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
json
{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

60 仅为示例,以实际响应头为准。兼容接口其他错误见错误响应。

轮询与超时 ​

  1. 创建成功后保存任务 ID,建议每 10~15 秒查询一次;多个原生任务优先批量查询。
  2. 成功时读取输出地址;失败时记录错误并停止。不要依赖 progress=100 判断成功。
  3. 查询发生暂时性网络失败或服务异常时,可以延迟后重试,设置总等待时间或最大次数;收到 Retry-After 时遵守等待时间。
  4. 本地停止等待不会取消服务端任务。稍后仍可用已保存的 ID 查询,不要因此重新创建任务。

创建请求超时

创建请求可能已被服务端执行。未收到响应不表示没有创建或扣费,不要对创建请求直接套用查询的自动重试策略,以免重复生成。若已获得任务 ID,继续查询该任务;若没有 ID,先在官网核对账号任务记录,必要时联系平台核实。

上传失败与链接有效期 ​

  • expireSeconds 是预签名上传 URL 的有效期,过期后需重新申请。
  • 完成确认返回的素材 URL 带签名,使用时保留完整查询参数;上传文件保留 3 天,不作为长期存储。
  • 预签名、素材访问签名与文件保留期限是不同概念。素材访问失败时不要通过删除签名参数尝试修复。
  • 文件 PUT 请求体使用原始二进制;请求头、大小、MIME 类型与预签名记录一致。
  • PUT 成功后仍需完成确认。该确认接口支持同一 fileKey 重复调用且不重复扣费,这不代表生成任务创建接口也具有同样语义。

退款与扣费时点见计费与退款及上传计费。

星辰 AI · 图片与视频生成 API