> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.vncps.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 视频生成节点

> 在 ComfyUI 中使用豆包 Seedance API 生成高质量视频（支持并发与提示词分行）

## 节点概述

<Note>
  **节点标识：** `artsmcp-seedance`\
  **技术栈：** Doubao Seedance\
  **功能：** 调用豆包 Seedance API 进行文生视频、图生视频（单图/多图）、并发批量生成
</Note>

### 支持的生成模式

* ✅ 文生视频：仅输入提示词生成视频
* ✅ 图生视频：单图或多图作为参考生成视频
* ✅ 首尾帧视频：两张图控制视频起始与结束画面
* ✅ 并发批量生成：相同提示词多次生成，或多行提示词分行生成
* ✅ 自动轮询任务状态并下载视频
* ✅ 返回标准 VIDEO 类型，直接接 SaveVideo/Preview Video

***

## 节点界面

<img src="https://mintcdn.com/shihuo/mt4Mlxceh9rUNmi5/images/seedance_run.png?fit=max&auto=format&n=mt4Mlxceh9rUNmi5&q=85&s=28bd06936e8b93ec62116be812d06d71" alt="Seedance 节点配置与运行界面" width="2430" height="1455" data-path="images/seedance_run.png" />

***

## 必需参数

### 基础配置

| 参数名称      | 说明                | 示例值                              | 备注             |
| --------- | ----------------- | -------------------------------- | -------------- |
| **提示词**   | 视频生成的文字描述         | `"一个机器人在未来城市中行走..."`             | 支持多行，配合分行功能使用  |
| **API密钥** | Seedance API 密钥   | `sk-xxx`                         | 在控制台令牌管理中获取    |
| **API地址** | Seedance API 服务端点 | `https://api.cozex.cn`           | 可改为自定义网关/中转站   |
| **模型**    | Seedance 模型版本     | `doubao-seedance-1-5-pro-251215` | 推荐使用最新 1.5 Pro |

<Info>
  模型选项通常包括：

  * `doubao-seedance-1-5-pro-251215`：**推荐，最新版，支持音频生成**；
  * `doubao-seedance-1-0-pro-fast-251015`：快速版；
  * `doubao-seedance-1-0-pro-250528`：标准版。
</Info>

### 输入图片（可选）

| 参数名称      | 说明         | 备注           |
| --------- | ---------- | ------------ |
| **参考图片1** | 图生视频/首帧参考图 | 可为空（纯文生视频）   |
| **参考图片2** | 图生视频/尾帧参考图 | 可为空，仅首帧时只填 1 |

***

## 视频配置参数

<ParamField path="分辨率" type="string" default="1080p">
  视频分辨率。

  **可选值：**

  * `480p`：预览/调试；
  * `720p`：推荐使用，质量与速度平衡；
  * `1080p`：高清输出，生成时间更长。
</ParamField>

<ParamField path="宽高比" type="string" default="16:9">
  视频宽高比。

  **可选值：**

  * `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`。

  <Info>
    - `adaptive` 一般用于图生视频场景；
    - 竖屏短视频常用 `9:16`，横屏视频常用 `16:9`。
  </Info>
</ParamField>

<ParamField path="时长" type="integer" default="5">
  视频时长（秒）。

  * 常见范围：`2-12` 秒；
  * 时长越长，生成时间越久。
</ParamField>

<ParamField path="帧率" type="integer" default="24">
  视频帧率，目前一般固定为 `24` FPS。
</ParamField>

***

## 高级参数

### 随机性与镜头控制

<ParamField path="随机种子" type="integer" default="-1">
  控制生成结果随机性的种子值。

  * `-1`：每次随机（推荐探索阶段使用）；
  * 非负整数：固定种子，可生成相似风格的视频（不保证完全一致）。
</ParamField>

<ParamField path="固定镜头" type="boolean" default="false">
  是否固定摄像机镜头，仅对 **文生视频** 生效。

  * `true`：镜头固定，画面主要通过场景变化；
  * `false`：允许摄像机运动（运镜）。
</ParamField>

<ParamField path="水印" type="boolean" default="false">
  是否在视频上添加水印标识。
</ParamField>

<ParamField path="生成音频" type="boolean" default="false">
  是否生成带有画面同步音频的视频（仅 1.5 Pro 模型支持）。

  * `true`：生成带音频的视频；
  * `false`：生成无声视频。
</ParamField>

<ParamField path="样片模式(开发中)" type="boolean" default="false">
  是否启用样片生成模式（仅 1.5 Pro 模型支持）。

  * `true`：快速生成低分辨率预览（仅支持 480p）；
  * `false`：正常生成模式。

  <Info>
    样片模式适合内容预览和效果确认，生成速度更快，成本更低。
  </Info>
