# Seedance 2.5 视频生成 API

> Seedance 2.5 异步视频生成：MP4/MOV 输出、参考生成与编辑/延长参数、素材格式与编码、任务约束

Seedance 2.5 视频生成采用**异步任务**模式：先提交任务拿到任务 ID，再轮询查询接口获取成片。LoopRouter 使用火山引擎方舟兼容端点，支持最长 30 秒、最高 `1080p` 输出，并支持 `output_format` 和 `omni_reference_task_type`。从 [Seedance 2.0](/api-capabilities/seedance2/video-generation) 迁移时，需重新检查素材数量、任务类型及 `ratio` / `duration` 限制。

<Info>
想先在浏览器里体验？打开 [API 参考 → 创建视频生成任务](/api-reference/create-video-task)，填入你的 `sk-` API Key 即可**试一试**在线发起真实请求。
</Info>

<Tip>
文生视频、图生视频、多模态参考共用同一个接口，模型根据 `content` 素材及提示词判断任务类型。模型清单、定价与常见问题见 [能力总览](/api-capabilities/seedance25/overview)。
</Tip>

<Warning>
**接入前请注意以下差异点，可以避开绝大多数排障时间：**

1. Base URL 为 `https://api.looprouter.com`，完整路径是 `/api/v3/contents/generations/tasks`，`/api` 前缀不能省略。
2. `resolution` 支持 `480p` / `720p` / `1080p`（默认 `720p`；Seedance 2.5 暂不支持 `4k`）。传入 `4k` 会直接返回 400，不会扣费。
3. `duration` 默认 `-1`，支持 4–30 秒整数；编辑任务仅支持 `-1`。首帧 / 首尾帧、编辑、延长任务的 `ratio` 仅支持 `adaptive`。
4. 本接口**不支持** `callback_url` 回调，传入会返回 400；请使用轮询查询任务状态。
5. 成功状态是 `succeeded`（不是 `completed`）；成片 `content.video_url` 为临时链接，请及时转存，详见[查询任务](#查询任务)。
6. Python `requests` 用户建议加请求头 `Accept-Encoding: identity`，避免个别网络环境下 gzip 解码异常导致响应截断。
7. `output_format` / `omni_reference_task_type` 仅适用于 Seedance 2.5。平台原样透传显式值，不传时使用上游默认的 `mp4` / `auto`；参数合法性与任务类型约束由上游校验。
</Warning>

## 代码示例

<CodeGroup>

```bash 创建任务（cURL）
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {
        "type": "text",
        "text": "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 10
  }'

# 返回：{"id": "task_xxxx"} —— 只返回任务 ID，视频需轮询查询接口获取
```

```python 完整流程（Python）
import time
import requests

BASE = "https://api.looprouter.com"
HEADERS = {
    "Authorization": "Bearer sk-你的APIKey",
    "Accept-Encoding": "identity",  # 避免个别环境 gzip 解码异常
}

# 1. 创建任务
resp = requests.post(
    f"{BASE}/api/v3/contents/generations/tasks",
    headers=HEADERS,
    json={
        "model": "doubao-seedance-2-5-260628",
        "content": [
            {"type": "text", "text": "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过"}
        ],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 10,          # 2.5 支持 4~30 秒
        "output_format": "mp4",  # 可改为 mov，用于专业后期
        # "generate_audio": True,  # 默认开启同步音频
    },
)
resp.raise_for_status()
task_id = resp.json()["id"]
print("任务已创建:", task_id)

# 2. 轮询任务状态（建议 15~30 秒一次；长时长任务可适当延长）
while True:
    task = requests.get(
        f"{BASE}/api/v3/contents/generations/tasks/{task_id}",
        headers=HEADERS,
    ).json()
    status = task["status"]
    print("当前状态:", status)
    if status in ("succeeded", "failed", "cancelled", "expired"):
        break
    time.sleep(20)

# 3. 下载成片（下载时不要携带 Authorization 头）
if status == "succeeded":
    video_url = task["content"]["video_url"]
    output_format = task.get("output_format", "mp4")
    filename = f"output.{output_format}"
    with requests.get(video_url, stream=True) as r:
        r.raise_for_status()
        with open(filename, "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)
    print("已保存", filename)
else:
    print("任务未成功:", task.get("error"))
```

```python 图生视频与多模态参考（Python）
# 模式二：首尾帧图生视频 —— 用两张图约束视频的第一帧和最后一帧
first_last_frame_body = {
    "model": "doubao-seedance-2-5-260628",
    "content": [
        {"type": "text", "text": "镜头缓缓推进，人物转身微笑"},
        {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
        {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"},
    ],
    "resolution": "720p",
    "ratio": "adaptive",  # 2.5 首帧 / 首尾帧任务仅支持 adaptive
    "duration": 8,
}

# 模式三：多模态参考 —— 参考图 / 参考视频 / 参考音频自由组合
multimodal_body = {
    "model": "doubao-seedance-2-5-260628",
    "omni_reference_task_type": "reference",
    "content": [
        {"type": "text", "text": "根据图片1中的角色生成一段在草地上奔跑的新视频"},
        {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"},
        # {"type": "video_url", "video_url": {"url": "https://example.com/ref.mp4"}, "role": "reference_video"},
        # {"type": "audio_url", "audio_url": {"url": "https://example.com/voice.mp3"}, "role": "reference_audio"},
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": -1,  # -1 表示由模型自行决定时长，按实际产出计费
}
```

```javascript Node.js
const BASE = "https://api.looprouter.com";
const KEY = process.env.LOOPROUTER_API_KEY;

async function main() {
  // 创建任务
  const createRes = await fetch(`${BASE}/api/v3/contents/generations/tasks`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${KEY}`,
    },
    body: JSON.stringify({
      model: "doubao-seedance-2-5-260628",
      content: [
        { type: "text", text: "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过" },
      ],
      resolution: "720p",
      ratio: "16:9",
      duration: 10,
    }),
  });
  const { id } = await createRes.json();
  console.log("任务已创建:", id);

  // 轮询
  for (;;) {
    await new Promise((r) => setTimeout(r, 20000));
    const task = await (
      await fetch(`${BASE}/api/v3/contents/generations/tasks/${id}`, {
        headers: { Authorization: `Bearer ${KEY}` },
      })
    ).json();
    console.log("当前状态:", task.status);
    if (["succeeded", "failed", "cancelled", "expired"].includes(task.status)) {
      if (task.status === "succeeded") console.log("视频地址:", task.content.video_url);
      else console.error("任务未成功:", task.error);
      break;
    }
  }
}

