> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ominiapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance

# Seedance 2.0 创建视频生成任务 API 文档

## 1. 接口说明

用于创建 Seedance 2.0 视频生成任务。

| 项目   | 内容                                |
| ---- | --------------------------------- |
| 请求方法 | `POST`                            |
| 请求路径 | `/v1/video/generations`           |
| 请求格式 | `application/json`                |
| 认证方式 | `Authorization: Bearer <API Key>` |

## 2. 请求结构

请求体为 JSON 对象，基础字段放在顶层，时长、比例、分辨率、音频、水印、随机种子、固定镜头、多模态素材等参数放在 `metadata` 内。

```json theme={null}
{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "海边日落，镜头缓慢推进，光影变化细腻",
    "metadata": {
        "duration": 8,
        "ratio": "16:9",
        "resolution": "720p"
    }
}
```

`duration`、`ratio`、`resolution`、`generate_audio`、`watermark`、`seed`、`return_last_frame`、`camera_fixed`、`content` 必须放在 `metadata` 内。

## 3. 场景互斥规则

Seedance 2.0 的图片输入分为三类角色场景。以下三种场景不能在同一个请求中混用。

| 场景      | 图片数量     | 图片角色                         | 说明                  |
| ------- | -------- | ---------------------------- | ------------------- |
| 首帧场景    | 1 张      | `first_frame`                | 以输入图片作为视频首帧         |
| 首尾帧场景   | 2 张      | `first_frame` + `last_frame` | 第 1 张作为首帧，第 2 张作为尾帧 |
| 多模态参考场景 | 1-9 张参考图 | `reference_image`            | 图片作为风格、主体或画面参考      |

多模态参考场景还可以同时包含参考视频和参考音频。

| 多模态素材 | 数量限制  | ContentItem 类型 | 角色                |
| ----- | ----- | -------------- | ----------------- |
| 参考图片  | 1-9 张 | `image_url`    | `reference_image` |
| 参考视频  | 0-3 段 | `video_url`    | `reference_video` |
| 参考音频  | 0-3 段 | `audio_url`    | `reference_audio` |

在多模态参考模式下，`reference_image`、`video_url`、`audio_url` 可以任意组合同时使用。

禁止混用示例：

| 不允许的组合                      | 原因                |
| --------------------------- | ----------------- |
| `image` + `video`           | 顶层首帧图片不能和顶层视频参考混用 |
| `images` 传 2 张 + `videos`   | 首尾帧场景不能和视频参考混用    |
| `first_frame` + `video_url` | 首帧场景不能和多模态参考视频混用  |
| `last_frame` + `audio_url`  | 首尾帧场景不能和多模态参考音频混用 |

## 4. 顶层参数

| 参数         | 类型     | 必填 | 说明                                         |
| ---------- | ------ | -- | ------------------------------------------ |
| `model`    | string | 是  | 模型 ID                                      |
| `prompt`   | string | 是  | 文本提示词；中文不超过 500 字，英文不超过 1000 词             |
| `image`    | string | 否  | 单张图片 URL，作为首帧；与 `video` / `videos` 互斥      |
| `images`   | array  | 否  | 多张图片 URL，用于首尾帧或参考图；与 `video` / `videos` 互斥 |
| `video`    | string | 否  | 单个参考视频 URL；与 `image` / `images` 互斥         |
| `videos`   | array  | 否  | 多个参考视频 URL，最多 3 个；与 `image` / `images` 互斥  |
| `metadata` | object | 推荐 | 透传参数对象，时长、比例、分辨率等必须放在这里                    |

可用模型：

| 模型 ID                             | 说明                  |
| --------------------------------- | ------------------- |
| `doubao-seedance-2-0-260128`      | Seedance 2.0 标准版    |
| `doubao-seedance-2-0-fast-260128` | Seedance 2.0 Fast 版 |

## 5. metadata 参数

| 参数                  | 类型      | 默认值     | 说明                               |
| ------------------- | ------- | ------- | -------------------------------- |
| `duration`          | integer | `5`     | 视频时长，单位秒，范围 4-15                 |
| `ratio`             | string  | `16:9`  | 视频宽高比                            |
| `resolution`        | string  | `720p`  | 分辨率，可选 `480p` / `720p` / `1080p` |
| `generate_audio`    | boolean | `true`  | 是否生成同步音频                         |
| `watermark`         | boolean | `false` | 是否添加水印                           |
| `seed`              | integer | `-1`    | 随机种子；`-1` 表示随机                   |
| `return_last_frame` | boolean | `false` | 是否返回尾帧图像                         |
| `camera_fixed`      | boolean | `false` | 是否固定摄像头                          |
| `content`           | array   | -       | 多模态素材数组，使用 ContentItem 格式        |

## 6. 请求示例

### 6.1 文生视频

```json theme={null}
{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "海边日落，镜头缓慢推进，光影变化细腻",
    "metadata": {
        "duration": 8,
        "ratio": "16:9",
        "resolution": "720p"
    }
}
```

### 6.2 图生视频：首帧

```json theme={null}
{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "画面中的人物开始行走",
    "image": "https://www.example.com/first-frame.jpg",
    "metadata": {
        "duration": 5,
        "resolution": "720p",
        "ratio": "adaptive"
    }
}
```

单张首帧使用顶层 `image` 即可。不要与 `video`、`videos` 或包含 `video_url` 的 `metadata.content` 同时传入。

### 6.3 图生视频：首尾帧

