计费与错误码

积分在提交任务时扣除，任务失败自动退回。本文说明计费口径、退款规则，以及各种错误码的含义与排查方向。

计费方式

计费公式

text

积分 = 向上取整（ 计费秒数 × 每秒单价 × 分辨率倍率 × 视频编辑倍率 ）× 客户折扣

各项含义：

因子	说明
计费秒数	默认取请求里的 `duration`。`vipro-main2.5` 带视频输入时口径不同，见下。
每秒单价	按模型分别配置，以控制台展示为准。
分辨率倍率	按 `resolution` 取值乘以对应倍率（480p / 720p / 1080p 三档）。不传或传了无法识别的值时倍率为 1。
视频编辑倍率	仅当请求带视频输入（编辑类任务）时生效。
客户折扣	按账号配置的折扣系数，未配置时为原价。

duration 与 resolution 会直接放大费用。resolution 写错（例如写成 720P 而不是 720p、或写了个上游不认的值）不会报错，但倍率会按 1 计算 —— 这可能与实际出片分辨率不一致，建议统一用小写。

2.5 的计费口径

vipro-main2.5 在带视频输入时按「输入秒数 + 输出秒数」计费，且不再叠加视频编辑倍率（输入侧已单独计入）。详细公式与示例见参考模式 · 计费影响。

最容易踩的坑：2.5 带视频输入时若未传 source_duration_seconds，输入侧按 30 秒上限兜底计费，费用会显著高于预期。

在哪里看消耗

每次提交的响应头 x-credits-consumed 与 x-credits-remaining，可即时读取。
用户控制台的用量明细，可按任务号对账。

失败退款

任务在生成阶段失败时，系统会自动把本次已扣积分退回，不需要调用方申请、也不需要人工介入。

失败发生的位置	表现	是否扣费
提交阶段（参数非法、余额不足、鉴权失败）	直接返回 4xx，不产生任务	不扣费
生成阶段（内容审核未过、上游异常、超时）	轮询返回 `status: "failed"` / `expired`	先扣后退，自动退款

退款窗口为 24 小时。 超过 24 小时后才查询到的失败结果不再退款，此时 error 会变成 Task failed after 24h billing window。请务必在任务提交后 24 小时内完成轮询。

退款是幂等的：同一任务多次轮询到失败，也只会退款一次。

限流

项目	说明
接口请求频率	有全局限流，超出返回 `429`。按建议的 5 秒间隔轮询远低于阈值，正常使用不会触发。
任务并发	提交任务本身不受并发额度限制，可以连续提交多个任务，由服务端排队执行。

收到 429 时请退避重试：等待数秒后再发起请求，不要立即密集重试，否则会持续被限流。轮询场景建议固定 5 秒间隔。

429 响应体：

json · 429

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 1 minute"
}

上面的响应体是限流插件的标准格式，与你可能在其他接口见过的并发超限提示不同 —— 视频生成接口不限制同时进行的任务数。

HTTP 错误码

状态码	典型 `error` / `code`	原因与处理
`400`	`Insufficient credits`	账户积分不足。充值或降低分辨率 / 时长后重试。
`400`	`source video duration must be between 4 and 30 seconds`	2.5 的编辑 / 延长模式下 `source_duration_seconds` 超出范围。
`500`	`Adapter upstream error: ...`	上游拒绝了请求或无法连通。响应体的 `response` 字段里有上游返回的原始内容，按它排查。
`401`	`missing_api_key`	没有携带 API Key。检查 `Authorization: Bearer <key>` 是否漏写或格式错误。
`401`	`invalid_api_key`	API Key 不存在。确认 Key 复制完整、没有被换行或空格截断。
`403`	`api_key_disabled`	该 API Key 已被禁用。到控制台检查 Key 状态。
`404`	`Task not found`	任务号不存在、已过 7 天保留期，或用了另一个账号创建的任务号。
`429`	`Too Many Requests`	请求过于频繁，触发全局限流。退避数秒后重试，并检查轮询间隔是否过密。
`500`	含 `code` / `detail` / `response`	上游异常或素材审核失败。错误体里带上游详情，可用于定位。

500 响应的结构

素材审核或上游异常时，错误体会尽可能带上现场信息：

json · 500

{
  "error": "TR-SD asset upload failed: ...",
  "code": "TR_SD_ASSET_UPLOAD_FAILED",
  "detail": { "...": "上游返回的失败详情" },
  "response": { "...": "上游原始响应体" }
}

素材相关的错误码：

`code`	含义
`TR_SD_ASSET_UPLOAD_FAILED`	人物素材入库失败。通常是素材无法被上游抓取，或素材中的人脸不符合要求。
`VOLC_ACTION_ASSET_UPLOAD_FAILED`	素材上传到审核服务失败。
`VOLC_ACTION_ASSET_STATUS_QUERY_FAILED`	素材审核状态查询失败，通常是上游暂时不可用，可稍后重试。
`VOLC_ACTION_GROUP_CREATE_FAILED`	素材组创建失败。

code / detail / response 三个字段只在有值时才出现，不是每个错误都有。

上游失败码

任务提交成功后，生成阶段的失败通过轮询响应里的 error.code 表达：

`error.code`	含义	处理
`OutputVideoSensitiveContentDetected`	输出视频命中内容安全策略。	调整提示词或素材后重试。已自动退款。
`InvalidParameter.TaskTypeConstraint`	带视频输入的请求被判为编辑类，但 `ratio` / `duration` 不符要求。	见参考模式：显式声明 `reference_mode`。已自动退款。
其他上游错误码	由上游模型返回，含义以 `error.message` 描述为准。	按 message 提示调整参数。若持续复现，带上任务号联系技术支持。

排查清单

任务一直停在 running

视频生成本身需要数十秒到数分钟，请耐心轮询，间隔 5 秒即可。
超过 30 分钟仍未终态，按超时处理并停止轮询；该任务会被上游置为 expired 并自动退款。

提交成功但很快失败

先看 error.code：内容安全类命中需要改提示词，参数类按 message 调整。
2.5 带视频输入的任务，先确认 reference_mode 有没有传对。

扣费比预期高

检查 resolution：1080p 的倍率明显高于 720p。
检查 duration：计费按请求时长，不是实际出片时长。
2.5 带视频输入：检查 source_duration_seconds 有没有漏传（漏传按 30 秒兜底）。

拿到的视频打不开

结果链接是带签名的临时地址，约 24 小时失效。请及时下载转存。
不要对结果链接做二次代理或长期缓存 URL 本身。