API 文档

先区分两类错误：开放 API 自身错误和文本上游错误。

开放 API 错误格式

鉴权、参数、积分、任务查询等本地错误使用统一结构：

{
  "error": {
    "code": "insufficient_credits",
    "message": "insufficient_credits"
  }
}

常见状态码：

HTTP 状态码	常见原因	是否建议重试
400	缺少参数、模型或回调地址无效。	修正请求后再提交。
401	API Key 缺失、错误、已撤销或已过期。	不要自动重试。
402	积分不足或团队额度不足。	补充积分或调整额度后再试。
403	账号或团队不可用。	不要自动重试。
404	模型或任务不存在。	核对 ID；模型问题可重新拉取列表。
429	单枚 API Key 在一分钟内请求过多。	退避后重试。
502	文本上游连接失败或超时。	可以退避重试。
503	文本 Provider 未正确配置。	切换模型或联系管理员。
500	服务内部错误。	记录请求编号，稍后重试。

每个已鉴权请求都会返回 X-Request-Id。记录状态码、错误正文和该请求编号，方便定位日志。

文本上游错误

/v1/chat/completions 和 /v1/messages 会原样返回上游状态码和响应正文。上游错误不一定符合上面的统一 JSON 结构。

客户端应先判断 HTTP 状态码，再按响应的 Content-Type 读取 JSON 或文本，不要只检查 error.code。

限流处理

限流按 API Key 计算，具体额度由服务端配置。收到 429 后使用指数退避并加入随机抖动，例如：

function retryDelay(attempt) {
  const base = Math.min(30000, 1000 * 2 ** attempt)
  return base + Math.floor(Math.random() * 500)
}

不要在多个 Worker 中共享同一枚密钥后各自按满额度发送。按服务或队列拆分 API Key，排查和限流都会更清楚。

扣费时点

接口	扣费方式
文本生成	先扣模型最低积分，再按上游返回的 token usage 结算。上游失败时退回预扣积分。
图片生成	创建任务时按模型和参数计算并扣除积分。
视频生成	创建任务时按模型、时长和参数计算并扣除积分。

通过 GET /v1/user 查询当前可用积分。

哪些请求可以重试

GET 请求可以在网络错误、429 或 5xx 后安全重试。

POST 请求需要更谨慎：

• 文本请求重试会再次调用模型并再次计费。
• 图片和视频创建接口目前没有幂等键。请求超时不代表任务一定没有创建。
• external_id 只用于保存业务关联信息，不会阻止重复任务。

创建任务后立即保存 task_id。如果连接在收到响应前中断，不要无限自动重试；先查看任务列表和积分记录，再决定是否重新创建。

一个可用的重试边界

• 400、401、402、403：停止重试，先处理请求或账号问题。
• 404：任务查询停止重试；模型调用可刷新模型列表后重试一次。
• 429、502、普通 5xx：指数退避，限制最大次数。
• 网络超时：GET 可重试；POST 先确认是否可能已经成功。