main();
```

```bash 查询任务（cURL）
curl "https://api.looprouter.com/api/v3/contents/generations/tasks/task_xxxx" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

</CodeGroup>

## 请求参数速查

`POST /api/v3/contents/generations/tasks`，请求头 `Authorization: Bearer sk-...`。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 如 `doubao-seedance-2-5-260628`，可用模型以控制台「模型广场」为准 |
| `content` | array | 是 | — | 生成素材数组，见下方[内容项说明](#content-数组) |
| `resolution` | string | 否 | `720p` | `480p` / `720p` / `1080p`（Seedance 2.5 暂不支持 `4k`，传入 `4k` 返回 400 且不扣费） |
| `ratio` | string | 否 | `adaptive` | 文生视频 / 参考生成可选 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`；首帧 / 首尾帧、编辑、延长任务仅支持 `adaptive` |
| `duration` | int | 否 | `-1` | 输出时长（秒），范围 **4–30**；`-1` 表示智能选择；编辑任务必须为 `-1`，输出时长跟随待编辑视频 |
| `generate_audio` | bool | 否 | `true` | 是否生成与画面同步的单声道音频（人声/音效/配乐） |
| `watermark` | bool | 否 | `false` | 是否叠加 AI 生成水印 |
| `output_format` | string | 否 | `mp4` | `mp4` / `mov`；输出容器格式，MOV 请求保留上游原生输出 |
| `omni_reference_task_type` | string | 否 | `auto` | `auto` / `reference` / `edit` / `extend`；多模态参考任务的子类型引导，详见下方[任务约束](#任务类型与参数约束) |
| `return_last_frame` | bool | 否 | `false` | 成功后额外返回无水印 PNG 末帧图，尺寸与输出视频一致，便于多段续接 |
| `execution_expires_after` | int | 否 | `172800` | 从任务创建时间起计算的超时秒数，范围 `[3600, 259200]`；超时未完成转为 `expired` |

<Warning>
`callback_url` 在本平台**不受支持**，传入会返回 400。官方未将 Seedance 2.5 列入 `seed`、`frames`、`camera_fixed` 的支持模型，也不支持 `service_tier: flex`；请勿把这些字段用于 2.5 请求。
</Warning>

### 输出格式与任务类型参数

这两个参数仅适用于 **Seedance 2.5**，平台透传至上游；省略时不额外填值，由上游应用默认值。切换为 Seedance 2.0 或其他不支持的模型时应移除。

| 参数 | 类型 | 默认值 | 取值与作用 |
| --- | --- | --- | --- |
| `output_format` | string | `mp4` | `mp4` / `mov`，选择输出容器格式，详见[输出格式与编码](#输出格式与编码) |
| `omni_reference_task_type` | string | `auto` | `auto` / `reference` / `edit` / `extend`，仅用于全模态参考任务的子类型引导 |

`omni_reference_task_type` 只用于全模态参考，文生视频、首帧 / 首尾帧任务不需要设置。`auto` 由模型按素材和提示词判断任务类型；显式设置 `reference` / `edit` / `extend` 时，上游会在提交阶段提前校验对应参数，但实际意图与指定类型不一致时仍可能异步失败。

### content 数组

每个元素为一个内容项，`type` 决定其结构：

| type | 结构 | role 取值 | 说明 |
| --- | --- | --- | --- |
| `text` | `{"type":"text","text":"..."}` | — | 提示词。建议中文 ≤500 字、英文 ≤1000 词；台词放在双引号内可提升配音效果 |
| `image_url` | `{"type":"image_url","image_url":{"url":"..."},"role":"..."}` | `first_frame` / `last_frame` / `reference_image` | 支持公网 URL、Base64 data URI、`asset://素材ID` |
| `video_url` | `{"type":"video_url","video_url":{"url":"..."},"role":"reference_video"}` | `reference_video` | 公网 URL 或 `asset://素材ID`，不支持视频 Base64；最多 10 个，总时长 ≤30 秒；携带视频输入享受[计费折扣](/api-capabilities/seedance25/overview#模型定价) |
| `audio_url` | `{"type":"audio_url","audio_url":{"url":"..."},"role":"reference_audio"}` | `reference_audio` | 公网 URL、Base64 data URI 或 `asset://素材ID`；WAV / MP3，单段 2–30 秒，最多 10 段，总时长 ≤30 秒；支持仅输入音频 |

### 素材要求

| 素材 | 格式 | 数量、时长及大小 |
| --- | --- | --- |
| 图片 | JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF | 首帧 1 张、首尾帧 2 张，或多模态参考最多 30 张；单张小于 30 MB |
| 视频 | MP4 / MOV，支持编码见下表 | 最多 10 个，总时长 ≤30 秒；非编辑任务单个 2–30 秒，编辑任务单个 4–30 秒；单个 ≤200 MB |
| 音频 | WAV / MP3 | 最多 10 段，单段 2–30 秒，总时长 ≤30 秒；单段 ≤15 MB |

- 图片和视频的宽高比均为 `[0.4, 2.5]`，宽、高均为 `[300, 6000]` 像素，均包含边界值。
- 输入视频支持 `480p` / `720p` / `1080p` / `4k`，总像素数（宽 × 高）须在 `[407696, 8295044]`，帧率为 `[24, 60]` FPS。**支持 4k 输入不代表支持 4k 输出**。
- 请求体不超过 64 MB；图片和音频可使用 Base64 data URI，大文件应使用 URL 或素材 ID；视频不支持 Base64。

**输入视频的容器与编码必须同时满足要求：**

| 容器 | 扩展名 | MIME | 视频编码 | 音频编码 |
| --- | --- | --- | --- | --- |
| MP4 | `.mp4` | `video/mp4` | H.264/AVC、H.265/HEVC | AAC、MP3 |
| QuickTime | `.mov` | `video/quicktime` | H.264/AVC、H.265/HEVC | AAC、MP3、PCM |

修改文件扩展名不会改变实际编码。**含真人人脸的图片或视频不能直接上传作为参考素材**；授权真人素材需先走 [素材库](/asset-management/asset-library) 与 [真人认证](/asset-management/real-person)，再以 `asset://` 引用。

### 生成模式

| 模式 | content 组合 |
| --- | --- |
| 文生视频 | 1 个 `text` |
| 首帧图生视频 | 可选 `text` + 1 个 `image_url`（role 可省略） |
| 首尾帧图生视频 | 可选 `text` + 2 个 `image_url`（role 必须分别为 `first_frame`、`last_frame`） |
| 多模态参考 | 可选 `text` + 0–30 张参考图 + 0–10 个参考视频 + 0–10 段参考音频（至少 1 个素材，允许仅音频） |

首帧、首尾帧、多模态参考是互斥场景：不能把 `first_frame` / `last_frame` 与参考图、参考视频或参考音频混用。多模态参考中可通过提示词描述首尾画面；如需严格约束首尾帧，应使用首尾帧模式。

### 任务类型与参数约束

| 任务类型 | 输入要求 | ratio | duration |
| --- | --- | --- | --- |
| 文生视频 | 文本提示词 | `adaptive` 或指定比例 | `-1` 或 4–30 秒整数 |
| 首帧 / 首尾帧图生视频 | 对应首帧 / 首尾帧图片 | 仅 `adaptive`，跟随首帧图片 | `-1` 或 4–30 秒整数 |
| 参考生成（`reference`） | 至少 1 个参考素材 | `adaptive` 或指定比例 | `-1` 或 4–30 秒整数 |
| 视频编辑（`edit`） | 至少 1 个 `reference_video`，单个 4–30 秒 | 仅 `adaptive`，跟随待编辑视频 | 仅 `-1`，跟随待编辑视频 |
| 视频延长（`extend`） | 至少 1 个 `reference_video`，单个 2–30 秒 | 仅 `adaptive`，跟随待延长视频 | `-1` 或 4–30 秒整数 |

<Warning>
平台转发 `omni_reference_task_type`、`ratio` 和 `duration`，不会因为选择了 `edit` / `extend` 就自动修正比例或时长。调用方界面选择编辑时，应锁定并提交 `ratio: adaptive`、`duration: -1`；选择延长时，只需锁定比例为 `adaptive`，时长仍可选择 `-1` 或 4–30 秒整数。不要把原视频的具体宽高比或秒数代替编辑任务要求的特殊值；不符合任务约束的参数由上游拒绝。
</Warning>

编辑任务的实际成片可能为非整数秒，可能比待编辑视频略短（官方说明误差约 0.4 秒）。提示词应明确说明生成新视频、编辑现有视频，或向前 / 向后延长，避免模型判定的任务类型与参数配置冲突。

例如，编辑一段 4–30 秒参考视频并输出 MOV，向创建任务接口提交以下 JSON：

```json 编辑视频并输出 MOV
{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {"type": "text", "text": "编辑视频1，将天空改为日落时分的暖色，保留原有主体动作和镜头"},
    {"type": "video_url", "video_url": {"url": "https://example.com/source.mov"}, "role": "reference_video"}
  ],
  "omni_reference_task_type": "edit",
  "output_format": "mov",
  "resolution": "1080p",
  "ratio": "adaptive",
  "duration": -1
}
```

延长视频时将任务类型改为 `extend`，在提示词中明确向前或向后延长；仍使用 `ratio: adaptive`，`duration` 可为 `-1` 或 4–30 秒整数。

## 输出格式与编码

通过 `output_format` 选择输出容器；这不是直接指定 H.264 / H.265 的编码参数。**显式请求 `mov` 时，平台保留上游原生规格产物**，容器、色度采样与音频编码保持不变。默认或显式请求 `mp4` 的任务按平台默认交付策略处理。

以下为**官方原始产物规格**；MP4 产物请以下载文件的实际媒体信息为准。

| 官方输出格式 | 用途与编码说明 |
| --- | --- |
| `mp4`（默认） | 常规播放与分发；官方分辨率说明中，2.5 的 1080p 输出采用 10bit 位深与 H.265/HEVC 编码 |
| `mov` | 调色、抠像、合成等专业后期；官方 MOV 专项说明为 H.264 视频编码 + yuv444p 色度采样 + PCM 音频编码，推荐用于视频编辑 / 延长的输入与输出 |

<Note>
官方分别列出了「1080p：10bit / H.265」和「MOV：H.264 / yuv444p / PCM」的说明，未在该接口文档中明确 `1080p + mov` 组合的位深与编码优先规则，因此不能把所有 MOV 都写成 H.265，也不能仅凭扩展名推断位深。需要特定规格时，请检查实际文件的媒体信息。
</Note>

输出帧率固定为 24fps，有声视频为单声道。H.265/HEVC 和 MOV 的 yuv444p / PCM 在部分浏览器或播放器中可能不兼容；官方列出的 MOV 兼容播放器包括 VLC、mpv、ffplay，以及 macOS 上的 IINA。

## 查询任务

`GET /api/v3/contents/generations/tasks/{task_id}`

任务状态机：`queued → running → succeeded / failed / cancelled / expired`。任务记录长期保留，可随时回查。

成功响应示例：

```json
{
  "id": "task_xxxx",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "content": {
    "video_url": "https://api.looprouter.com/.../output.mp4?...",
    "last_frame_url": ""
  },
  "usage": {
    "completion_tokens": 493680,
    "total_tokens": 493680
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 10,
  "framespersecond": 24,
  "generate_audio": true,
  "output_format": "mp4",
  "created_at": 1752940800,
  "updated_at": 1752941120
}
```

<Warning>
成片地址在 `content.video_url` 字段，为**临时链接**。官方原始视频 URL 有效期为 24 小时，Seedance 2.5 视频 URL 下载次数上限为 100 次；平台转存链接的有效期以实际存储策略为准。请及时下载并转存，不要依赖重新查询来刷新过期链接；下载时**不要**携带 `Authorization` 头。
</Warning>

`output_format` 返回上游生成视频的格式（`mp4` / `mov`），单任务查询与任务列表均保留此字段。旧任务或上游未返回时会省略，请勿只凭下载 URL 的后缀判断格式。

查询返回的 `duration` 为整数秒约数，按「实际总帧数 ÷ 24，向下取整」计算，不保证等于文件的精确时长。例如 133 帧对应约 5.54 秒，接口返回 `duration: 5`。

<Info>
`usage.total_tokens` 为上游按「时长 × 分辨率像素 × 帧率」口径折算的视频 token 数，是结算依据。使用 `duration: -1` 或 `ratio: adaptive` 时，以响应中回填的实际值为准。
</Info>

## 任务列表与取消

本平台提供以下两个任务管理接口（列表参数与保留策略以本平台为准）：

**列出任务** — `GET /api/v3/contents/generations/tasks`

| 查询参数 | 说明 |
| --- | --- |
| `page_num` | 页码，默认 1 |
| `page_size` | 每页数量，默认 20，最大 500 |
| `filter.status` | 按状态过滤：`queued` / `running` / `succeeded` / `failed` / `cancelled` |
| `filter.model` | 按模型过滤 |
| `filter.task_ids` | 按任务 ID 列表过滤 |

响应为 `{"items": [...], "total": n}`，元素结构与查询单个任务一致。

**取消/删除任务** — `DELETE /api/v3/contents/generations/tasks/{task_id}`

排队中的任务可以取消；`running` 状态的任务不可取消（返回 400 `invalid_task_status`）。成功返回 `{}`。

## 错误响应

所有错误采用与火山引擎一致的结构：

```json
{
  "error": {
    "code": "invalid_request",
    "message": "具体错误描述 (request id: ...)",
    "param": "",
    "type": "BadRequest"
  }
}
```

| HTTP 状态码 | type | 常见原因 |
| --- | --- | --- |
| 400 | `BadRequest` | 缺少 `model`/`content`；`resolution` 传入 `4k`（2.5 不支持）；`duration` 既非 `-1` 也非 4–30 秒整数；素材或任务参数不兼容；传了 `callback_url`；取消运行中任务 |
| 401 | `Unauthorized` | API Key 缺失或无效 |
| 403 | `Forbidden` | 令牌无权访问该模型；内容审核未通过（如真实人脸直传） |
| 404 | `NotFound` | 任务 ID 不存在或不属于当前账号 |
| 429 | `RateLimitExceeded` | 当前分组上游负载已饱和，请稍后再试 |
| 5xx | `InternalServerError` | 服务端异常，建议指数退避后重试 |

<Info>
429 与 5xx 建议采用指数退避重试（如 2s → 4s → 8s）。参数校验失败（400）与内容审核拒绝（403）**均不扣费**；已预扣的失败任务会自动退款。
</Info>

部分任务类型错误会在创建成功后异步返回。查询到 `status: failed` 时检查 `error.code`：`InvalidParameter.TaskTypeConstraint` 表示参数与模型判定的任务类型不兼容；官方显式任务类型与实际意图不一致时则为 `InvalidParameter.TaskTypeMismatch`。

## 核对依据

本页模型规格依据火山引擎官方 [创建视频生成任务](https://docs.volcengine.com/docs/82379/1520757)（2026-08-21 更新）与 [查询视频生成任务](https://docs.volcengine.com/docs/82379/1521309)（2026-08-19 更新）的文档快照核对；平台差异单独标明。

## 相关文档

<CardGroup cols={3}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/seedance25/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    从上传素材到角色一致性生成的完整链路
  </Card>
  <Card title="在线调试" icon="flask" href="/api-reference/create-video-task">
    在文档内直接试一试
  </Card>
</CardGroup>