错误码速查

先区分请求失败和任务执行失败, 再查错误标识与具体说明. 同一个错误码可能对应多种情况, 例如 invalid_request 可能是图片尺寸不符合要求, 不能据此判断模型不支持图片输入.

从哪里读取错误

场景	判断方式	要读取的字段
OpenAI 格式的请求错误	HTTP 非成功状态或响应包含错误对象	`error.code`, `error.message`, 可选的 `error.param` 和 `error.type`
部分任务提交或查询接口的请求错误	HTTP 状态与响应体结合判断	顶层 `code`, `message`, `data`
任务执行失败	查询成功, 但任务 `status` 为 `failed`	`error.code`, 可选的 `error.reason`, `error.message`
任务 Webhook 失败事件	`type` 为 `generation.failed`, `data.status` 为 `FAILURE`	`data.error.code`, `data.error.message`
视频请求恢复	检查恢复记录的 `state`	可选的 `error_code`, `message`, `task_id`

请求错误示例, 文案仅用于说明:

{
  "error": {
    "code": "invalid_request",
    "type": "toapis_error",
    "param": "",
    "message": "Image dimensions or aspect ratio do not meet this model's requirements."
  }
}

任务执行失败示例:

{
  "id": "task_example",
  "object": "generation.task",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "reason": "image_dimensions_multiple",
    "message": "Image dimensions must be multiples of 16."
  }
}

第二个示例中的倍数只用于展示一种具体约束, 不适用于所有模型. 查询返回 HTTP 200 表示查询成功, 仍需检查任务状态. 数字业务 code 也不等于 HTTP 状态码; 返回 success: false 的接口需要检查响应体. code 用于识别错误, reason 在提供时补充任务失败类别, message 用于阅读具体情况. error.type 是错误类型, 不一定等于错误码. 文案可能随语言变化, 不要通过完整匹配 message 控制业务逻辑. 部分鉴权响应的 code 为空, 部分协议只有 type 和 message.

请求错误速查

下表列出公开请求可能遇到的标识, 并非每个接口都会返回全部标识. 不同模型也可能保留不同的原始拼写. 字段位置按上表中的响应格式读取.

错误标识	可能的情况	建议操作
`invalid_request`, `invalid_request_error`, `invalid_params`, `InvalidParameter`, `invalid_parameter_error`, `invalid_value`	参数类型, 图片尺寸, 素材读取, 消息结构或参数组合不合法	根据 `param` 和 `message` 定位字段, 参考下方具体情况; 修改输入后再提交
`invalid_json`, `invalid_multipart_form`, `read_request_body_failed`	JSON 或表单无法解析, 请求体读取失败	检查序列化结果, `Content-Type` 和上传是否完整
`unknown_parameter`, `unsupported_value`, `provider_capability_not_supported`, `not_supported`	模型不接受某个字段, 参数值, 工具或接口能力	检查精确模型的接口说明; 移除不支持的字段或使用支持该能力的模型
`missing_model`, `model_not_found`, `unsupported_model`, `DeploymentNotFound`	缺少模型名, 模型不可访问, 当前入口不支持, 或服务暂不可用	核对模型目录和 API Key 权限. 模型名正确但文案提示暂不可用时, 稍后重试或联系支持
`invalid_private_assets`, `invalid_image`, `invalid_image_file`	素材引用无效, 图片无法解码, 数量或尺寸超限, 或链接无法读取	检查具体素材的位置和限制; 重新导出或上传后再提交
`access_denied`, 或 HTTP 401/403 且无 code	API Key 无效, 过期, 停用, IP 或模型权限受限	检查 API Key 和访问权限. 不要把服务返回的认证错误一律理解为本地密钥错误
`insufficient_user_quota`, `quota_not_enough`, `token_quota_not_enough`, `pre_consume_token_quota_failed`	账户余额, 令牌可用额度或周期限额不足; 令牌额度检查也可能临时失败	只有文案明确指向本账户或令牌时才充值或调整额度. 服务侧额度问题或检查失败应稍后重试或联系支持
`rate_limit_exceeded`, `RateLimitReached`, `rate_limit_unavailable`	请求频率超限, 模型服务限流, 或暂时无法检查限额	降低并发, 优先遵守 `Retry-After`, 再使用带随机抖动的退避. 见异步限流
`get_channel_failed`, `all_channels_circuit_broken`, `provider_unavailable`	当前模型暂时没有可用服务或负载过高	稍后重试; 持续失败时联系支持, 不需要修改图片内容
`do_request_failed`, `first_output_timeout`, `up_timeout`	连接, 等待首段输出或读取响应超时; 请求可能已被受理	有任务 ID 时先查询该任务; 无 ID 的视频请求按下方恢复流程处理
`bad_response_status_code`, `bad_response`, `bad_response_body`, `read_response_body_failed`, `upstream_error`, `unknown_error`	服务返回错误或响应无法读取, 解析	结合 HTTP 状态和文案判断. 先确认是否已有任务, 持续失败时提供请求 ID 联系支持
`convert_request_failed`, `model_price_error`, `pricing_failed`, `pricing_unavailable`, `internal_error`	请求转换, 定价或服务处理失败, 不一定是输入错误	文案有明确字段约束时修正输入; 否则稍后重试或联系支持
`task_not_found`, `task_not_exist`, `request_not_found`	任务或恢复记录不存在, 不属于当前账号, 或恢复记录已过期	核对 ID, 账号和查询入口. 恢复记录不存在不能证明原请求从未执行
`invalid_client_request_id`, `request_cache_unavailable`, `submission_unconfirmed`	恢复标识无效, 恢复服务不可用, 或提交结果尚未确认	修正标识格式, 或等待并查询原请求; 不要连续生成新 ID 重提
`invalid_callback_url`, `callback_url_origin_mismatch`, `webhook_not_configured`, `webhook_configuration_invalid`, `webhook_configuration_unavailable`, `webhook_configuration_error`, `webhook_api_token_required`	回调地址或 Token 的 Webhook 配置不满足要求, 或配置暂不可读取	按任务 Webhook检查 HTTPS 地址, 来源, API Token 和配置
`sensitive_words_detected`, `prompt_blocked`, `content_policy_violation`, `content_filter`, `content_filtered`	输入或生成结果未通过内容审核	检查提示词和全部参考素材, 修改合规内容后再提交; 不要自动重复原请求
`invalid_encrypted_content`	对话返回项中的加密内容无法验证或解析	检查客户端是否修改或截断了历史返回项, 保持此类项原样. 持续失败时联系支持, 不要尝试修改加密内容

