错误格式

/api/v1/** 出错时 HTTP 状态码非 2xx，响应体是同一个结构：

{
  "error": {
    "code": "insufficient_scope",
    "message": "此 API 密钥没有 generate:write 权限。",
    "request_id": "req_xxxxxxxxxxxxxxxxxxxx"
  }
}

字段	说明
`code`	机器可读的错误码，程序按它分支。稳定，不会改
`message`	给人看的说明，跟随语言：网页按界面语言，API 按 `Accept-Language`，默认中文。可能变化，不要按它匹配
`request_id`	本次请求的唯一 id，和响应头 `X-Request-Id`、开发者中心日志里的一致。反馈问题时附上

成功响应也带 X-Request-Id 头。

/api/file/<filename> 不在 /api/v1 下，出错返回纯文本，见图片下载。

状态码总表

状态码	`code`	含义	怎么办
`400`	`invalid_request` 及子码	参数不合法	改参数，不要重试
`401`	`unauthorized`	没带 `Authorization` 头	带上
`401`	`invalid_api_key`	密钥无效、已撤销或已过期，`message` 写明哪种	新建一把
`402`	`insufficient_credits`	积分不足，`message` 带需要多少和充值联系方式	充值
`403`	`insufficient_scope`	密钥缺少所需权限	新建一把带该权限的
`403`	`banned`	账号已封禁	联系客服
`404`	`session_not_found`	`session_id` 不存在或不属于你	不传，或传自己的
`404`	`not_found`	图片包发布记录不存在或不属于你	—
`429`	`rate_limited`	密钥超过 24 小时限额	等窗口过去，见限额
`429`	`new_user_daily_limit`	新账号 24 小时内消耗超过上限	明天再来
`500`	`internal_error`	生成失败或服务端错误。已预扣的积分已退回	可重试一次；持续失败附 `request_id` 反馈
`503`	`auth_unavailable`	鉴权服务暂时不可用	几秒后重试

出图接口 POST /api/v1/generate 的参数错误会给出具体子码：

`code`	含义
`invalid_request`	请求体不是 JSON，或 `prompt` 和 `ref_image_ids` 都没有
`prompt_too_long`	`prompt` 超过 4000 字符
`invalid_model`	`model` 不在模型表里
`invalid_ratio`	`ratio` 不合法，或该模型不支持这个比例，`message` 列出可选值
`invalid_resolution`	`resolution` 不是 `1K` / `2K` / `4K`
`invalid_quality`	`quality` 不是 `low` / `medium` / `high`
`invalid_image_count`	`n` 不是 1 / 2 / 4
`invalid_reference_images`	`ref_image_ids` 不是字符串数组
`too_many_reference_images`	参考图超过模型上限
`reference_image_missing`	有参考图已不在图库里（被删除或清理）
`prompt_or_reference_required`	提示词和参考图不能同时为空

错误格式

统一错误体、完整错误码与重试建议

/api/v1/** 出错时 HTTP 状态码非 2xx，响应体是同一个结构：

{
  "error": {
    "code": "insufficient_scope",
    "message": "此 API 密钥没有 generate:write 权限。",
    "request_id": "req_xxxxxxxxxxxxxxxxxxxx"
  }
}

字段	说明
`code`	机器可读的错误码，程序按它分支。稳定，不会改
`message`	给人看的说明，跟随语言：网页按界面语言，API 按 `Accept-Language`，默认中文。可能变化，不要按它匹配
`request_id`	本次请求的唯一 id，和响应头 `X-Request-Id`、开发者中心日志里的一致。反馈问题时附上

成功响应也带 X-Request-Id 头。

/api/file/<filename> 不在 /api/v1 下，出错返回纯文本，见图片下载。

状态码	`code`	含义	怎么办
`400`	`invalid_request` 及子码	参数不合法	改参数，不要重试
`401`	`unauthorized`	没带 `Authorization` 头	带上
`401`	`invalid_api_key`	密钥无效、已撤销或已过期，`message` 写明哪种	新建一把
`402`	`insufficient_credits`	积分不足，`message` 带需要多少和充值联系方式	充值
`403`	`insufficient_scope`	密钥缺少所需权限	新建一把带该权限的
`403`	`banned`	账号已封禁	联系客服
`404`	`session_not_found`	`session_id` 不存在或不属于你	不传，或传自己的
`404`	`not_found`	图片包发布记录不存在或不属于你	—
`429`	`rate_limited`	密钥超过 24 小时限额	等窗口过去，见限额
`429`	`new_user_daily_limit`	新账号 24 小时内消耗超过上限	明天再来
`500`	`internal_error`	生成失败或服务端错误。已预扣的积分已退回	可重试一次；持续失败附 `request_id` 反馈
`503`	`auth_unavailable`	鉴权服务暂时不可用	几秒后重试

出图接口 POST /api/v1/generate 的参数错误会给出具体子码：

`code`	含义
`invalid_request`	请求体不是 JSON，或 `prompt` 和 `ref_image_ids` 都没有
`prompt_too_long`	`prompt` 超过 4000 字符
`invalid_model`	`model` 不在模型表里
`invalid_ratio`	`ratio` 不合法，或该模型不支持这个比例，`message` 列出可选值
`invalid_resolution`	`resolution` 不是 `1K` / `2K` / `4K`
`invalid_quality`	`quality` 不是 `low` / `medium` / `high`
`invalid_image_count`	`n` 不是 1 / 2 / 4
`invalid_reference_images`	`ref_image_ids` 不是字符串数组
`too_many_reference_images`	参考图超过模型上限
`reference_image_missing`	有参考图已不在图库里（被删除或清理）
`prompt_or_reference_required`	提示词和参考图不能同时为空