# Seedance 2.0 系列调用指南

> 通过 UniAI 调用 Seedance 2.0、Seedance 2.0 Fast 和 Seedance 2.0 Mini，涵盖多模态输入、视频编辑、延长和任务查询。

Canonical URL: https://docs.uniai.tv/models/video/seedance-2-0/series-guide
Locale: zh-CN

更新时间：2026-07-29

本文介绍如何通过 UniAI 调用 Seedance 2.0 系列。新接入推荐使用三个稳定公共模型名，通过请求参数选择分辨率和生成能力。

## 1. 模型选择

| 公共模型 | 支持分辨率 | 适用场景 |
| --- | --- | --- |
| `seedance2.0` | `480p`、`720p`、`1080p`、`4k` | 综合质量优先，支持完整能力 |
| `seedance2.0-fast` | `480p`、`720p` | 生成速度优先 |
| `seedance2.0-mini` | `480p`、`720p` | 轻量任务和速度优先 |

三个模型均支持：

- 文生视频；
- 单图生视频；
- 首尾帧生视频；
- 图片、视频和音频多模态参考；
- 视频编辑和视频延长；
- 有声视频、水印和随机种子；
- 纯文本联网搜索；
- 返回生成视频的尾帧；
- 使用可用素材响应返回的 `uri`。

## 2. 接口与鉴权

推荐使用 OpenAI 兼容视频任务接口：

```http
POST /v1/videos
GET  /v1/videos/{task_id}
GET  /v1/videos/{task_id}/content
```

请求头：

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

以下示例中的 `{BASE_URL}` 使用：

```uri
https://api.uniai.tv
```

同时保留以下兼容接口：

```http
POST /v1/videos/generations
GET  /v1/videos/generations/{task_id}

POST /v1/video/generations
GET  /v1/video/generations/{task_id}
```

新接入建议统一使用 `/v1/videos`。

## 3. 公共参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 三个公共模型之一，或兼容期内的固定分辨率模型名 |
| `prompt` | string | 条件必填 | 视频提示词；使用 `content[]` 时改为至少一个 `type=text` 项 |
| `resolution` | string | 新公共模型必填 | 输出分辨率，取值见模型表 |
| `size` | string | 否 | `resolution` 的兼容别名 |
| `duration` | integer/string | 是 | 输出时长，支持 `4` 到 `15` 秒；兼容值 `auto`，推荐显式传整数 |
| `aspect_ratio` | string | 否 | `auto`、`21:9`、`16:9`、`4:3`、`3:2`、`2:3`、`1:1`、`3:4`、`9:16` |
| `ratio` | string | 否 | `aspect_ratio` 的兼容别名；`adaptive` 等价于 `auto` |
| `content` | object[] | 否 | 推荐的多模态输入格式，详见下一节 |
| `operation` | string | 特定能力必填 | `reference_to_video`、`edit_video` 或 `extend_video` |
| `generate_audio` | boolean | 否 | 是否生成有声视频 |
| `watermark` | boolean | 否 | 是否添加水印 |
| `seed` | integer | 否 | 随机种子 |
| `return_last_frame` | boolean | 否 | 是否在完成结果中返回尾帧 URL |
| `tools` | object[] | 否 | 当前仅支持 `[{"type":"web_search"}]` |

参数兼容规则：

- `resolution` 和 `size` 同时传入时必须相同。
- `aspect_ratio` 和 `ratio` 同时传入时必须表达相同比例。
- `ratio: "adaptive"` 与 `aspect_ratio: "auto"` 视为相同。
- `operation`、`generate_audio`、`watermark`、`seed`、`return_last_frame` 和 `tools` 也兼容放入 `extra_body`；同一参数不要在顶层和 `extra_body` 重复传入。
- `draft`、`frames`、`camera_fixed` 和 `service_tier: "flex"` 不属于当前公共契约。

## 4. `content[]` 多模态格式

复杂输入推荐统一使用 `content[]`：

```json
{
  "content": [
    {
      "type": "text",
      "text": "提示词"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.png"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/video.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/audio.mp3"
      },
      "role": "reference_audio"
    }
  ]
}
```

支持的类型和角色：

| `type` | `role` | 含义 |
| --- | --- | --- |
| `text` | 无 | 提示词，可传多个文本项 |
| `image_url` | `image` | 单图生视频输入图 |
| `image_url` | `reference_image` | 参考图片 |
| `image_url` | `first_frame` | 首帧图片 |
| `image_url` | `last_frame` | 尾帧图片 |
| `video_url` | `source_video` | 编辑或延长的源视频 |
| `video_url` | `reference_video` | 参考视频 |
| `audio_url` | `reference_audio` | 参考音频 |

输入约束：

- `content[]` 至少包含一个非空文本项。
- 图片最多 9 张，视频最多 3 段，音频最多 3 段。
- `first_frame` 和 `last_frame` 必须成对出现，且各只能有 1 张。
- 首尾帧模式不能再混入视频、音频或其他图片。
- `image` 和 `reference_image` 不要在同一请求中混用。
- `source_video` 最多 1 段。
- 参考音频必须同时存在至少一张图片或一段视频；不接受纯音频或“文本 + 音频”。
- 使用多份参考素材时，可在提示词中按顺序使用 `@Image1`、`@Video1`、`@Audio1` 指定素材。

简单请求仍兼容 `image`、`images`、`last_image`、`video`、`videos` 和 `audios` 等字段；新功能和多模态组合建议使用 `content[]`，避免输入角色不明确。

## 5. 请求示例

### 5.1 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "prompt": "雨后的未来城市街道，霓虹倒影，电影感镜头缓慢向前推进。",
    "resolution": "1080p",
    "duration": 5,
    "ratio": "16:9",
    "generate_audio": true
  }'