invalid_request 可能具体指什么

以下情况来自实际请求和失败任务的诊断归纳. 它们可能由上述通用参数码包裹, 也可能以更具体的 reason 或模型原始错误码返回. 先看具体字段和说明, 再决定修改什么.

具体情况	如何区分和修正
输出尺寸或比例写法不匹配	某些模型的 `size` 接受 `1:1` 等比例, 某些接受像素尺寸. 把 `1024x1024` 传给只接受比例的模型会失败. 按所选模型的 `size`, `resolution`, `aspect_ratio` 定义传值
宽高, 总像素或尺寸倍数不符合要求	图片可能太小, 太大, 比例过宽, 或宽高不是要求的倍数. 区分报错指向参考图还是输出尺寸, 按该模型限制缩放或裁剪; 不是所有模型都使用同一倍数或像素上限
参考图文件或图片数量超限	文件字节数, 长边像素, 总像素和图片数量是不同限制. 文件压缩只能减少字节数, 未必降低像素数. 根据报错选择压缩, 缩放或减少图片
图片字段类型错误	接口需要 URL 字符串数组时, 传入对象数组会解析失败. `image_urls` 与 `image_with_roles` 的结构不同, 某些入口也不接受 Base64 或混用两种字段
URL 存在但服务读不到文件	403/404, 需要登录, 链接过期, 下载超时, 防盗链或返回 HTML 页面都可能失败. 提供足够长时间有效, 可直接下载真实文件的公网 URL, 或先使用上传接口
素材格式或时长不满足要求	文件扩展名正确不代表内容可解码. GIF, 视频编码, 帧率, 单段或总参考时长可能不符合所选模型要求. 按模型文档重新导出媒体
Seedance 任务类型与参数冲突	被识别为视频编辑时, 可能要求 `aspect_ratio=adaptive`, `duration=-1`; 延长任务也可能要求 `adaptive`. `InvalidParameter.TaskTypeConstraint` 也可能表示提示词和素材被识别成另一任务类型. 见Seedance 2.5
文本, 对话历史或工具调用结构错误	提示词超长, 模型不接受 `developer` 角色, `tool_calls` 缺少对应工具回复, 或思考模式缺少必要的 `reasoning_content`. 按该模型协议修正历史结构
参数存在但当前模型不接受	`quality`, `reasoning_effort`, `temperature`, `thinking`, `enable_thinking` 等取值或字段并非通用. `max_tokens` 与 `max_completion_tokens` 也可能互斥. 工具 Schema 和 `response_format` 需符合所选模型约束

历史失败中的具体数值不是全平台限制. 能否传图片要看模型是否支持该输入, 不能仅根据 invalid_request 或 invalid_image 推断.

任务失败原因速查

任务已返回 ID 后, 以查询状态为准. 普通生成任务失败常见 error.code=generation_failed, 具体分类读取可选的 error.reason. 以下标识是 reason, 不应假定它们都出现在请求错误的 code 字段. 若响应提供 error.input_media_errors, 逐项读取 type, index, message. 例如 type=image, index=0 指向原请求的第一张图片, 可以只修正该素材. 这些明细不是所有模型或查询格式都提供.