</ParamField>

<ParamField path="样片任务ID" type="string" default="">
  基于样片生成高清成片时使用的样片任务ID。

  * 填写后将使用指定样片生成高清视频；
  * 继承样片的内容和风格；
  * 支持 720p / 1080p 分辨率。
</ParamField>

### 并发与分行提示词

<ParamField path="并发请求数" type="integer" default="1">
  同时创建的视频生成任务数量。

  * 范围：`1-10`；
  * 可与提示词分行功能配合使用，最终总任务数 ≈ 提示词行数 × 并发请求数。
</ParamField>

<ParamField path="启用提示词分行" type="boolean" default="false">
  是否按行拆分提示词，每行一个独立视频任务。

  * 关闭：整段提示词视为一个基础任务，结合“并发请求数”重复生成多段视频；
  * 开启：按换行符拆分提示词，每行一个基础任务，再结合“并发请求数”计算总任务数。
</ParamField>

### 系统与调试参数

<ParamField path="轮询间隔" type="integer" default="10">
  轮询任务状态的间隔时间（秒）。

  * 建议范围：`2-30` 秒；
  * 间隔越短，请求越频繁，负载越高。
</ParamField>

<ParamField path="超时秒数" type="integer" default="60">
  单次 HTTP 请求的超时时间（秒）。
</ParamField>

<ParamField path="最大等待时长" type="integer" default="300">
  最大轮询总时长（秒）。

  * 实际最大等待时间 ≈ `轮询间隔 × (最大等待时长 / 轮询间隔)`；
  * 到达上限仍未完成则认为超时失败。
</ParamField>

<ParamField path="详细日志" type="boolean" default="false">
  是否输出完整的 API 请求和响应日志，便于调试。
</ParamField>

<ParamField path="忽略SSL证书" type="boolean" default="false">
  是否忽略 SSL 证书校验（仅调试环境使用，生产环境建议关闭）。
</ParamField>

<Warning>
  生产环境建议保持 `忽略SSL证书 = False`，以保证链路安全。
</Warning>

***

## 并发模式与内部流程

### 三种使用模式

1. **单任务模式**
   * 并发请求数 = 1；
   * 启用提示词分行 = False；
   * 生成 1 个视频。

2. **相同提示词重复模式**
   * 并发请求数 = N (>1)；
   * 启用提示词分行 = False；
   * 相同提示词重复生成 N 个视频（方便挑选最佳）。

3. **提示词分行模式**
   * 启用提示词分行 = True；
   * 按换行符拆分提示词，每行一个基础任务；
   * 总任务数 = 提示词行数 × 并发请求数（例如：3 行 × 并发 2 = 6 个视频）。

### 三阶段并发流程

```text theme={null}
阶段 1：并发创建任务
  ├─ ThreadPoolExecutor 并发调用创建接口
  ├─ 每个任务返回 task_id
  └─ 收集所有 task_id 列表

阶段 2：轮询所有任务状态
  ├─ 按轮询间隔定期查询
  ├─ 对返回状态做归一化处理
  └─ 直到所有任务完成或超时

阶段 3：下载所有视频
  ├─ 从响应中提取视频 URL
  ├─ 顺序下载到 output 目录
  └─ 构造 VideoObject 列表作为节点输出
```

***

## 输出说明

<ResponseField name="视频输出" type="video">
  生成的视频（或视频列表），可直接连接 SaveVideo 或 Preview Video。

  **文件信息：**

  * 文件格式：`.mp4`；
  * 默认保存路径：`ComfyUI/output/`；
  * 文件名格式：`doubao_seedance_<timestamp>.mp4`。

  **并发模式下：**

  * 输出为 `VideoObject` 列表；
  * 每个对象都提供：`get_dimensions()`、`get_fps()`、`get_frame_count()`、`get_path()`、`save_to(path)` 等方法。
</ResponseField>

<ResponseField name="生成统计" type="string">
  文本形式的统计信息，用于快速了解并发任务执行情况：

  * 总任务数；
  * 创建成功/失败数；
  * 生成成功/失败数；
  * 下载成功/失败数；
  * 总耗时等。
</ResponseField>

***

## 使用示例

### 示例 1：文生视频

<Steps>
  <Step title="配置提示词">
    ```
    一个机器人在未来城市中行走，霓虹灯闪烁，
    雨夜街道有倒影，镜头缓慢推进，氛围略带孤独感。
    ```
  </Step>

  <Step title="设置参数">
    * 分辨率：`1080p`
    * 宽高比：`16:9`
    * 时长：`10` 秒
    * 并发请求数：`1`
  </Step>

  <Step title="执行生成">
    运行节点，等待视频生成并自动下载到 output 目录。
  </Step>
