# Seedance 2.5

> 使用 Seedance 2.5 创建 480p/720p/1080p 视频、音频参考、Draft 样片及 1080p 成片，支持编辑、延长和高级控制。

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

本页中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。

更新时间：2026-10-19

## 概览

UniAI 对外提供一个稳定的 Seedance 2.5 公共模型：`seedance2.5`。该模型支持文生视频、单首帧和首尾帧生视频、多模态参考生成、视频编辑、视频延长、可复用 `asset://` 素材、可选的联网搜索，以及 480p Draft 样片转 1080p 成片。

| 能力 | 必需输入 | 核心规则 |
| --- | --- | --- |
| 文生视频 | 提示词 | 默认 `720p`、自动时长，也可显式选择。 |
| 单首帧生视频 | 1 张首帧图 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 首尾帧生视频 | 1 张首帧图和 1 张尾帧图 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 多模态参考生成 | 图片、视频或音频 | 文本可省略，也允许仅音频参考。 |
| 视频编辑 | 提示词和 1 个视频 | 显式传 `omni_reference_task_type: "edit"`，使用自动时长。 |
| 视频延长 | 提示词和 1 个视频 | 显式传 `omni_reference_task_type: "extend"`。 |
| Draft 转成片 | 当前用户已完成的 Draft 任务 ID | 样片为 `480p`，七天内可转为继承原设置的 `1080p` 成片。 |

## 接口与鉴权

| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建任务 | `POST` | `/v1/videos` |
| 查询任务 | `GET` | `/v1/videos/{task_id}` |

已有客户端可继续使用以下兼容创建和查询路径：

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

新接入统一使用 `/v1/videos` 和 `/v1/videos/{task_id}`。

```http
Authorization: Bearer <UNIAI_API_KEY>
Content-Type: application/json
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `seedance2.5`。 |
| `prompt` | string | 条件必填 | 文本指令。纯文生、编辑和延长必填；有图片、视频或音频参考时可省略，Draft 转成片时必须省略。 |
| `resolution` | string | 否 | `480p`、`720p` 或 `1080p`。普通请求默认 `720p`；Draft 默认且只能为 `480p`；Draft 转成片默认且只能为 `1080p`。 |
| `duration` | integer/string | 否 | `"auto"`、`-1` 或 `4` 到 `30` 的整数，默认自动时长。编辑只能使用自动时长；Draft 转成片时省略。 |
| `aspect_ratio` | string | 否 | `auto`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4` 或 `9:16`。帧输入、编辑和延长需省略或使用 `auto`；Draft 转成片时省略。 |
| `content` | object[] | 否 | 文字、图片、视频或音频内容。文字项使用 `{"type":"text","text":"..."}`，媒体角色见下文。 |
| `omni_reference_task_type` | string | 否 | `auto`、`reference`、`edit` 或 `extend`。编辑或延长需显式设置对应值；Draft 转成片时省略。 |
| `draft` | boolean | 否 | `true` 创建 480p 样片，默认 `false`；Draft 转成片时不能为 `true`。 |
| `draft_task_id` | string | 条件必填 | 同一用户创建、已完成且创建未满七天的 UniAI Draft 任务 ID，用于生成 1080p 成片。 |
| `output_format` | string | 否 | `mp4` 或 `mov`，默认 `mp4`。 |
| `generate_audio` | boolean | 否 | 是否生成音频，显式 `false` 会保留。Draft 转成片时继承，必须省略。 |
| `watermark` | boolean | 否 | 是否添加水印，显式 `false` 会保留。 |
| `return_last_frame` | boolean | 否 | 是否在可用时返回生成视频的尾帧，显式 `false` 会保留。 |
| `seed` | integer | 否 | `-1` 到 `2147483647`；Draft 转成片时省略。 |
| `priority` | integer | 否 | `0` 到 `9`，显式 `0` 会保留。 |
| `execution_expires_after` | integer | 否 | 执行过期时间，单位为秒，范围 `3600` 到 `259200`。 |
| `safety_identifier` | string | 否 | `1` 到 `64` 个可见 ASCII 字符，不含空格或控制字符；使用非敏感标识。 |
| `tools` | object[] | 否 | 联网搜索使用 `[{"type":"web_search"}]`；Draft 转成片时省略。 |
| `service_tier` | string | 否 | 仅支持 `default`，不支持 `flex`。 |
| `size` | string | 否 | `resolution` 的兼容别名；两者同时存在时必须描述同一分辨率，推荐使用 `resolution`。 |
| `seconds` | integer/string | 否 | `duration` 的兼容别名，推荐使用 `duration`；Draft 转成片时省略。 |
| `ratio` | string | 否 | `aspect_ratio` 的兼容别名，`adaptive` 归一为 `auto`；Draft 转成片时省略。 |
| `operation` | string | 否 | 兼容操作选择：`reference_to_video`、`edit_video` 或 `extend_video`。新示例优先使用 `omni_reference_task_type`，不要传入冲突选择；Draft 转成片时省略。 |

