Skip to Content
API 参考视频生成错误码

错误码

Video API 各端点的错误都使用同一个 JSON 结构：

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

HTTP 状态码表示问题的类别；error.code 是稳定的字符串标识，供程序分支判断。请始终按 error.code 匹配，不要解析 error.message 文案。

错误码表

HTTPcode含义
400invalid_request参数缺失或取值非法
400invalid_callback_urlcallback_url 非 HTTPS 或指向私网（被 SSRF 校验拦截）
400references_conflictframe_images 与 input_references 在同一请求中同时传（互斥）
400too_many_referencesinput_references 超出上限（图 > 9 / 音 > 3 / 视 > 1）
400cancel_not_supported上游 provider 不支持中断该任务
400cancel_failed任务已处于终态，无法取消
401unauthorized / invalid_api_key鉴权失败
401upstream_auth_failed上游供应商鉴权失败
402insufficient_credits余额不足，无法受理任务
404not_found任务不存在，或无访问权限
404model_not_found模型不存在
429rate_limited频率超限（轮询限流或上游限流）
502upstream_error / route_error上游供应商错误 / 路由失败
500internal_error内部错误

references_conflict 与 too_many_references 是请求体校验错误，具体上限见 创建视频任务。cancel_not_supported 与 cancel_failed 的判定见 取消任务。not_found 对”任务不存在”和”任务属于其他 API Key”两种情况统一返回——二者故意不作区分。

real_person 图片预处理错误

当 real_person: true 因传入图片问题导致预处理失败时，API 返回 HTTP 400，且 error.code 为 invalid_request。error.message 末尾会包含以下稳定原因短码，并标出出错引用位置，例如 input_references[0]：

原因短码处理方式
bad_data_uridata: URI 格式错误，或 base64 内容无效
download_failed因连接、超时或访问控制问题无法下载图片
unreachable图片 URL 返回非成功 HTTP 状态
not_image下载内容不是受支持且可解码的图片
too_large图片超过文件大小、像素数或单次请求的处理上限
{
  "error": {
    "code": "invalid_request",
    "message": "real_person image processing failed — input_references[0]: ... (not_image)"
  }
}

程序分支仍应判断 error.code；原因短码和引用位置用于修正输入或排查问题。

402 余额不足

insufficient_credits 仅在创建任务（POST /v1/videos）时返回。开启预扣后，ofox 会在受理任务前按请求的分辨率与时长预估费用；若预估额超过账户余额，请求会被立即拒绝——任务不会入库，也不会产生扣费。

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

Video API 的 402 只会返回 insufficient_credits 这一个 code。接入方处理这一个 code、充值后重试即可。

429 频率限制

rate_limited 同时覆盖 GET /v1/videos/{id} 的按 Key 轮询限流与上游限流。触发轮询限流时，响应会带 Retry-After 头：

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
 
{ "error": { "code": "rate_limited", "message": "..." } }

请尊重 Retry-After 头，退避后再重试。若轮询过于频繁，改用 Webhook 通知——由 ofox 在终态时主动推送，彻底避开轮询限流。创建任务（POST）与取消任务（DELETE）不受该轮询限流影响。

Last updated on
Webhook 通知