</Steps>

### 示例 2：图生视频（首帧驱动）

<Steps>
  <Step title="连接参考图片">
    将一张静态场景图连接到 `参考图片1`。
  </Step>

  <Step title="配置提示词">
    ```
    让画面中的场景开始动起来，
    灯光逐渐点亮，远处车辆缓慢移动，
    整体风格保持原图不变。
    ```
  </Step>

  <Step title="执行生成">
    Seedance 会根据参考图和提示词生成动态视频。
  </Step>
</Steps>

### 示例 3：首尾帧视频

<Steps>
  <Step title="连接两张图片">
    * 参考图片1：白天场景；
    * 参考图片2：夜晚场景。
  </Step>

  <Step title="配置提示词">
    ```
    从白天缓慢过渡到夜晚，
    天空颜色逐渐变暗，路灯和窗户的灯光依次亮起。
    ```
  </Step>

  <Step title="设置参数">
    * 时长：`8-10` 秒；
    * 建议适当提高幅度，让变化更明显。
  </Step>
</Steps>

### 示例 4：并发批量生成

<Steps>
  <Step title="相同提示词多版本">
    * 并发请求数：`3`；
    * 启用提示词分行：`False`；
    * 提示词为单行描述。
  </Step>

  <Step title="提示词分行多主题">
    * 启用提示词分行：`True`；
    * 并发请求数：`2`；
    * 提示词示例：
      ```
      一个机器人在未来城市中行走
      赛博朋克风格的城市夜景
      海洋深处的神秘生物
      ```
  </Step>

  <Step title="执行生成">
    * 第一种模式：输出 3 段同主题视频；
    * 第二种模式：3 行 × 并发请求数 2 = 6 段不同主题视频。
  </Step>
</Steps>

### 示例 5：样片预览流程

<Steps>
  <Step title="生成样片">
    * 样片模式：`True`；
    * 分辨率：`480p`；
    * 时长：`5` 秒；
    * 生成音频：`True`。
  </Step>

  <Step title="查看样片效果">
    等待样片生成完成，预览效果，确认内容是否符合预期。
  </Step>

  <Step title="基于样片生成成片">
    * 样片任务ID：填入样片的 `task_id`；
    * 分辨率：`720p` 或 `1080p`；
    * 生成高清成片。
  </Step>
</Steps>

<Info>
  样片流程可以显著降低高清视频生成失败的风险，推荐在重要项目中使用。
</Info>

### 示例 6：批量离线处理

<Steps>
  <Step title="配置参数">
    * 服务层级：`flex`；
    * 并发请求数：`5` 或更多；
    * 分辨率：`720p`。
  </Step>

  <Step title="提交批量任务">
    节点将创建多个离线任务，任务ID格式为 `cgt-batch-*`。
  </Step>

  <Step title="等待处理完成">
    离线模式处理时间较长，但成本更低，适合大批量生成场景。
  </Step>
</Steps>

***

## 常见问题

<AccordionGroup>
  <Accordion title="视频生成大概要多久？">
    一般 5 秒左右的视频需要 30–60 秒生成时间，受以下因素影响：

    * 分辨率与时长；
    * 场景复杂度；
    * 当前服务端负载情况。
  </Accordion>

  <Accordion title="1080p 是否支持图生视频？">
    根据 README 中的限制：

    * `resolution=1080p` 不支持参考图场景（图生视频）；
    * 如需图生视频，推荐使用 `720p` 或更低分辨率。
  </Accordion>

  <Accordion title="生成失败时如何排查？">
    1. 打开“详细日志”，查看完整错误信息；
    2. 检查 API 密钥是否正确、余额是否充足；
    3. 确认 API 地址可访问且未被防火墙拦截；
    4. 尝试降低分辨率、缩短时长或简化提示词；
    5. 如频繁出现 5xx 错误，可适当调大最大等待时长。
  </Accordion>

  <Accordion title="如何获得更稳定的风格？">
    * 固定“随机种子”参数（例如 12345）；
    * 固定模型、分辨率、宽高比和提示词；
    * 在此基础上微调部分参数即可获得风格一致的系列视频。
  </Accordion>

  <Accordion title="样片模式什么时候使用？">
    推荐在以下场景使用样片模式：

    * 需要快速预览多个创意方案；
    * 生成高清视频前确认内容效果；
    * 预算有限，需要降低测试成本。
  </Accordion>

  <Accordion title="离线推理模式适合什么场景？">
    `service_tier="flex"` 适合：

    * 批量视频制作任务；
    * 非紧急项目，可以等待较长时间；
    * 成本敏感场景，需要降低成本。
  </Accordion>
</AccordionGroup>