参数放在顶层。兼容客户端也可把控制参数放在 `extra_body` 中；同一字段在两处同时出现时，值必须一致。显式 `false` 和 `0` 是有效值，不等同于省略。

不支持 4K、`frames`、`camera_fixed` 或 `flex` 服务档位。

## 最小文生请求

```bash
curl -X POST "https://api.uniai.tv/v1/videos" \
  -H "Authorization: Bearer <UNIAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.5",
    "prompt": "A mechanical bird unfolds its wings on a wooden table."
  }'
```

省略 `resolution` 和 `duration` 时，普通生成使用 `720p` 和自动时长。需要明确规格和高级控制时可使用：

```json
{
  "model": "seedance2.5",
  "prompt": "A mechanical bird unfolds its wings on a wooden table.",
  "resolution": "1080p",
  "duration": 4,
  "aspect_ratio": "16:9",
  "output_format": "mp4",
  "generate_audio": true,
  "watermark": false,
  "return_last_frame": true,
  "seed": 250628,
  "priority": 0,
  "execution_expires_after": 86400,
  "safety_identifier": "video-demo-01"
}
```

## 媒体输入

新接入建议使用 `content[]` 表达多模态输入。每一项包含一个媒体类型和明确角色。

| 项目类型 | URL 字段 | 支持角色 |
| --- | --- | --- |
| `text` | `text` | 生成或编辑指令 |
| `image_url` | `image_url.url` | `first_frame`、`last_frame`、`reference_image` |
| `video_url` | `video_url.url` | `reference_video` |
| `audio_url` | `audio_url.url` | `reference_audio` |

媒体地址可以是公开 HTTP(S) URL，也可以是有效的 `asset://` 素材地址。HTTP(S) 素材必须能由 UniAI 服务直接访问，不能依赖 Cookie 或自定义请求头。创建可复用 `asset://` 输入的方法见 [Seedance 素材库](/models/video/seedance-2-0/material-library)。素材可用后直接复制响应返回的 `uri`，不要用 `mat_*` 自行拼接，并须在 `expires_at` 前使用。

图片和音频兼容字段 `image`、`images`、`audios` 和 `last_image` 仍可使用。不要同时通过 `content[]` 和兼容字段传入冲突内容。

视频参考请使用 `content[]` 中 `type: "video_url"`、`role: "reference_video"` 的写法。顶层 `video` / `video_url` 字段使用编辑或延长入口的语义，不能直接替代参考视频内容项。编辑或延长时需显式设置 `omni_reference_task_type` 为 `edit` 或 `extend`。

### 媒体数量限制

- 图片最多 `30` 张。
- 视频最多 `10` 个。
- 音频最多 `10` 个。
- 所有媒体合计最多 `50` 个。
- 多模态请求可以不包含文本。
- 允许仅音频参考请求。

## 操作规则

| 模式 | `omni_reference_task_type` | `duration` | `aspect_ratio` |
| --- | --- | --- | --- |
| 文生视频 | 省略或 `auto` | 省略、`"auto"`、`-1` 或整数 `4..30` | 任意支持值 |
| 单首帧 / 首尾帧生视频 | 省略或 `auto` | 省略、`"auto"`、`-1` 或整数 `4..30` | 省略或 `auto` |
| 多模态参考生成 | 显式指定时使用 `reference` | 省略、`"auto"`、`-1` 或整数 `4..30` | 由媒体模式决定；帧输入需使用 `auto` |
| 视频编辑 | 必须为 `edit` | 省略、`"auto"` 或 `-1` | 省略或 `auto` |
| 视频延长 | 必须为 `extend` | 省略、`"auto"`、`-1` 或整数 `4..30` | 省略或 `auto` |
| Draft 转成片 | 省略，自动继承 | 省略，自动继承 | 省略，自动继承 |

