错误处理与计费规则

请求错误与任务失败不是一回事

视频 API 的 HTTP 错误使用公开错误结构，例如参数校验失败：

{
  "error": {
    "message": "The request contains an invalid parameter.",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

以 HTTP 状态及公开 code 判断处理方式，不要匹配完整 message。部分参数错误还会返回 param、allowed_values 等修正线索。视频请求错误经过公开错误转换，不应依赖模型厂商的原始错误码。

已创建的视频任务后来失败时，查询请求本身可以成功（HTTP 200），但任务的 status 是 failed，任务内的 error 当前只保证 message。不要把它与 HTTP 错误的 type/code 结构混淆。

图片接口目前仍有与视频不同的错误封装路径，不能假定其 type/code 枚举已完全统一。客户端应保留未知错误分支，以 HTTP 状态和调用日志辅助排查；不要依赖供应商消息的具体措辞。

按状态处理

异步任务的常见错误码

异步图片任务（/v1/images/tasks）和模型任务（/v1/model-tasks）自受理起 15 分钟内没有结果就会判定失败；提交后 15 分钟仍未确认的任务（图片任务显示为 submitting 或 submission_unknown，模型任务显示为 queued）也会以 generation_timeout 失败，不会被重新提交。所以异步图片任务的轮询等待上限设为 20 分钟即可看到最终状态。

模型任务超过可同时运行的数量（你的账户同时运行的任务数有上限，平台整体也有上限）时不会被拒绝，而是先排队：状态为 queued，并带估计的排队位置 queue_position（1 表示下一个，位置会变化）。你自己的任务超过账户上限时，会按提交顺序等你的其他任务完成。提交后排队 5 分钟仍未开始的任务以 queue_timeout 失败并全额退款；排队中的任务可以用 POST /v1/model-tasks/{id}/cancel（同一把密钥）取消，取消后以 cancelled 失败并全额退款；任务已不在排队中（正在发出、已发出或已结束）时不能取消。因此模型任务的轮询等待上限设为 25 分钟。任务对象以后可能增加字段，客户端应忽略不认识的字段。

视频任务状态

删除接口是 DELETE /v1/videos/{id}：排队任务取消，已完成、失败或过期的任务记录删除后不能再查询；运行中和已取消的任务不能再次更改。成功返回 204。被拒绝时按实际 HTTP 状态和错误体处理，不要依赖某个厂商的删除错误码。

建议每 5 秒轮询一次，并设置单次等待上限。到达上限只停止客户端等待，任务可能仍在运行；保存任务 ID，之后继续 GET 查询，不要再次 POST 生成。

图片结果

图片能力有同步和异步两种执行方式，以能力 Schema 的 api.endpoint 和目录 generation.mode 为准。同步 POST /v1/images/generations 成功后处理全部 data[].url；异步 POST /v1/images/tasks 返回任务 id，再查询 GET /v1/images/tasks/{id}，完成后处理全部 data[].url。结果链接可能过期，异步任务可重新查询以获取新链接。页面关闭或链接过期不代表该次生成没有发生。

计费与重试边界

• 实际价格以当前能力目录为准。pricing.basis 为 usage 时按实际用量结算：有 pricing.usage 时按其单价（每 pricing.usage.unit）计费；没有 pricing.usage 时没有公开单价，按实际成本结算；有 pricing.tokens 时按其列出的 token 单价计费（每 100 万 token 的美元价格，只列出计费的种类：text_input、image_input、input、text_output、image_output、cache_read）。提交时冻结 pricing.prepayment（如有），amount 是单次请求最多冻结的金额。有 pricing.prepayment.scales_with 时按本次输入冻结：冻结 = scales_with.price × max(scales_with.field 字段的字符数, 1) ÷ scales_with.per，向上取整到 $0.000001，最多 amount；字符按 Unicode 字符计，与该字段 maxLength 的计数相同；请求带有未声明的顶层字段，或其他顶层文本超过 64 个字符且不是 enum/const 取值时，按 amount 冻结。没有 scales_with 时冻结 amount。余额须不低于 $0.01 与本次冻结金额中的较大者，否则请求因余额不足被拒绝。结算按实际用量：多余部分退回，超出部分全额从余额扣除，余额可能因此变为负数；余额为负时新请求暂停（返回 402），充值后先抵扣欠款。其他情况按 pricing.rules。不能把文档示例价格当作固定费率。
• 当前 Seedream 图片按张计量，Seedance 视频按输出 token 计量；其他模型接入后以各自规则为准。
• 按 token 计价时，计算为 output_tokens × price ÷ unit。像素对齐等口径见单能力 Schema 的 x-billing-basis。
• 确认被拒绝、确认生成失败或成功取消的排队任务不收生成费。
• 异步图片任务和模型任务自受理起 15 分钟内无结果、或提交后 15 分钟仍未确认，即判定失败（generation_timeout）并全额退回预扣；之后即使生成仍产生费用，也由平台承担。
• 生成服务暂时不可用、没有接受提交时，任务立即失败（upstream_unavailable）并全额退回预扣。
• 模型任务的输入被拒绝时，任务失败（invalid_parameters）并全额退回预扣。
• 模型任务排队期间被取消（cancelled）、排队超时（queue_timeout）、模型下线（model_unavailable_while_queued）或余额变负（insufficient_balance）时，任务从未发给模型，全额退回预扣。排队中的任务也已冻结金额：余额页会写明有多少金额冻结在进行中和排队中的请求里，没用完的部分会自动退回。
• 网络断开、客户端超时、停止轮询并不证明任务失败；生成可能已完成并结算。
• 多张图片应依据实际生成结果和账单核对，不按请求的最大张数直接认定费用。
• 视频完成与费用显示可能存在短暂延迟；响应中的最终结算值和调用日志是核对依据。

重试规则按接口区分：

• 异步图片任务 /v1/images/tasks、模型任务 /v1/model-tasks：提交是幂等的，任务 ID 就是你的 X-Request-Id。超时、连接失败、429 或 5xx 时，用同一个 X-Request-Id 原样重新提交：已提交的会返回原任务，不会重复生成或扣费。模型任务要求重发的请求体字节完全一致。任务已经失败（包括 generation_timeout、upstream_unavailable、invalid_parameters，以及模型任务的 cancelled、queue_timeout、model_unavailable_while_queued、insufficient_balance）时，同一个 ID 只会返回这条失败任务；重新生成要换一个新的 X-Request-Id。
• 视频 /v1/videos、同步图片 /v1/images/generations：不按请求 ID 去重，重发会新建并计费。已拿到视频任务 ID 时继续查询该 ID；没有拿到响应时先查看调用日志，确认结果再决定是否重新生成。

排查顺序

1. 在调用日志查模型、状态、费用和请求 ID。
2. 确认密钥有效、余额足够且有对应能力的权限。
3. 重新读取实时目录和该能力 Schema，检查参数与上下架状态。
4. 查询视频任务时使用创建时的同一把密钥。
5. 反馈问题附请求 ID；不要发送密钥或带签名的媒体链接。