```json theme={null}
{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "平滑过渡",
    "images": [
        "https://www.example.com/first-frame.jpg",
        "https://www.example.com/last-frame.jpg"
    ],
    "metadata": {
        "duration": 8,
        "resolution": "720p",
        "ratio": "adaptive"
    }
}
```

顶层 `images` 传 2 张图时，网关会自动分配 `first_frame` 和 `last_frame`。该示例为纯图片输入，不能与 `video`、`videos` 或 `metadata.content` 中的 `video_url` 混用。

### 6.4 视频参考

```json theme={null}
{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "按照参考视频的风格生成",
    "video": "https://www.example.com/ref.mp4",
    "metadata": {
        "duration": 5,
        "resolution": "720p"
    }
}
```

也可以使用 `videos` 数组传入多个参考视频，最多 3 个。还可以通过 `metadata.content` 传入仅包含 `video_url` 的素材项。该示例为纯视频参考，请求中不得再出现 `image`、`images` 或 `metadata.content` 中的 `image_url`。

### 6.5 多模态参考：参考图 + 参考视频 + 参考音频

```json theme={null}
{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "结合参考图片的主体、参考视频的运动风格和参考音频的节奏生成视频",
    "metadata": {
        "duration": 8,
        "ratio": "16:9",
        "resolution": "720p",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://www.example.com/ref-image.jpg"
                },
                "role": "reference_image"
            },
            {
                "type": "video_url",
                "video_url": {
                    "url": "https://www.example.com/ref-video.mp4"
                },
                "role": "reference_video"
            },
            {
                "type": "audio_url",
                "audio_url": {
                    "url": "https://www.example.com/ref-audio.mp3"
                },
                "role": "reference_audio"
            }
        ]
    }
}
```

该模式下 `reference_image`、`video_url`、`audio_url` 可以任意组合。不要在同一请求中再传入 `first_frame` 或 `last_frame`。

## 7. 图片模式

图片输入适用于顶层 `image`、顶层 `images`，或 `metadata.content` 中仅包含 `image_url` 的请求。

图片模式与视频参考互斥，不可与顶层 `video`、顶层 `videos` 或 `metadata.content` 中的 `video_url` 混用，除非该请求明确处于多模态参考模式且图片角色为 `reference_image`。

| 图片数量   | 角色分配                         | 说明         |
| ------ | ---------------------------- | ---------- |
| 1 张    | `first_frame`                | 以该图片作为视频首帧 |
| 2 张    | `first_frame` + `last_frame` | 指定首帧和尾帧    |
| 3 张及以上 | `reference_image`            | 作为参考图      |

使用图片时，`ratio` 建议设置为 `adaptive`，以自适应图片宽高比。

## 8. 视频参考

Seedance 2.0 支持以参考视频驱动生成。推荐通过顶层 `video` 或 `videos` 传入，也可以通过 `metadata.content` 中的 `video_url` 项传入。

视频参考属于多模态参考模式。在该模式下，`reference_image`、`video_url`、`audio_url` 可以任意组合同时使用。但不能与首帧或首尾帧场景混用，即不能同时包含 `first_frame` / `last_frame` 和 `video_url`。

| 参数                        | 说明                                     |
| ------------------------- | -------------------------------------- |
| `video`                   | 单个参考视频 URL                             |
| `videos`                  | 多个参考视频 URL，最多 3 个                      |
| `content[].type`          | 使用 `metadata.content` 时固定为 `video_url` |
| `content[].video_url.url` | 参考视频 URL                               |
| `content[].role`          | 固定为 `reference_video`                  |

视频参考素材要求：

| 约束   | 要求        |
| ---- | --------- |
| 数量   | 不超过 3 个   |
| 格式   | MP4、MOV   |
| 单片时长 | 2-15 秒    |
| 分辨率  | 480p-720p |

## 9. 宽高比

| 值          | 说明         |
| ---------- | ---------- |
| `16:9`     | 横屏，文生视频默认  |
| `9:16`     | 竖屏         |
| `4:3`      | 传统横幅       |
| `3:4`      | 传统竖幅       |
| `1:1`      | 正方形        |
| `21:9`     | 超宽屏        |
| `adaptive` | 自适应，图生视频推荐 |

## 10. ContentItem 格式

### 10.1 参考图片

```json theme={null}
{
    "type": "image_url",
    "image_url": {
        "url": "https://www.example.com/ref-image.jpg"
    },
    "role": "reference_image"
}
```

### 10.2 参考视频

```json theme={null}
{
    "type": "video_url",
    "video_url": {
        "url": "https://www.example.com/ref-video.mp4"
    },
    "role": "reference_video"
}
```

### 10.3 参考音频

```json theme={null}
{
    "type": "audio_url",
    "audio_url": {
        "url": "https://www.example.com/ref-audio.mp3"
    },
    "role": "reference_audio"
}
```

## 11. 快速校验清单

提交请求前建议确认：

1. `model` 和 `prompt` 已填写。
2. `duration`、`ratio`、`resolution` 等生成参数放在 `metadata` 内。
3. 顶层 `image` / `images` 没有和顶层 `video` / `videos` 混用。
4. 首帧或首尾帧场景没有和 `video_url` / `audio_url` 混用。
5. 多模态参考模式中图片角色使用 `reference_image`。
6. `videos` 数量不超过 3 个。
7. 参考视频格式为 MP4 或 MOV，单片时长为 2-15 秒，分辨率为 480p-720p。