编辑和延长都需要提示词和源视频，不要通过提示词关键词推断操作。原有 `operation` 选择仍兼容，新示例使用 `omni_reference_task_type`。

## 请求示例

### 首尾帧生视频

```json
{
  "model": "seedance2.5",
  "prompt": "Move naturally from the first composition to the last while preserving the subject.",
  "resolution": "720p",
  "duration": 10,
  "aspect_ratio": "auto",
  "content": [
    {
      "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"
    }
  ]
}
```

单首帧模式只传 `first_frame` 项。两种帧模式都不能使用固定画幅，因为画面构图由源图片决定。

### 多模态参考生成

```json
{
  "model": "seedance2.5",
  "omni_reference_task_type": "reference",
  "resolution": "720p",
  "duration": 12,
  "content": [
    {
      "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"
    }
  ]
}
```

### 仅音频参考，无提示词

```json
{
  "model": "seedance2.5",
  "resolution": "480p",
  "duration": 4,
  "content": [
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/reference.wav"
      },
      "role": "reference_audio"
    }
  ]
}
```

### 视频编辑

```json
{
  "model": "seedance2.5",
  "prompt": "Replace the sky and preserve the subject",
  "video": "https://example.com/source.mp4",
  "omni_reference_task_type": "edit",
  "resolution": "720p",
  "duration": "auto",
  "aspect_ratio": "auto"
}
```

### 视频延长

```json
{
  "model": "seedance2.5",
  "prompt": "Continue the camera movement into the illuminated square.",
  "video": "asset://asset-EXAMPLE",
  "omni_reference_task_type": "extend",
  "resolution": "720p",
  "duration": 8,
  "aspect_ratio": "auto",
  "output_format": "mov"
}
```

### 联网搜索

```json
{
  "model": "seedance2.5",
  "prompt": "Create a concise visual recap of the latest public spaceflight milestone.",
  "resolution": "720p",
  "duration": 8,
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
```

联网搜索可以与媒体输入组合。其他 `tools` 结构不受支持。

## Draft 样片转 1080p 成片 {/* #draft-to-final */}

### 1. 创建 480p Draft

设置 `draft: true`。省略 `resolution` 时使用 `480p`；显式指定其他档位会拒绝。Draft 也可使用本页的媒体参考输入。

```bash
curl -X POST "https://api.uniai.tv/v1/videos" \
  -H "Authorization: Bearer <UNIAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.5",
    "prompt": "A mechanical bird unfolds its wings on a wooden table.",
    "draft": true,
    "duration": 4,
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "seed": 250628
  }'
```

### 2. 保存 UniAI 任务 ID 并等待完成

使用创建响应中的 `id` 或 `task_id` 查询，直到 `status` 为 `completed`。下方 `task_YOUR_COMPLETED_DRAFT` 是占位符，必须替换为你实际收到的 UniAI 任务 ID。

```bash
curl "https://api.uniai.tv/v1/videos/task_YOUR_COMPLETED_DRAFT" \
  -H "Authorization: Bearer <UNIAI_API_KEY>"
```

### 3. 提交成片请求

父任务必须是同一 UniAI 用户创建、已完成的 Seedance 2.5 Draft，且自创建起未满七天。未完成、失败、过期、非 Draft 或其他用户的任务不能复用。

```bash
curl -X POST "https://api.uniai.tv/v1/videos" \
  -H "Authorization: Bearer <UNIAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.5",
    "draft_task_id": "task_YOUR_COMPLETED_DRAFT",
    "output_format": "mov",
    "watermark": false,
    "return_last_frame": true,
    "priority": 0
  }'
```

成片默认使用 `1080p`，也可显式指定 `resolution: "1080p"`；其他分辨率会拒绝。成功提交后会返回新的成片任务 ID，按同样方式轮询。

成片继承原 Draft 的提示词、所有素材、时长、画幅、`seed`、`generate_audio` 及任务类型。请省略这些继承字段，不要重复发送相同值或尝试覆盖；`tools`、`operation` 和 `omni_reference_task_type` 也必须省略。原始 `content` 不可重复传入，即使 `generate_audio` 为 `false` 也不要重传。

