# Seedance 2.5 参数与使用规则

> 汇总自字节跳动 Seed 官方发布说明、即梦 / fal / reAPI / Segmind / Atlas 等公开 API 文档（检索日：2026-08-13）。  
> 第三方网关字段名可能略有差异；**本仓库实际提交以火山方舟 `content` 多模态格式为准**（见文末「本仓库映射」）。

相关链接：

- 官方发布：[一镜成片，随心参考｜Seedance 2.5](https://seed.bytedance.com/zh/blog/one-take-creation-flexible-referencing-introducing-seedance-2-5)
- 项目页：[seedance2_5](https://seed.bytedance.com/seedance2_5)
- 使用指南（即梦/BytePlus 系公开稿）：[How To Use Seedance 2.5](https://fal.ai/learn/devs/how-to-use-seedance-2-5)
- 参数参考示例：[reAPI Seedance 2.5](https://reapi.ai/docs/seedance-2-5)、[fal reference-to-video](https://fal.ai/models/bytedance/seedance-2.5/reference-to-video/api)

拆镜与分集产品规则见：[EPISODE_RULES.md](./EPISODE_RULES.md)、[SHOT_SPLITTING.md](./SHOT_SPLITTING.md)。

---

## 1. 模型定位（相对 2.0）

| 能力 | Seedance 2.0（常见公开口径） | Seedance 2.5 |
|------|------------------------------|--------------|
| 单次生成时长 | 约 4–15s（部分渠道到 15s） | **4–30s**（可 `-1` / auto） |
| 参考图 | 最多约 9 | **最多 30** |
| 参考视频 | 最多约 3 | **最多 10**（合计时长 ≤ ~30s） |
| 参考音频 | 最多约 3 | **最多 10**（合计时长 ≤ ~30s） |
| 仅音频参考 | 通常需配图/视频 | **支持 audio-only**（2.5） |
| 原生分辨率 | 视渠道；部分 2.0 有 1080p | 公开 API 多为 **480p / 720p**（无原生 1080p/4K） |
| 长叙事 | 偏短片段 | 单次可组织多镜头；支持多轮延长 |
| 编辑 | 有 | 强化时间戳编辑、绿幕/视角/参考编辑 |

---

## 2. 生成模式（由输入推断，无需单独 mode 字段）

多数网关按「塞了哪些媒体」隐式分流：

| 模式 | 典型触发 | 说明 |
|------|----------|------|
| Text-to-video | 仅文本 | `prompt` 必填 |
| Image-to-video / 首尾帧 | `first_frame` / `last_frame`（或 `image_with_roles`） | 画幅常锁定为首帧；首尾帧比例宜一致 |
| Reference-to-video | 参考图 / 视频 / 音频 + 描述性 prompt | 多模态参考生视频；引用写法见 §4 |
| Video edit | 参考视频 + prompt 含「编辑/替换/改…」意图 | **时长通常只能 auto/`-1`**，画幅跟随源片 |
| Video extend | 参考视频 + prompt 含「延长/续写」意图 | 画幅跟随源片；时长可设 |

注意：edit / extend 常由 **prompt 措辞异步判定**。若出现「duration/ratio 参数错误」，先去掉编辑/延长类措辞，或按上表改参数。

---

## 3. 核心 API 参数一览

下列为公开文档中的常见字段（英文网关命名）。火山方舟侧等价项见 §7。

| 参数 | 类型 | 常见默认 | 规则 |
|------|------|----------|------|
| `model` | string | — | 如 `doubao-seedance-2.5-*` / 渠道别名 |
| `prompt` / text | string | — | 纯文生必填；有参考时可省略。部分渠道上限约 2 万字 |
| `duration` | int | `5` | **4–30**；`-1` / `auto` 由模型择优。编辑任务多用 `-1` |
| `resolution` | string | `720p` | **`480p` / `720p`**（2.5 公开原生档） |
| `ratio` / `aspect_ratio` / `size` | string | `adaptive` | `16:9` `9:16` `1:1` `4:3` `3:4` `21:9` `adaptive` |
| `generate_audio` | bool | `true` | 原生配音 + 音效 + BGM；关闭则通常无对白/配乐 |
| `watermark` | bool | 视渠道 | 是否水印 |
| `return_last_frame` | bool | `false` | 返回尾帧，便于镜头衔接 / 延长 |
| `seed` | int | 随机 | 近似可复现 |
| 参考图 | URL[] | — | 最多 **30**；单张常见上限约 30MB / ≤4K |
| 参考视频 | URL[] | — | 最多 **10**；单段约 **2–30s**，合计 ≤ **~30s**；单文件约 ≤200MB |
| 参考音频 | URL[] | — | 最多 **10**；单段约 **2–30s**，合计 ≤ **~30s**；单文件约 ≤15MB（wav/mp3） |

### 3.1 参考素材硬限制（务必遵守）

| 素材 | 数量上限 | 时长 | 其它 |
|------|----------|------|------|
| 图 | ≤ 30 | — | jpeg/png/webp 等；公网 URL |
| 视频 | ≤ 10 | 单段 ~2–30.2s，**合计 ≤ ~30.2s** | mp4/mov；边长约 300–6000px；比例约 0.4–2.5；帧率约 24–60 |
| 音频 | ≤ 10 | 单段 ~2–30.2s，**合计 ≤ ~30.2s** | wav/mp3 |

稳定性建议（非硬上限，来自公开使用指南）：

- 主体参考图：优先 **1–8** 个不同主体
- 主体参考视频：优先 **1–5** 主体，每主体约 5–10s
- 音频：只留与任务直接相关的声线 / 对白 / 环境 / 音乐
- 多视角同一主体：拆成多张独立图，避免一张拼贴

### 3.2 任务类型与参数锁定

| 任务 | 画幅 | 时长 |
|------|------|------|
| 视频编辑 | 锁定源视频；不可另设 | 约等于源时长（误差约 ±0.3–0.4s）；常用 `-1` |
| 首帧 / 首尾帧 | 锁定首帧比例 | 可设 |
| 视频延长 | 锁定源视频 | 可设 4–30 |

首尾帧：两张图比例不一致时，尾帧可能被拉伸。

---

## 4. Prompt 与引用写法

### 4.1 基础公式（公开指南）

```
主体 + 动作/事件 +（场景）+（画风）+（景别/运镜/切镜）+（音频）
```

示例要素：谁在做什么 → 环境光影 → 中景推近再切正面 → 保留环境音。

### 4.2 参考素材必须在文案里「指名」

不要只靠图上的文字标签。推荐：

```
@Image 1 / 参考图1 定义角色外貌与服装（不要用图中背景）
@Video 1 / 参考视频1 定义运镜节奏（不要用片中人物身份）
@Audio 1 / 参考音频1 定义声线与指定对白
```

多主体时逐个绑定，禁止「图 1–4 分别是四个角色」这种含糊写法。

### 4.3 音字特殊语法（即梦公开稿）

| 内容 | 语法 | 例 |
|------|------|----|
| 音乐 | `()` | `(轻柔钢琴铺底)` |
| 音效 | `<>` | `<雷声滚过>` |
| 对白 | `{}` | `{你好，欢迎回来。}` |
| 字幕 | `【】` | `【第一章：启程】` |

非中文对白：先声明语种，再写 `{台词}`。

### 4.4 长视频（≤30s）叙事

- 用 **阶段 + 结束态**：每阶段只做一次主要状态变化，并写清镜头末可见状态  
- 需要卡点时用 **时间戳**（`0-5秒` / `5-10秒`），区间应连续、少重叠  
- 时间戳是节奏预算，不是精确剪辑点；不要要求「1 秒内做完三个动作」  
- 多镜头可用 `Shot 1:` / `Shot 2:` 或中文「镜 1 / 镜 2」

### 4.5 编辑 / 延长措辞示例

- 编辑：明确「编辑 @视频1，保持…不变，仅改…」  
- 延长：明确「延长 @视频1，衔接画面与主体继续生成…」

误用编辑/延长措辞会导致任务被重分类并触发参数校验失败。

---

## 5. 输出与异步

- 提交多为异步：`task_id` → 轮询至成功  
- 输出常见为 mp4；部分渠道支持 mov（后期友好、兼容性较差）  
- `return_last_frame=true` 时返回尾帧 URL，便于下一镜衔接  
- 结果 URL 可能过期，应落自有 OSS  

---

## 6. 实践红线（跨文档共识）

1. **单条 reference_audio / reference_video 勿超过 ~30s**；多条合计也不要超过 ~30s。  
2. **2.5 原生分辨率按 480p/720p 规划**；更高清多为渠道后处理，不是模型原生档。  
3. 参考图与「仅首尾帧」在部分网关 **互斥**；混用前查渠道说明。  
4. 参考 URL 需 **公网可访问**（本仓库会走 OSS 公开链）。  
5. 空镜 / 纯画面描写不要写成对白口播；否则易被烧字幕（本仓库会纠正「空镜：」误标）。  
6. `generate_audio=false` 时通常无口播与配乐——短剧口播场景保持 `true`。

---

## 7. 本仓库（PRINTFILM / drama）映射

代码入口：`backend/app/services/drama/build_seedance_generate_body.py`、`seedance_segments.py`、`ark.py`。

| 产品侧 | 提交字段 / 行为 |
|--------|-----------------|
| 顶栏模型 | `model` |
| 画幅 / 清晰度 | `ratio`、`resolution`（默认常为 `9:16` + `480p`） |
| 脚本 `@duration` 合计 | `duration`（钳制约 4–30） |
| 分镜正文 + 强制约束块 | `content[]` 中 `type=text` |
| 角色/场景封面 | `image_url` + `role=reference_image` |
| 角色/旁白试听 | **暂不提交** `reference_audio`；口播由 `generate_audio` 自发挥 |
| 原生配音 | `generate_audio: true` |
| 水印 | `watermark: false` |
| 尾帧 | `return_last_frame: true` |

提示词组装顺序（摘要）：

1. 【强制约束：视频画面风格】  
2. 【强制约束：音频、字幕与配乐】  
3. 角色形象 / 场景 / 道具 → 参考图序号  
4. 正文：`@asset` →「名称（参考图 N）」（正文已有同名则不叠写）；`@duration:N` → `00:00-00:04` 时间区间  

（角色/旁白音色 → 参考音频：暂关）  

分镜 cue：

- 画面 / 空镜 → `【画面·无配音仅环境音】`（禁止配音与字幕）  
- 旁白 → `【旁白·慢速清晰·同步字幕】`  
- 对白 → `【对白·慢速清晰·同步字幕】`  
- 漫剧字幕 cue → `【字幕：底部居中·简体中文·逐句轮换·与口播同步】`

单镜脚本内建议：`@duration` 单段 3–12s，镜合计 ≤ 30s（与 Seedance 单次上限对齐）。

---

## 8. 资料来源与维护

| 来源 | 用途 |
|------|------|
| ByteDance Seed 博客（2026-07-31） | 2.5 能力口径：30s、30/10/10 参考、编辑与延长 |
| fal / BytePlus「How To Use Seedance 2.5」 | Prompt 公式、时间戳、编辑参数锁定、素材建议量 |
| reAPI / fal / Segmind / Atlas API 页 | duration / resolution / ratio / 参考时长等硬限制 |
| 本仓库代码 | 方舟 `content` 形态与 drama 生产 cue |

上游若调整上限，以火山方舟 / 即梦最新文档为准，并同步改本页与 `voice_reference_audio.py` 等常量。