快速开始

错误

每个失败都会返回标准 HTTP 状态码和相同的 JSON 信封 —— 在读取其他任何内容之前，请先根据 success 分支处理。

两类失败 请求错误（密钥错误、参数错误、超出配额）会同步返回一个非 2xx 响应，包含下方的信封。生成失败发生在之后：创建请求返回 200，随后资产以 taskStatus: 3 结束 —— 其积分会自动退还。读取资产上的 errorCategory / errorDetail 即可查看原因。参见异步与轮询。

错误信封

error response

{
  "success": false,
  "error": {
    "code": 14001,
    "message": "Insufficient credit",
    "httpStatus": 402,
    "timestamp": "2026-08-05T09:12:00.000Z",
    "path": "/v1/models/from-text"
  }
}

错误响应中没有 data。error.code 是稳定的数字标识符 —— 请根据它分支，而不要根据 error.message，后者面向人类阅读且可能变化。

部分错误码带有 error.details 少数错误会附带一个 error.details 对象，包含失败背后的实时数值 —— 例如 13002 会返回 { "total": 15, "maxTotal": 15 }。请读取这些值，而不要把上限硬编码到客户端中。

HTTP 状态码

状态	含义
`400`	校验错误 —— 参数错误或缺失、引擎/格式不受支持，或图像无法读取。
`401`	API 密钥缺失、无效或已吊销。
`402`	积分不足以支付该任务。
`403`	账号没有 API 使用权限 —— 没有有效订阅或已完成的积分购买。
`404`	找不到资产或合集，或不属于你的密钥。
`413`	上传的文件超过 20 MB。
`429`	触及速率限制（`10003`）、进行中的并发生成过多（`13002`），或上游引擎的配额超出。请退避后重试。
`500` · `503` · `504`	服务器错误、维护中，或上游引擎超时。请退避后重试。

错误码目录

在 /v1 上最可能遇到的错误码。数字 code 在各版本间保持稳定。

错误码	HTTP	发生时机
1001	`401`	API 密钥缺失、无效或已吊销。
6014	`403`	账号没有有效订阅或已完成的积分购买 —— 没有 API 使用权限。
14001	`402`	钱包余额无法支付该任务。请充值，或查看 `GET /v1/credits`。
2001	`400`	某个字段校验失败（类型、范围或长度）。
2012	`400`	提示词或图像被内容策略拦截。
7002	`413`	上传超过 20 MB 上限。
7003	`400`	不受支持的上传格式。
13001	`404`	未知的资产 id，或该资产不属于你的密钥。
13005	`400`	重构网格的源必须是 AI 生成的模型 —— 上传的文件无法重构网格。
13008	`400`	动画的源无法绑定 —— 需要清晰的人形或动物形态。
10003	`429`	超出每 IP 或每用户的速率限制。
13002	`429`	进行中的生成已过多 —— 参见并发上限。不会扣费，待有空位后重试即可。
20001	`504`	生成引擎超时。可以安全重试。
20002	`429`	引擎容量暂时已满。请稍候片刻后重试。
20004	`400`	引擎拒绝了输入（例如无法处理的图像）。

处理方式

重试：429、500、503、504 采用指数退避重试 —— 从约 1 秒起，上限约 30 秒，共五次。
不要重试：400、401、403、404 不要重试，而应修正请求。
遇到 429 时请放慢调用频率：限制为每 IP 每分钟 240 次请求、每用户每分钟 120 次生成请求。
在 200 之后失败的任务（taskStatus: 3）会自动退还 —— 只对成功的生成计费。