参考模式（Seedance 2.5）

本文说明 vipro-main2.5 上两个可选声明字段。视频编辑与视频延长两个模型都支持；这两个字段只是在 2.5 上把意图提前讲清楚，避免任务在提交成功之后才异步失败。传给 vipro-main 会被忽略。

一句话版本：在 vipro-main2.5 上带视频输入时，加上 "reference_mode": "edit"（或 extend）以及 "source_duration_seconds": <源视频秒数> 即可。

为什么需要这两个字段

vipro-main2.5 对「带视频输入」的请求，会在受理之后由模型根据提示词语义判定任务类型。三类任务对参数的要求不同：

任务类型	判定条件	`ratio`	`duration`
参考生视频	至少 1 个参考图/视频/音频	无限制	无限制
视频编辑	有参考视频 + 提示词表达编辑意图	必须 `adaptive`	必须 `-1`
视频延长	有参考视频 + 提示词表达延长意图	必须 `adaptive`	无限制

参数不符时的实际表现 —— 注意不是创建时报错：

提交任务 → 返回 200 + 任务号（正常扣费）
约 1~2 分钟后轮询 → 返回 status: "failed"，错误码 InvalidParameter.TaskTypeConstraint

json · 轮询到失败

{
  "id": "task_xxxx",
  "status": "failed",
  "error": {
    "code": "InvalidParameter.TaskTypeConstraint",
    "message": "The parameters `ratio` and `duration` specified in the request are not valid. Seedance identified your task as video editing based on your prompt. For this task type, the output ratio and duration follow the input video selected by the model for editing, and the video selected must satisfy the duration requirement of 4 to 30 seconds. Issues: [0] `ratio` must be `adaptive`. [1] `duration` must be -1."
  }
}

失败会自动退款，但调用方白等 1~2 分钟，且这一次任务永远不会产出结果。 编辑类的输出比例与时长跟随模型选中的那个源视频，请求里传的 duration 会被忽略。

新增字段

字段	类型	必填	说明
`reference_mode`	string	建议必传	带视频输入时三选一：`generate` / `edit` / `extend`。
`source_duration_seconds`	number	建议必传	待编辑 / 待延长那个源视频的时长（秒）。是「模型将要选中的那个视频」（通常是提示词里的「视频1」），不是所有参考视频的合计。

字段名与 content[].video_url 里的素材元信息不是同一个东西，不要混用。后者描述素材本身，前者是这次任务的计费与校验依据。

三种模式对照

`reference_mode`	你传什么	网关做什么	计费依据
`generate`	`duration` 照常传期望时长，`ratio` 随意	不改任何参数	`duration`
`edit`	`duration` 可以省略（会被覆盖为 `-1`），`ratio` 随意	强制 `ratio=adaptive`、`duration=-1`	`source_duration_seconds`
`extend`	`duration` = 延长多少秒（必传、原样转发）	仅强制 `ratio=adaptive`	`source_duration_seconds` + `duration`
不传	—	不改任何参数（等同现状）	`duration`

edit 模式下 duration 传了也会被覆盖，建议不传，避免歧义。

计费影响

vipro-main2.5 按「输入秒数 + 输出秒数」计费（输入 = 参考/源视频，输出 = 本次生成的视频）。两项各自向上取整后相加。分辨率倍率照常生效。具体单价以控制台展示为准。

参考模式	输入秒数	输出秒数	计费秒数
`edit`	`source_duration_seconds`	跟随源视频（= 输入秒数）	2 × 源视频时长
`extend`	`source_duration_seconds`	`duration`（延长量）	源视频时长 + 延长量
`generate`	`source_duration_seconds`（如有参考视频）	`duration`	参考视频时长 + `duration`
无视频输入（纯文 / 纯图）	0	`duration`	`duration`

举例：源视频 4.08 秒的编辑任务 → 输入取整 5 + 输出取整 5 = 10 秒计费。

务必传 source_duration_seconds，不要省略。 字段缺失或非法（未传、null、空串、非数字、≤ 0）时， 输入侧按上限 30 秒计费。这是有意设计的商务口径：宁可多收后退，不可漏收。

