通用视频接口 · OpenAI 格式

错误码

OpenAI 格式的接口出错时，返回 HTTP 4xx 或 5xx 状态码和错误对象，格式与 OpenAI 相同，OpenAI SDK 会把它转成异常。

错误格式

返回结果是一个 error 对象，例如 Seedance 2.0 Fast 传了 1080p：

{
  "error": {
    "message": "模型 doubao-seedance-2-0-fast-260128 支持的分辨率：480p、720p",
    "type": "invalid_request_error",
    "code": "unsupported_resolution",
    "request_id": "5oAolP1vT0aPGNVd"
  }
}

字段	说明
`message`	错误信息，说明具体原因
`type`	错误类型，和 HTTP 状态码对应，见下表
`code`	错误码，见错误码列表
`request_id`	请求 ID，和响应头 `X-Request-ID` 相同，反馈问题时请提供

HTTP 状态码	type
400	`invalid_request_error`
401	`authentication_error`
402	`insufficient_quota`
403	`permission_error`
404	`invalid_request_error`
409	`invalid_request_error`
429	`rate_limit_error`
500	`server_error`
503	`server_error`

错误码列表

HTTP 状态码	code	说明
400	`invalid_bodybody_too_largeinvalid_argument`	请求体不是合法的 JSON 或 multipart/form-data、超过 32 MB，或者参数的类型不对
400	`model_requiredprompt_requiredprompt_too_long`	没有传 model；当前生成方式需要提示词；提示词超过字数上限
400	`invalid_secondsunsupported_secondsinvalid_size`	时长或 size 的格式不对，或者模型不支持这个时长
400	`unsupported_resolutionunsupported_aspect_ratiounsupported_audiounsupported_parameter`	模型不支持这个分辨率、画幅、声音设置，或者不支持 negative_prompt、seed
400	`unsupported_modeinvalid_task_type`	模型不支持这种生成方式，或者 omni_reference_task_type 的取值不对
400	`invalid_imageimage_too_largeunsupported_imageduplicate_image`	图片无法识别、超过 10 MB、格式不支持，或者同时传了 input_reference 和 first_frame
400	`first_frame_requiredframes_with_referencesreference_requiredreference_video_required`	只有尾帧没有首帧、首尾帧和参考素材混用，或者缺少当前生成方式需要的参考素材
400	`too_many_referencesreference_video_too_longinvalid_reference_videoinvalid_reference_audioreference_too_large`	参考素材超过模型的上限，或者参考视频、音频无法读取、格式不对、太大
400	`content_policy_violation`	提交时被模型的内容审核拦截，message 里有具体原因
400	`invalid_request`	请求的参数或素材不被模型接受，message 里有具体原因
400	`invalid_limitinvalid_orderinvalid_cursorunsupported_variant`	视频列表或下载视频的查询参数不对
401	`invalid_api_key`	缺少 API Key，或者 API Key 无效
402	`insufficient_balance`	账户余额不足，充值后重试
403	`api_key_disabledapi_key_expired`	API Key 已禁用或已过期
403	`api_key_quota_exceeded`	API Key 的额度已用完，可以在控制台 → API Keys调高额度
403	`model_not_allowedip_not_allowedaccount_disabled`	API Key 不能使用这个模型、请求的 IP 不在 API Key 的白名单里，或者账号已被禁用
404	`model_not_found`	模型不存在或已下线
404	`video_not_foundroute_not_found`	视频不存在或不属于当前账号，或者接口路径写错了
409	`video_not_ready`	视频还没有生成完成，不能下载
429	`too_many_requests`	请求过于频繁，按 Retry-After 响应头给出的秒数等待后重试
429	`channels_busy`	当前排队的任务较多，稍后重试
500	`internal_error`	服务内部错误，稍后重试；多次失败时请带上 request_id 联系客服
503	`no_available_channelupstream_unavailable`	模型暂时没有可用资源，或者模型服务暂时不可用，稍后重试

创建接口返回错误时不扣费。429、500 和 503 可以稍后重试，其他错误需要先按 message 修改请求，原样重试仍会失败。视频生成失败时的错误码见查询视频的失败原因。

处理错误

OpenAI SDK 收到错误响应时抛出 openai.APIStatusError（及其子类），可以从中取出 HTTP 状态码、错误码、错误信息和 request_id：

捕获错误

import os

import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://your-domain/v1",
    api_key=os.environ["API_KEY"],
)

try:
    video = client.videos.create(
        model="doubao-seedance-2-0-260128",
        prompt="清晨的海边，一只金毛犬沿着浪花奔跑，镜头缓慢跟随，阳光穿过薄雾",
    )
    print(video.id, video.status)
except openai.APIStatusError as e:
    # e.body 是返回结果里的 error 对象
    print(e.status_code, e.code, e.body["message"])
    print("request_id:", e.request_id)

SDK 默认会对 409、429 和 5xx 自动重试 2 次，重试仍失败才抛出异常；可以在创建客户端时用 max_retries 调整。
没有收到返回结果的网络错误（超时、连接失败等）抛出 openai.APIConnectionError，没有错误码，需要单独处理。