目录 · API 文档

错误码

错误响应统一为 OpenAI 风格信封：

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key 缺失或无效"
  }
}

常见 HTTP 状态码

HTTP	code	type	说明
400	`invalid_request`	invalid_request_error	参数错误（看 message 详情）
400	`prohibited_content`	invalid_request_error	提示词命中违禁词，未扣费
401	`invalid_api_key`	authentication_error	缺 / 错 / 撤销 / 过期 key
402	`insufficient_balance`	billing_error	T 币不足，去 /recharge 充值
403	`insufficient_scope`	permission_error	key 缺 `images:write` 权限
403	`forbidden`	permission_error	访问其他用户的资源
404	`not_found`	invalid_request_error	generation id 不存在
413	`invalid_request`	invalid_request_error	参考图超 50MB
429	`rate_limit_exceeded`	invalid_request_error	达到 RPM 上限。响应 `Retry-After` 头给秒数
429	`daily_quota_exceeded`	invalid_request_error	今日 5000 次额度用完
429	`too_many_active_jobs`	invalid_request_error	同时进行的任务超过 3 个
502	`upstream_failed`	api_error	上游模型异常，已自动退款
504	`upstream_timeout`	api_error	上游 5 分钟超时，已自动退款
500	`internal_error`	api_error	未预期错误，已自动退款

排查思路

401 反复出现：去 /account/api-keys 确认 key 没被撤销，环境变量没拼错
402 余额不足：先 GET /v1/account/balance 看余额，再充值
429：响应里的 Retry-After 头告诉你几秒后可以重试，建议指数退避
5xx：T 币已退还到余额，直接重试即可；持续报错请联系客服