可以单独设置 `output_format`、`watermark`、`return_last_frame`、`priority`、`execution_expires_after` 和 `safety_identifier`，但不能设置 `draft: true`。

也兼容仅包含一条 Draft 引用的 `content` 写法：

```json
{
  "model": "seedance2.5",
  "content": [
    {
      "type": "draft_task",
      "draft_task": {
        "id": "task_YOUR_COMPLETED_DRAFT"
      }
    }
  ]
}
```

该 `id` 同样必须使用 UniAI 返回的公开任务 ID。不要与其他文本或媒体 part 混合；若同时传入 `draft_task_id`，两处 ID 必须一致。

## 创建响应与任务生命周期

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

保存公开 `id` 或 `task_id`，建议每 2 到 5 秒调用 `GET /v1/videos/{task_id}`，直到 `status` 变为 `completed` 或 `failed`。完成后优先使用响应中的 `video_url` 下载视频；兼容响应也可能在 `result.video_url` 或 `result.outputs` 中提供结果。不要把结果 URL 当成永久存储。

普通任务也可按下方方式查询：

```bash
curl "https://api.uniai.tv/v1/videos/task_YOUR_VIDEO" \
  -H "Authorization: Bearer <UNIAI_API_KEY>"
```

如请求了 `return_last_frame: true`，完成时可读取返回的尾帧结果。1080p 视频使用 HEVC/10bit，需要兼容的播放器；MP4 和 MOV 是输出容器格式。

Seedance 2.5 请求失败、客户端超时或结果不确定时，不得自动重试创建请求。已拿到任务 ID 时继续查询原任务；没有任务 ID 时先核对原请求结果。Draft 转成片也遵守此规则。

公共状态字段、完成/失败响应和错误处理见[视频生成概览](/models/video/overview#视频任务生命周期)。本模型的禁止自动重试规则优先于通用重试建议。

## 计费说明

以各任务返回的实际 Token 用量和最终结算记录为准，预扣仅为估算。Draft 和成片是两个独立计费的任务，样片不抵扣成片，也不会被重复计为成片的输入视频。当前价格以账号可见的 UniAI 价格为准。

## 常见错误

| 错误 | 原因 | 处理方式 |
| --- | --- | --- |
| 缺少输入 | 既没有提示词，也没有媒体或有效 Draft 引用 | 提供对应工作流的必需输入。 |
| 分辨率无效 | 4K，或 Draft/成片档位不匹配 | 普通请求使用 `480p`/`720p`/`1080p`，Draft 仅 `480p`，成片仅 `1080p`。 |
| 兼容别名冲突 | `resolution` 和 `size` 的值不同 | 删除 `size` 或确保两者完全一致。 |
| 编辑时长无效 | 编辑使用整数时长 | 省略 `duration` 或设为 `"auto"`/`-1`。 |
| 画幅无效 | 首帧、首尾帧、编辑或延长请求使用固定比例 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 媒体数量超限 | 单类型或媒体总数超过限制 | 按文档限制减少媒体数量。 |
| 素材不可访问 | URL 私有、过期或无法从公网访问 | 使用稳定公开 URL 或可用的 `asset://` 素材。 |
| 联网工具无效 | `tools` 不是唯一支持的联网搜索结构 | 传 `[{"type":"web_search"}]` 或省略 `tools`。 |
| 字段不支持 | 传入 `frames`、`camera_fixed` 或 `service_tier: "flex"` | 删除不支持字段。 |
| Draft 引用无效 | 不存在、未完成、非 Draft、过期或属于其他用户 | 使用同用户未满七天的已完成 Draft 的 UniAI 任务 ID。 |
| 成片继承字段重复 | 成片请求再次传入 prompt、素材、时长、比例、seed、音频或任务类型 | 省略所有继承字段，只发送 Draft ID 和允许的输出控制。 |
| 参数类型或范围错误 | 布尔值写成字符串，或 priority、seed、过期时间超出范围 | 使用 JSON 布尔值和参数表规定的整数范围。 |

## 相关页面

- [视频生成概览](/models/video/overview)
- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance 素材库](/models/video/seedance-2-0/material-library)
- [模型列表](/models)