# Seedance 2.5 能力总览

> Doubao Seedance 2.5 视频生成：素材规格、输出格式与编码、任务类型约束、计费方式与常见问题

Seedance 2.5 是字节跳动豆包（Doubao）系列的视频生成模型，支持文生视频、首帧 / 首尾帧图生视频、多模态参考、视频编辑与视频延长，**单次生成最长 30 秒**，并可同步生成音频。LoopRouter 使用火山引擎方舟兼容接口；从 2.0 迁移时，还需检查素材数量、任务类型、宽高比和输出格式，不能只替换 `model`。

<Note>
平台支持 `output_format`（`mp4` / `mov`）和 `omni_reference_task_type`（`auto` / `reference` / `edit` / `extend`），查询结果会在上游返回时提供 `output_format`。这两个参数仅适用于 Seedance 2.5；不传时使用官方默认值。详见 [输出格式与任务类型参数](/api-capabilities/seedance25/video-generation#输出格式与任务类型参数)。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance25/video-generation">
    请求参数、素材与编码规格、任务类型约束、响应与错误码
  </Card>
  <Card title="在线调试（试一试）" icon="flask" href="/api-reference/create-video-task">
    在文档内直接发起真实请求
  </Card>
  <Card title="素材库" icon="images" href="/asset-management/asset-library">
    上传素材、管理素材组，获取 asset ID
  </Card>
  <Card title="真人认证接口" icon="user-check" href="/asset-management/real-person">
    真实人像素材的活体认证全流程 API
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="更长单段时长" icon="clock">
    时长范围扩展到 4–30 秒，一次生成即可覆盖更完整的镜头叙事
  </Card>
  <Card title="多模态参考生成" icon="layer-group">
    最多 30 张参考图、10 个参考视频、10 段参考音频，也支持仅输入音频
  </Card>
  <Card title="音画同步" icon="volume-high">
    `generate_audio` 默认开启，人声、音效与配乐与画面同步生成
  </Card>
  <Card title="高清分辨率" icon="expand">
    支持 480p / 720p / 1080p 三档输出，固定 24fps
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 |
| --- | --- |
| `doubao-seedance-2-5-260628` | 新一代标准版，支持全部生成模式，时长最长 30 秒，输出分辨率 480p / 720p / 1080p |

<Note>
模型名与火山官方快照版本号保持一致（`doubao-seedance-2-5-260628`），不需要 `ep-` 开头的接入点 ID。实际可用模型以控制台「模型广场」为准。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 首帧图生 / 首尾帧图生 / 多模态参考（参考生成、编辑、延长） |
| 分辨率 | `480p` / `720p` / `1080p`，默认 `720p`（Seedance 2.5 暂不支持 `4k`，传入 `4k` 将被 400 拒绝，不扣费） |
| 宽高比 | 默认 `adaptive`；文生视频 / 参考生成可选 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`；首帧 / 首尾帧、编辑、延长任务仅支持 `adaptive` |
| 时长 | **4–30 秒**整数，默认 `-1`（智能选择）；编辑任务仅支持 `-1`，时长跟随待编辑视频 |
| 帧率 | 固定 24fps |
| 输出格式 | `mp4`（默认）/ `mov`，通过 `output_format` 指定；MOV 请求保留上游原生规格产物 |
| 输出编码 | 官方 1080p 规格为 10bit、H.265/HEVC；MOV 另有 H.264 + yuv444p + PCM 的格式说明，见 [输出格式与编码](/api-capabilities/seedance25/video-generation#输出格式与编码) |
| 音频 | 默认生成同步音频，输出为单声道；可用 `generate_audio: false` 关闭 |
| 参考素材 | ≤30 图 + ≤10 视频 + ≤10 音频；视频总时长 ≤30 秒，音频总时长 ≤30 秒；支持仅输入音频 |
| 图片要求 | jpeg/png/webp/bmp/tiff/gif/heic/heif；宽高比 `[0.4, 2.5]`；边长 `[300, 6000]`px；单张小于 30 MB |
| 视频要求 | MP4 / MOV；视频编码 H.264/AVC 或 H.265/HEVC；24–60fps；单个 ≤200 MB；非编辑任务 2–30 秒，编辑任务 4–30 秒 |
| 音频要求 | WAV / MP3；单段 2–30 秒；单段 ≤15 MB |
| 提示词建议 | 中文 ≤500 字 / 英文 ≤1000 词；台词用双引号包裹 |
| 任务模式 | 异步任务：`queued → running → succeeded / failed / cancelled / expired` |
| 成片链接 | `content.video_url` 为临时链接；官方原始视频 URL 有效期 24 小时、最多下载 100 次；平台转存链接以实际存储策略为准 |

<Tip>
从 2.0 迁移：2.5 的时长上限为 30 秒，参考素材上限提升至 30 图 / 10 视频 / 10 音频，支持仅输入音频；输出最高 `1080p`，不支持 `4k`。首帧 / 首尾帧、编辑、延长任务必须使用 `ratio: adaptive`，编辑任务还必须使用 `duration: -1`。`output_format` 和 `omni_reference_task_type` 是 2.5 专属参数，切回 2.0 时应移除。
</Tip>

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/v3/contents/generations/tasks` | 创建视频生成任务 |
| GET | `/api/v3/contents/generations/tasks/{task_id}` | 查询单个任务 |
| GET | `/api/v3/contents/generations/tasks` | 任务列表（分页/筛选） |
| DELETE | `/api/v3/contents/generations/tasks/{task_id}` | 取消/删除任务 |
| POST | `/api/v3/assets?Action=...&Version=2024-01-01` | 素材库与真人认证（[详情](/asset-management/asset-library)） |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。路径中的 `/api` 前缀不能省略。
</Tip>

## 模型定价

计费采用**提交预扣、完成结算**的两段式流程：

<Steps>
  <Step title="提交预扣">
    任务创建成功后，按请求参数（分辨率、时长）预估并预扣一笔额度，日志中心会产生一条预扣记录。时长越长、分辨率越高，预扣越多。
  </Step>
  <Step title="完成结算">
    任务成功后按上游返回的实际用量（`usage.total_tokens`，约等于 时长 × 输出宽 × 输出高 × 24 ÷ 1024）重新计算，多退少补；任务失败则全额退回预扣。
  </Step>
</Steps>

<Info>
**视频输入折扣**：当请求 `content` 中包含参考视频（`video_url`）时，系统自动应用带视频输入的优惠倍率，无需额外传参。

**不扣费场景**：参数校验失败（400）、内容审核拒绝（403）均不产生费用。
</Info>

<Warning>
使用 `duration: -1`（模型自选时长）或 `ratio: adaptive` 时，实际费用以任务成功后响应中回填的真实时长/分辨率为准，与预扣金额可能存在差额，结算时自动多退少补。长时长任务（如 30 秒）请预留充足余额。
</Warning>

各分辨率档位的具体单价请以控制台「模型广场」与「日志中心」展示为准。实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率（具体折扣以商务对接约定为准），分组同时决定可用的分辨率档位。

## 限流与重试

- 平台按渠道维度做 RPM 智能调度：并发高峰时任务会短暂排队而不是直接失败。
- 收到 429（`当前分组上游负载已饱和，请稍后再试`）或 5xx 时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔 15–30 秒；时长越长生成耗时越久，长视频请适当延长轮询周期与超时时间。

## 常见问题

<AccordionGroup>
  <Accordion title="2.5 和 2.0 的接口有什么区别？">
    两者使用相同端点，但 2.5 的时长、素材数量、仅音频输入、输出格式与任务类型约束都有变化。尤其是首帧 / 首尾帧、编辑、延长任务仅支持 `ratio: adaptive`，编辑任务仅支持 `duration: -1`。请按 [视频生成 API](/api-capabilities/seedance25/video-generation) 检查参数，不能只替换模型名。
  </Accordion>
  <Accordion title="为什么创建任务只返回一个 id，没有视频？">
    这是异步任务接口：创建仅入队并返回任务 ID，需轮询 `GET /api/v3/contents/generations/tasks/{id}` 直到状态变为 `succeeded`，再从 `content.video_url` 下载成片。
  </Accordion>
  <Accordion title="成功状态是 completed 还是 succeeded？">
    是 `succeeded`。判断终态请匹配 `succeeded / failed / cancelled / expired` 四个值。
  </Accordion>
  <Accordion title="支持哪些分辨率？">
    Seedance 2.5 支持 `480p`、`720p`、`1080p` 三档，默认 `720p`；暂不支持 `4k`（传入 `4k` 会返回 400 且不扣费）。
  </Accordion>
  <Accordion title="支持 callback 回调吗？">
    不支持。`callback_url` 会被 400 拒绝，请使用轮询获取任务结果。
  </Accordion>
  <Accordion title="MP4 和 MOV 的编码、播放兼容性有什么区别？">
    官方默认输出 MP4，1080p 规格采用 10bit 与 H.265/HEVC，播放器需支持相应解码。设置 `output_format: mov` 可选择面向专业后期的 MOV，官方格式说明为 H.264 + yuv444p + PCM，部分播放器不兼容。MOV 请求保留上游原生规格产物。输入视频的容器与编码要求见 [素材要求](/api-capabilities/seedance25/video-generation#素材要求)。
  </Accordion>
  <Accordion title="视频链接过期了怎么办？">
    官方原始视频 URL 有效期为 24 小时，Seedance 2.5 视频 URL 最多下载 100 次；平台转存链接的有效期以实际存储策略为准。请在任务成功后尽快下载并转存，不要依赖重新查询来刷新过期链接。任务记录仍可查询不代表视频文件永久可下载。
  </Accordion>
  <Accordion title="能直接用真人照片作参考图吗？">
    不能。出于防深度伪造要求，真实人脸图片不能直接放入 `image_url`（会被内容审核 403 拒绝）。需先完成 [真人认证](/asset-management/real-person)，把照片上传到认证素材组，再以 `asset://素材ID` 引用。
  </Accordion>
  <Accordion title="Python 请求报 JSON 解析错误 / 响应被截断？">
    在请求头加 `Accept-Encoding: identity`。个别网络环境下网关 gzip 协商会导致 `requests` 解码异常。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance25/video-generation">
    参数与响应详解
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    端到端角色一致性教程
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频
  </Card>
</CardGroup>