error.reason	可能的情况与处理
`invalid_input`, `missing_parameter`	输入未通过校验或缺少字段. 检查上方具体情况和错误文案, 修正后重新生成
`reference_image_too_large`, `image_dimensions_multiple`	参考图文件过大, 或图片尺寸不符合倍数要求. 分别检查文件大小和像素尺寸
`reference_media_unreadable`, `unsupported_media_format`	URL 无法下载, 文件无效或格式不支持. 检查访问权限和真实媒体内容
`unsupported_parameter_value`, `parameter_out_of_range`, `parameter_replacement_required`	值不在允许集合或范围, 或需要替换字段. 根据返回文案和模型说明修改
`video_edit_parameters_required`, `unsupported_request_capability`	视频编辑参数组合不合法, 或模型不支持所请求能力. 调整任务类型, 参数或模型
`content_policy_rejected`	提示词, 参考图片/视频/音频, 或生成输出未通过安全或版权审核. 检查全部输入; 合规输入也可能因输出审核而失败
`service_busy`, `request_rate_limited`	服务繁忙或限流. 等待并降低请求频率
`generation_timeout`	等待生成或任务处理超时. 先确认已有任务状态, 不要在仍处理中时反复重新生成
`generation_unavailable`, `model_unavailable`, `model_region_unavailable`	当前模型服务暂不可用, 或当前访问区域不支持. 核对模型与权限, 持续异常时联系支持
`insufficient_user_balance`, `token_quota_exceeded`	本账户余额或 API Token 额度不足. 检查两者及周期限额后再提交
`result_storage_failed`	生成结果保存或交付失败, 不一定是生成模型不支持输入. 提供任务 ID 联系支持
`submission_pending_reconciliation`	提交或生成结果仍待核实. 保留已有 ID 并等待查询结果, 避免重复生成
`refund_pending`	失败任务退款尚在处理. 查看最新查询中的可用计费状态, 持续异常时联系支持
`request_cancelled`	请求或任务被取消. 确认取消是否符合预期后再决定重新提交
`generation_failed`, `service_error`	没有更具体的公开原因, 或服务内部处理失败. 保留任务和请求 ID, 联系支持

部分模型保留原始错误, 如 InvalidParameter.TaskTypeConstraint, RateLimitReached, InputImageSensitiveContentDetected 或 OutputVideoSensitiveContentDetected. 这些取值不是完整枚举, 分别可能涉及任务参数, 服务限流, 输入审核或输出审核. Seedance Global 查询的 error.code 和 error.message 可能是原始 JSON 值, 包括数字或 null, 也可能缺省. OpenAI 视频格式和 Webhook 不保证提供 reason. 客户端应容忍未知码, 缺省字段和不同字段类型; 不要把原始数字 code 当作 HTTP 状态.

重试与请求恢复

参数, 格式和内容审核问题: 修改输入后再提交. 原样重试通常不能解决.
限流或暂时不可用: 有 Retry-After 时优先遵守; 否则使用指数退避和随机抖动, 避免无限重试.
已有任务 ID: 继续查询该任务, 或接收任务 Webhook. queued 和 in_progress 不表示失败, 不要因此创建重复任务.
视频提交超时或返回 submission_unconfirmed: 如果原请求使用了 client_request_id, 用同一账号调用 GET /v1/video/requests/{client_request_id}. 得到 task_id 后查询任务; submitting 或 unknown 表示继续等待. 只有恢复记录明确为 failed 且 error_code=submission_rejected 时, 才表示该请求已被明确拒绝, 可按提示发起新请求. 此恢复能力只适用于支持并使用了该字段的视频入口, 不适用于所有 API.

失败任务不一定立即完成退款. 查询计费状态中的可用 billing 字段; 字段缺省不代表免费或退款完成. Webhook 是事件快照, 不保证与后续查询的计费字段完全相同.

联系支持时提供什么

提供请求时间和时区, 模型名, 接口路径, HTTP 状态, 请求 ID, 可用的任务 ID, 错误 code/reason 和脱敏后的具体说明. 图片问题附上尺寸, 格式和文件大小即可. 不要提供 API Key, 签名 URL, 完整提示词或私人素材; 需要复现时使用可公开的最小示例.

快速上手

模型目录

文本对话系列

图像系列

视频系列

音乐系列

任务管理

文件上传

账户

常见问题

从哪里读取错误

请求错误速查

invalid_request 可能具体指什么

任务失败原因速查

重试与请求恢复

联系支持时提供什么

​从哪里读取错误

​请求错误速查

​invalid_request 可能具体指什么

​任务失败原因速查

​重试与请求恢复

​联系支持时提供什么

从哪里读取错误

请求错误速查

invalid_request 可能具体指什么

任务失败原因速查

重试与请求恢复

联系支持时提供什么