```

### 5.2 单图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "人物自然转身看向镜头，衣服随风轻微摆动，保持人物身份一致。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/person.png"
        },
        "role": "image"
      }
    ]
  }'
```

### 5.3 首尾帧生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "镜头从白天自然过渡到夜晚，运动连贯，建筑结构保持稳定。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/first.png"
        },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/last.png"
        },
        "role": "last_frame"
      }
    ]
  }'
```

### 5.4 多模态参考生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-mini",
    "resolution": "720p",
    "duration": 8,
    "operation": "reference_to_video",
    "content": [
      {
        "type": "text",
        "text": "让 @Image1 中的产品按照 @Video1 的镜头运动展示，并参考 @Audio1 的节奏。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/product.png"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/motion.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "https://example.com/music.mp3"
        },
        "role": "reference_audio"
      }
    ]
  }'
```

### 5.5 视频编辑

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "operation": "edit_video",
    "content": [
      {
        "type": "text",
        "text": "把背景替换为雨夜霓虹街道，保留人物动作和主体身份。"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/source.mp4"
        },
        "role": "source_video"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/style.png"
        },
        "role": "reference_image"
      }
    ]
  }'
```

### 5.6 视频延长

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-fast",
    "resolution": "720p",
    "duration": 5,
    "operation": "extend_video",
    "content": [
      {
        "type": "text",
        "text": "延续原镜头运动，人物继续向前行走，光线和场景保持一致。"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/source.mp4"
        },
        "role": "source_video"
      }
    ]
  }'
```

### 5.7 纯文本联网搜索

联网搜索只能用于纯文本请求，不能同时传图片、视频或音频。

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0-mini",
    "prompt": "根据今天公开的科技新闻制作一段简洁的资讯视频，不要显示品牌商标。",
    "resolution": "720p",
    "duration": 5,
    "tools": [
      {
        "type": "web_search"
      }
    ]
  }'
```

`web_search` 表示允许模型检索公开信息，不保证每次生成都会实际产生搜索调用。

### 5.8 返回尾帧

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "prompt": "一艘纸船缓慢停在石桥旁，最后画面保持稳定。",
    "resolution": "720p",
    "duration": 5,
    "return_last_frame": true
  }'
```

任务完成后，尾帧通过 `result.last_frame_url` 返回，不会混入视频 `outputs`。

### 5.9 使用素材库 URI

通过 [Seedance 2.0 素材库](/models/video/seedance-2-0/material-library) 创建并查询可复用输入。素材达到 `status=available` 后，把普通媒体 URL 替换为接口返回的 `uri`：

```json
{
  "model": "seedance2.0-fast",
  "resolution": "480p",
  "duration": 4,
  "content": [
    {
      "type": "text",
      "text": "Keep the product appearance consistent as the camera slowly moves around it."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-EXAMPLE"
      },
      "role": "reference_image"
    }
  ]
}
```

复制自己的素材响应中的 `uri`，不要用 `mat_*` 自行拼接。URI 只能放入对应的结构化媒体字段，不要写入提示词，并须在 `expires_at` 前使用。

## 6. 任务状态与结果

创建成功后返回异步任务：

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "seedance2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1784640000
}
```

创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。

Seedance 请求生成尾帧时，完成响应还可能包含 `result.last_frame_url`。

## 7. 固定分辨率模型兼容

已有客户端可以继续使用固定分辨率模型名：

| 模型系列 | 兼容模型名 |
| --- | --- |
| Standard | `seedance2.0-480p`、`seedance2.0-720p`、`seedance2.0-1080p`、`seedance2.0-4k` |
| Fast | `seedance2.0-fast-480p`、`seedance2.0-fast-720p` |
| Mini | `seedance2.0-mini-480p`、`seedance2.0-mini-720p` |

更早的以下名称也继续兼容：

- `seedance2.0-video-480p`
- `seedance2.0-video-720p`
- `seedance2.0-fast-video-480p`
- `seedance2.0-fast-video-720p`

固定分辨率模型从模型名确定分辨率，不要求额外传 `resolution`。它们与对应的新公共模型使用相同参数和能力；如仍传 `resolution` 或 `size`，值必须与模型名中的分辨率一致。

新项目建议迁移到三个公共模型名，便于只修改请求参数即可切换输出分辨率。

## 8. 常见错误

| 场景 | 结果 | 修正方式 |
| --- | --- | --- |
| 新公共模型缺少 `resolution`/`size` | HTTP `400` | 显式传入支持的分辨率 |
| `resolution` 与 `size` 不同 | HTTP `400` | 只传一个，或保证值相同 |
| `aspect_ratio` 与 `ratio` 冲突 | HTTP `400` | 只传一个，或保证语义相同 |
| 缺少 `duration` | HTTP `400` | 传 `4` 到 `15` 的整数 |
| `content[]` 没有文本项 | HTTP `400` | 增加非空 `type=text` 项 |
| 首帧和尾帧没有成对传入 | HTTP `400` | 同时传 `first_frame` 和 `last_frame` |
| 纯音频或“文本 + 音频” | HTTP `400` | 至少增加一张图片或一段视频 |
| 联网搜索请求包含媒体 | HTTP `400` | 搜索请求只保留文本输入 |
| 图片、视频或音频数量超限 | HTTP `400` | 分别控制在 9、3、3 个以内 |
| 使用 `draft`、`frames`、`camera_fixed` 或 `service_tier=flex` | HTTP `400` | 删除这些参数 |

遇到安全审核、素材格式或参数错误时，应修改输入后创建新任务，不要对同一无效请求进行高频重复提交。

## 9. 相关页面

- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance 2.0 素材库](/models/video/seedance-2-0/material-library)
- [视频生成概览](/models/video/overview#视频任务生命周期)