# Seedance-2.0

<div class="doc-interface">
  <p><strong>URL</strong>：<code>/v3/contents/generations/tasks</code></p>
  <p><strong>Method</strong>：<code>POST</code></p>
</div>

#### 请求体 · 顶层参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 视频生成模型 ID，传 `doubao-seedance-2-0-260128` |
| content | object[] | 是 | 输入内容列表，见下文「`content` 类型与字段」 |
| callback_url | string | 否 | 任务状态回调 URL，状态含 `queued`、`running`、`succeeded`、`failed`、`expired` |
| return_last_frame | boolean | 否 | 是否返回尾帧，默认 `false` |
| execution_expires_after | integer | 否 | 任务过期时间（秒），默认 172800（48 小时），范围 [3600, 259200] |
| generate_audio | boolean | 否 | 是否生成同步音频 |
| tools | object[]  | 否 | 配置模型要调用的工具 {type:web_search(联网搜索工具)} |
| safety_identifier | string | 否 | 终端用户的唯一标识符，用于协助平台检测您的应用中可能违反火山方舟使用政策的用户。该标识符为英文字符串，需保证对单个用户固定且唯一，长度不超过 64 个字符。推荐传入对用户名、用户 ID 或邮箱进行哈希处理后生成的字符串，避免泄露用户隐私信息 |
| resolution | string | 否 | 输出分辨率。可选 `480p`、`720p`、`1080p`、`4k`，默认 `720p` |
| ratio | string | 否 | 输出宽高比。可选 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive(根据输入自动选择最合适的宽高比)` |
| duration | integer | 否 | 视频时长（秒），默认 5。 [4,15]  或设置为-1表示由模型在有效范围内自主选择合适的视频长度（整数秒) |
| seed | integer | 否 | 随机种子。范围 [-1, 2^32-1]，默认 `-1`（随机） |
| watermark | boolean | 否 | 是否添加水印，默认 `false` |





<p class="doc-note">不同模型对可选字段的支持与取值范围可能不同，以 <a href="https://www.volcengine.com/docs/82379/1520757?lang=zh">火山方舟文档</a> 及接入点说明为准。</p>

#### `content` 数组

`content` 为对象数组；**每一项必须包含 `type`**，并按类型填写其余字段。支持与官方一致的多模态组合（例如仅文本、文本+参考图、文本+图+视频+音频、基于样片任务等）。

| 说明 | 内容 |
| --- | --- |
| 常见组合 | 仅 `text`；`text`（可选）+ 若干 `image_url` / `video_url` / `audio_url`，具体以官方文档为准 |
| 注意 | 不支持直接上传含真人脸的参考图/视频 |

以下为各 `type` 的请求字段（与官网「按类型分表」一致）；**新增一种 `content` 类型时，可复制某一节改标题与表格即可。**

##### `type`：`text`（文本提示词）

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 固定为 `text` |
| text | string | 是 | 文本提示词。中英文均支持；另支持日语、印尼语、西班牙语、葡萄牙语；建议中文 ≤ 500 字、英文 ≤ 1000 词 |

##### `type`：`image_url`（图片）

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 固定为 `image_url` |
| image_url | object | 是 | 图片信息，见下表 |
| role | string | 条件必填 | 图片用途，与「图生视频-首帧 / 首尾帧 / 参考图」场景对应；三种场景互斥，不可混用，详见下方「图片场景与 role」 |

**`image_url` 对象**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| url | string | 是 | 图片地址，支持公网 URL 或 Base64 |

##### `type`：`video_url`（参考视频）

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 固定为 `video_url` |
| video_url | object | 是 | 视频信息，见下表 |
| role | string | 条件必填 | 常用 `reference_video` |

**`video_url` 对象**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| url | string | 是 | 视频 URL，或素材 ID：`asset://<ASSET_ID>` |

##### `type`：`audio_url`（参考音频）

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| type | string | 是 | 固定为 `audio_url` |
| audio_url | object | 是 | 音频信息，见下表 |
| role | string | 条件必填 | 常用 `reference_audio` |

**`audio_url` 对象**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| url | string | 是 | 音频 URL、Base64，或素材 ID：`asset://<ASSET_ID>` |



#### 图片场景与 `role`

| 图片场景 | 适用模型 | 传入要求 | `role` 取值 |
| --- | --- | --- | --- |
| 图生视频-首帧   | 传 1 个 `image_url` | `first_frame` 或不填 |
| 图生视频-首尾帧  | 传 2 个 `image_url` | 必填：首帧 `first_frame`，尾帧 `last_frame` |
| 图生视频-参考图   | 多张参考图 | 每张必填 `reference_image`（常见 1~9 张） |

#### 多媒体输入约束

| 约束项 | 规则 |
| --- | --- |
| 视频 | 格式 `mp4/mov`；分辨率 `480p/720p/1080p/4k`；单段时长 [2,15] 秒、最多 3 段、总时长 ≤ 15 秒；宽高比 [0.4,2.5]；宽或高 [300,6000]；像素总数 [409600,927408]；单视频 ≤ 50 MB；FPS [24,60] |
| 音频| 格式 `wav/mp3`；单段时长 [2,15] 秒、最多 3 段、总时长 ≤ 15 秒；单音频 ≤ 15 MB；请求体 ≤ 64 MB；音频不可单独输入，至少配合 1 个参考视频或图片 |
| 首尾帧补充 | 首尾图宽高比不一致时通常以首帧为主，尾帧自动裁剪适配 |

#### 响应字段（创建任务）

<p class="doc-note">创建视频生成任务为<strong>异步接口</strong>。拿到 <code>id</code> 后需结合「<a href="api-task-query-byteplus">BytePlus 视频任务查询</a>」轮询或使用回调获取结果。</p>

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | — | 视频生成任务 ID，用于后续查询任务状态与结果 |

<p class="doc-caption">cURL 示例（文生视频）</p>

```bash
curl -X POST "$BASE_URL/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "A futuristic city at sunset with flying cars" }
    ],
    "resolution": "1080p",
    "duration": 5
  }'
```

<p class="doc-caption">cURL 示例（文本 + 参考图 + 参考视频 + 参考音频）</p>

```bash
curl -X POST "$BASE_URL/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "一位少年在草坪上奔跑，3D 卡通风格" },
      { "type": "image_url", "image_url": { "url": "https://example.com/ref-1.jpg" }, "role": "reference_image" },
      { "type": "video_url", "video_url": { "url": "https://example.com/ref-video.mp4" }, "role": "reference_video" },
      { "type": "audio_url", "audio_url": { "url": "https://example.com/ref-audio.mp3" }, "role": "reference_audio" }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'
```

<p class="doc-caption">参考</p>

- 火山引擎方舟 · Seedance 2.0 API 参考：<https://www.volcengine.com/docs/82379/1520757?lang=zh>