取不到精确时长时，也请传一个尽量接近的值，不要留空。

校验规则

情况	网关行为
`source_duration_seconds` 不在 4 ~ 30 之间	提交时直接 400 拒绝，不提交上游、不扣费
字段缺失或非法	不拒绝，按 30 秒兜底计费
`reference_mode` 传了非法值	等同于未传（不改写、不校验）

400 响应：

json · 400

{ "error": "source video duration must be between 4 and 30 seconds" }

这条校验是有意加的：2.5 的编辑类要求源视频必须在 4~30 秒，低于 4 秒的任务即使参数全对也必定失败。提前拒绝可以省掉一次必然失败的任务和 1~2 分钟等待。

请求示例

视频编辑（源视频 6 秒）

注意 duration 不传。

json

{
  "model": "vipro-main2.5",
  "reference_mode": "edit",
  "source_duration_seconds": 6,
  "resolution": "720p",
  "generate_audio": false,
  "content": [
    { "type": "text", "text": "把@视频2贴到@视频1的绿幕处，保持@视频1的变焦，其他严格保持不变" },
    { "type": "image_url",
      "image_url": { "url": "https://your-cdn.com/ref.jpg" },
      "role": "reference_image" },
    { "type": "video_url",
      "video_url": { "url": "https://your-cdn.com/a.mp4" },
      "role": "reference_video" },
    { "type": "video_url",
      "video_url": { "url": "https://your-cdn.com/b.mp4" },
      "role": "reference_video" }
  ]
}

参考生视频

不需要任何改动，但建议显式声明以便对账。

json

{
  "model": "vipro-main2.5",
  "reference_mode": "generate",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "content": [
    { "type": "text", "text": "镜头缓慢推近，人物转头看向窗外" },
    { "type": "image_url",
      "image_url": { "url": "https://your-cdn.com/person.jpg" },
      "role": "reference_image" }
  ]
}

视频延长（源视频 10 秒，延长 4 秒）

此时 duration 的语义是「延长多少秒」。

json

{
  "model": "vipro-main2.5",
  "reference_mode": "extend",
  "source_duration_seconds": 10,
  "duration": 4,
  "resolution": "720p",
  "content": [
    { "type": "text", "text": "从原视频结尾自然延长4秒，画面风格保持一致" },
    { "type": "video_url",
      "video_url": { "url": "https://your-cdn.com/src.mp4" },
      "role": "reference_video" }
  ]
}

兼容性

两个字段都是可选的。不传 = 行为与现在完全一致（2.5 的编辑类仍会失败并自动退款）。
非 2.5 模型完全不受影响。传给 vipro-main 会被忽略，参数与计费都不变。因此可以无条件对所有请求都带上这两个字段，无需在调用方按模型分支。
不影响轮询接口、任务号、响应结构、失败退款逻辑。

排错

现象	原因与处理
轮询仍返回 `InvalidParameter.TaskTypeConstraint`	① `reference_mode` 没传或传了非法值；② 用的不是 `vipro-main2.5`（字段被忽略）；③ 传了 `edit` 但源视频实际不足 4 秒 —— 检查 `message` 里 `Issues` 是否提示 `content[N].video_url is X seconds`
提交时 400 `source video duration must be between 4 and 30 seconds`	`source_duration_seconds` 超出 4~30。请核对该值是否为「模型将要选中的那个源视频」的时长
扣费比预期高很多	大概率是 `source_duration_seconds` 缺失，走了 30 秒兜底
输出比例 / 时长与请求不符	编辑类的输出跟随源视频，这是模型规则，不是网关改写导致的

补充说明

任务类型由模型在受理后根据提示词语义判定，网关与调用方都无法提前得知。因此：

同一段提示词在 vipro-main 上可能成功、在 vipro-main2.5 上被判为编辑而失败。
网关不会解析上游错误文案做自动修正 —— 请在请求侧用 reference_mode 明确声明意图。