# Seedance 系列

使用 [异步视频接口](https://api.hamubox.com/docs/video/)。本章覆盖 EP 系列与对应 Doubao 模型，客户端不需要填写内部线路名。

## 模型与输出规格

| 模型 ID | 建议生成时长 | 分辨率 |
| --- | --- | --- |
| `dreamina-seedance-2-0-ep` | 4–15 秒 | `480p` / `720p` / `1080p` / `4k` |
| `dreamina-seedance-2-0-fast-ep` | 4–15 秒 | `480p` / `720p` |
| `dreamina-seedance-2-0-mini-ep` | 4–15 秒 | `480p` / `720p` |
| `dreamina-seedance-2-5-ep` | 4–30 秒 | `480p` / `720p` / **`1080p`** |
| `doubao-seedance-2-0-260128` | 4–15 秒 | `480p` / `720p` / `1080p` / `4k` |
| `doubao-seedance-2-0-fast-260128` | 4–15 秒 | `480p` / `720p` |
| `doubao-seedance-2-0-mini-260615` | 4–15 秒 | `480p` / `720p` |
| `doubao-seedance-2-5-260628` | 4–30 秒 | `480p` / `720p` / `1080p` |

按范围内的整数传 `duration`，不局限于 5 / 10 / 15 秒。官转 2.5 还支持 `duration: -1`，表示由模型决定输出时长；此值不是单独的编辑模式。不同分组可用模型以 `/v1/models` 为准。

支持的比例：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`。建议总是明确填写 `resolution` 和 `duration`，不要依赖不同线路的默认分辨率。

## 文生视频

省略 `mode` 和参考素材。

```json title="seedance-text.json"
{
  "model": "dreamina-seedance-2-0-ep",
  "prompt": "A slow aerial shot over a green valley at sunrise, natural light, steady camera.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true,
  "watermark": false
}
```

`audio` 控制是否生成音轨；`watermark` 控制水印。本章 EP 系列不承诺 `seed` 可复现结果，请勿依赖种子固定。

## 首帧、尾帧、首尾帧

使用 `mode: "first_last_frame"`，至少提供一个显式帧字段：

- 只有 `first_frame_url`：首帧生成。
- 只有 `last_frame_url`：尾帧生成，不要把尾帧放进 `image_urls[0]`。
- 两者都有：首尾帧生成。

```json title="seedance-frames.json"
{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "The character turns slowly toward the camera. Keep the face and outfit consistent.",
  "mode": "first_last_frame",
  "first_frame_url": "https://example.com/first.png",
  "last_frame_url": "https://example.com/last.png",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "adaptive",
  "audio": true
}
```

**输出比例跟随输入帧**。建议 `aspect_ratio: "adaptive"`；不要期待通过固定比例把输入帧变成另一个比例。需要特定比例时先裁剪素材。

只传尾帧：

```json title="seedance-tail.json"
{
  "model": "dreamina-seedance-2-0-fast-ep",
  "prompt": "The camera slowly approaches the final composition.",
  "mode": "first_last_frame",
  "last_frame_url": "https://example.com/last.png",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}
```

首尾帧模式不要混入 `reference_video_urls`、`reference_audio_urls`。旧的位置数组写法仍可兼容首帧 / 首尾帧，但新接入使用显式帧字段，避免用途混淆。

## 全能参考

使用 `mode: "multi_ref"`。图片是形象 / 风格参考，视频可提供动作与镜头，音频提供声音参考。至少提供一张图片或一段视频，再按需附加音频，避免仅音频请求。

```json title="seedance-reference.json"
{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Keep the character from image 1, follow the movement in video 1 and the mood of audio 1.",
  "mode": "multi_ref",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "reference_video_urls": [
    "https://example.com/motion.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/music.mp3"
  ],
  "metadata": {
    "reference_video_seconds": 8.4,
    "reference_audio_seconds": 6
  },
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "9:16",
  "audio": true
}
```

参考视频和音频的实际时长由服务端检测，调用方不必填写。`metadata.reference_video_seconds` 和 `metadata.reference_audio_seconds` 保留兼容，校验和费用预估以服务端检测值为准。

## 参考限制

| 系列 | 图片 | 视频 | 音频 | 时间边界 |
| --- | ---: | ---: | ---: | --- |
| 2.0 / Fast / Mini | 最多 9 张 | 最多 3 段 | 最多 3 段 | 标称单段 2–15 秒，视频与音频分别累计不超过 15 秒 |
| 2.5 | 最多 30 张 | 最多 10 段 | 最多 10 段 | 标称单段 2–30 秒，视频与音频分别累计不超过 30 秒 |

本站为编码时间误差保留边界余量：最小 1.8 秒，2.0 的最大 / 累计校验边界 15.2 秒，2.5 为 30.2 秒。**余量不是建议的目标长度**，也不改变生成时长上限；尽量按标称范围准备素材。

图片建议采用 JPEG / PNG 等常用格式。官转 Seedance 2.5（包括对应 EP、经济版和 face-library 线路）的参考图、首帧、尾帧均要求：宽和高各为 **300–6000px**，宽高比在 **0.4–2.5** 之间，单文件不超过 **30MB**。

游乐场上传时提前检查，服务端也会在预扣费和提交上游前读取实际图片进行校验；外链、Base64 和历史参数复用同样适用，客户端填写宽高不能绕过检查。不符合要求返回 HTTP 400、`invalid_reference_media`，说明图片序号、实际尺寸和限制，不会自动缩放。例如 `reference_images[2] has dimensions 290x382: shortest side must be at least 300px` 表示第三张图片过小。无法下载或识别图片时也会明确拒绝，请更换素材后重新提交。

`asset://` 是上游登记素材的标识，不作为图片网址下载；仍沿用素材登记与状态检查。其他渠道以模型能力接口公布的限制为准，不将某个模型或登记流程的边界套用到全部线路。

## Seedance 2.5 参考、编辑与延长

这三种意图都使用 `mode: "multi_ref"`。可选的顶层字段 `omni_reference_task_type` 用于提前校验参数；省略时为 `auto`。它不会强制改变模型对提示词的理解，请让提示词与指定意图一致。

| `omni_reference_task_type` | 含义 | 参考视频 | `aspect_ratio` | `duration` |
| --- | --- | --- | --- | --- |
| `auto`（默认） | 根据提示词和素材识别意图 | 按实际需求 | 推荐 `adaptive` | 推荐 `-1`，也可填 4–30 的整数，但须符合实际意图 |
| `reference` | 参考素材生成新视频 | 可选 | 支持固定比例或 `adaptive` | 4–30 的整数或 `-1` |
| `edit` | 修改已有视频 | 至少一段，每段 4–30 秒 | 必须 `adaptive` | 必须 `-1`，跟随被编辑的视频 |
| `extend` | 延长已有视频 | 至少一段，每段 2–30 秒 | 必须 `adaptive` | 4–30 的整数或 `-1` |

**编辑和延长也可同时提供图片、其他参考视频和音频**，仍受上表的数量和累计时长限制。多段视频时，模型根据提示词选择编辑或延长的对象。音频不能作为唯一参考素材。

不打算区分子任务时，建议 `auto + adaptive + -1`，并将参考视频准备为 4–30 秒，以同时满足编辑意图的下限。`-1` 不保证某个固定秒数，也不要把它套用到 2.0、Venice 或其他未声明支持的线路。

### 编辑已有视频

明确描述保留什么、修改什么。输出宽高比和时长跟随模型选中的原视频：

```json title="seedance-edit.json"
{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Edit the video: replace the background with a snowy city, preserve the camera movement.",
  "mode": "multi_ref",
  "omni_reference_task_type": "edit",
  "image_urls": [
    "https://example.com/background.png"
  ],
  "reference_video_urls": [
    "https://example.com/input.mp4"
  ],
  "metadata": {
    "reference_video_seconds": 8.4
  },
  "duration": -1,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}
```

### 延长已有视频

明确描述在原视频后继续发生的动作。输出比例跟随输入视频，`duration` 是请求的输出视频时长，不是自行假定的拼接后总长度：

```json title="seedance-extend.json"
{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Extend the video: continue the camera movement as the character walks toward the snowy city.",
  "mode": "multi_ref",
  "omni_reference_task_type": "extend",
  "reference_video_urls": [
    "https://example.com/input.mp4"
  ],
  "metadata": {
    "reference_video_seconds": 8.4
  },
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}
```

### 参数检查与错误处理

- 显式指定 `edit` / `extend` 时，本站先检查是否有视频、是否使用 `adaptive`，以及编辑时是否传入 `-1`。
- 服务端检测每个音视频文件的时长，分别累计后检查上限；填写 `metadata` 不能替代文件检查。每个文件的尺寸、格式仍须满足供应商要求。
- 省略子任务类型或使用 `auto` 时，模型识别的实际意图与固定比例/时长不兼容，可返回 `InvalidParameter.TaskTypeConstraint`。
- 指定的子任务类型与提示词表达的意图冲突，可返回 `InvalidParameter.TaskTypeMismatch`。请修改提示词或类型后由调用方决定是否重新提交。

字段定义和任务类型边界依据[官方创建视频任务文档](https://docs.volcengine.com/docs/82379/1520757?lang=zh)及[Seedance 2.5 参数约束](https://docs.volcengine.com/docs/82379/2607688?lang=zh#2.5_param_constraints)。本站统一接口使用 `aspect_ratio`，会转为上游的 `ratio`。

## Seedance 2.5 草稿与高清生成

已验证的 Doubao 2.5 和标准 EP 2.5 线路可先生成 `480p` 草稿，再用同一草稿生成 `1080p` 正式视频。是否开放以模型能力中的 `contract.draft` 为准；不要将此能力套用到经济版、特价版或其他未声明支持的线路。

### 第一步：生成草稿

通过 `POST /v1/video/generations` 提交 JSON，在正常生成参数上增加顶层 `draft: true`，且 `resolution` 必须为 `480p`。仍支持该模型允许的首尾帧和全能参考参数。

```json title="seedance-draft.json"
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "A red cube slowly rotates on a table, fixed camera.",
  "duration": 4,
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "draft": true,
  "audio": false,
  "watermark": false
}
```

用返回的本站 `task_...` ID 查询 `GET /v1/video/generations/{task_id}`。成功后，响应 `metadata` 提供 `draft`、`draft_can_finalize`、`draft_expires_at`（Unix 秒）。只有 `draft_can_finalize: true` 且未过期的草稿才可继续生成；不要使用上游任务 ID 或视频 URL 替代。

### 第二步：估价并确认生成 1080p

向 `POST /v1/video/generations/estimate` 提交以下参数，读取 `estimated_cost_usd`。估价不发起生成、不扣费；随后向 `POST /v1/video/generations` 提交同一份参数，并可将报价放入 `max_cost_usd`。

```json title="seedance-draft-final.json"
{
  "model": "doubao-seedance-2-5-260628",
  "draft_task_id": "task_replace_with_your_completed_draft_id",
  "resolution": "1080p",
  "watermark": false
}
```

- 必须是本人已成功的草稿，`model` 与草稿一致，`resolution` 必须为 `1080p`。
- 正式生成继承草稿设置。不要再次传提示词、模式、时长、比例、种子、声音、参考素材或 `metadata`，即使取值未变也应省略；`draft` 省略或为 `false`。
- 服务端锁定草稿原线路和原账号，不切换至普通高清备用线路。原账号被停用、权限变化或草稿过期会明确报错，不自动重新生成草稿。
- `max_cost_usd` 限制本次预扣报价。价格上涨时返回 HTTP 409、`approval_price_changed`，请重新估价并确认。它不是最终实际用量的硬性封顶。
- 草稿和正式视频是两个任务，**分别预扣、分别结算，不是补差价**。原草稿不再计作额外参考视频；原请求已有的参考视频费用仍按对应规则计算。
- 可用期以返回的 `draft_expires_at` 为准。草稿过期不删除已生成的视频，只是不再允许继续生成高清版本。部分正式视频采用 HEVC 编码，播放器需支持对应格式。

草稿及升级请求仅接受 JSON，不接受 multipart。视频游乐场和无限画布均提供草稿开关：游乐场在结果区操作；画布选中已完成的草稿视频后，可重新估价并确认高清生成。高清结果在画布中新增独立节点，保留原草稿。

## 计费

按视频 token 计费。不同分辨率、是否有参考视频，对应不同的每百万 token 单价。图片 / 音频参考不应被当作视频输入时长。

提交时按估算预扣，任务完成后按实际用量结算。实际输出尺寸、时长和参考视频都会影响费用；不能用文字 token 估算器计算视频 token。详细单价与当前 Key 的适用价格见[模型广场](https://api.hamubox.com/pricing)，响应字段见[计费与结算](https://api.hamubox.com/docs/billing/)。

官转 2.5 使用自动时长时，按 30 秒输出估算预扣；显式编辑且已知参考视频总时长时，按该时长保守估算。最终仍以实际用量结算，多余预扣退回。