错误与额度

错误响应结构、常见错误码，以及免费积分生成的处理方式。

错误格式

所有错误均使用相同的 JSON 外层结构：

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Required 10 credits, available 4, missing 6. Choose lower-cost settings to continue."
  }
}

code 是稳定字段，可以用于程序分支判断；message 是供人阅读的说明，内容可能变化。

错误码

HTTP	错误码	触发情况	处理方式
`400`	`INVALID_INPUT`	请求体验证失败，例如缺少提示词、枚举值无效，或非 pro 模式启用音频。	修正请求，错误说明会指出相关字段。
`404`	`JOB_NOT_FOUND`	任务 ID 不存在，或不属于当前密钥/浏览器会话。	检查创建任务时保存的 ID。
`402`	`INSUFFICIENT_CREDITS`	当前免费积分和其他积分余额不足以支付服务器报价。	领取符合条件的免费积分，或选择费用更低的设置。
`403`	`CHALLENGE_REQUIRED`	生成风控检测到独立的高风险信号。	完成服务器要求的安全验证，并使用同一个幂等键重试。
`429`	`GENERATION_COOLDOWN`	高频请求与强独立风险信号触发了模型专属冷却。	等待冷却结束，重复请求不会延长冷却时间。
`502`	`CREATE_JOB_FAILED`	生成流程拒绝或未能受理任务。	属于暂时性问题，可采用指数退避重试。
`500`	`UNKNOWN_ERROR`	服务端出现预期外的问题。	重试一次；如仍存在，请联系我们。

任务受理之后的失败不使用此错误结构。任务本身会变为 status: "failed"，原因写在 errorMessage 中，详见任务生命周期。

免费积分

符合条件的访客与已登录用户需手动领取免费积分。
免费积分在下一个 UTC 零点到期，并优先于其他积分扣除。
服务器根据模型、时长、分辨率、音频及支持的视频特征参考选项计算费用。
已受理但失败或取消的任务，会按原积分来源退回；免费积分退款不会变成付费积分。

可以采用以下清晰的集成方式：

const res = await fetch(`${BASE}/api/ai-video/jobs`, { method: 'POST', headers, body });

if (res.status === 402) {
  const { error } = await res.json();
  if (error.code === 'INSUFFICIENT_CREDITS') {
    // retain the draft and ask the user to claim or lower the quoted cost
  }
}

免费额度不够用？请联系我们，我们会协助安排合适的生成量。

错误格式

所有错误均使用相同的 JSON 外层结构：

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Required 10 credits, available 4, missing 6. Choose lower-cost settings to continue."
  }
}

code 是稳定字段，可以用于程序分支判断；message 是供人阅读的说明，内容可能变化。

错误码

HTTP	错误码	触发情况	处理方式
`400`	`INVALID_INPUT`	请求体验证失败，例如缺少提示词、枚举值无效，或非 pro 模式启用音频。	修正请求，错误说明会指出相关字段。
`404`	`JOB_NOT_FOUND`	任务 ID 不存在，或不属于当前密钥/浏览器会话。	检查创建任务时保存的 ID。
`402`	`INSUFFICIENT_CREDITS`	当前免费积分和其他积分余额不足以支付服务器报价。	领取符合条件的免费积分，或选择费用更低的设置。
`403`	`CHALLENGE_REQUIRED`	生成风控检测到独立的高风险信号。	完成服务器要求的安全验证，并使用同一个幂等键重试。
`429`	`GENERATION_COOLDOWN`	高频请求与强独立风险信号触发了模型专属冷却。	等待冷却结束，重复请求不会延长冷却时间。
`502`	`CREATE_JOB_FAILED`	生成流程拒绝或未能受理任务。	属于暂时性问题，可采用指数退避重试。
`500`	`UNKNOWN_ERROR`	服务端出现预期外的问题。	重试一次；如仍存在，请联系我们。

任务受理之后的失败不使用此错误结构。任务本身会变为 status: "failed"，原因写在 errorMessage 中，详见任务生命周期。

免费积分

符合条件的访客与已登录用户需手动领取免费积分。
免费积分在下一个 UTC 零点到期，并优先于其他积分扣除。
服务器根据模型、时长、分辨率、音频及支持的视频特征参考选项计算费用。
已受理但失败或取消的任务，会按原积分来源退回；免费积分退款不会变成付费积分。

可以采用以下清晰的集成方式：

const res = await fetch(`${BASE}/api/ai-video/jobs`, { method: 'POST', headers, body });

if (res.status === 402) {
  const { error } = await res.json();
  if (error.code === 'INSUFFICIENT_CREDITS') {
    // retain the draft and ask the user to claim or lower the quoted cost
  }
}

免费额度不够用？请联系我们，我们会协助安排合适的生成量。

错误格式

错误码

免费积分

目录

错误与额度

错误格式

错误码

免费积分

目录