synthetai-ComfyUI-JM-Volcengine-API/README.md

# ComfyUI 火山引擎 API 插件

这是一个为 ComfyUI 开发的火山引擎AI服务插件，支持多种火山引擎API功能。

## 功能特性

### 1. Volcengine SeeDream V3 - 文生图节点
- 火山引擎即梦AI SeeDream V3 文生图模型
- 支持1.5K分辨率图片生成
- 支持多种宽高比：1:1、4:3、3:2、16:9、9:16、21:9
- 自动保存生成的图片到输出目录
- 同时返回图片URL和本地文件路径

### 2. Volcengine I2V S2.0Pro - 图生视频节点
- 火山引擎即梦AI图生视频S2.0Pro专业级模型
- 从静态图片生成高质量动态视频
- 支持多种视频宽高比：16:9、4:3、1:1、3:4、9:16、21:9、9:21
- 支持中英文提示词，最大150字符
- 异步处理，自动轮询查询结果
- 视频时长固定5秒
- 自动下载和保存视频文件

### 3. Volcengine Img Edit V3.0 - 图生图指令编辑节点
- 火山引擎图生图3.0指令编辑模型
- 根据文字指令智能编辑图片内容
- 支持精确的编辑强度控制（0.1-1.0）
- 支持多种推理参数调节
- 保持原图主体结构的同时进行局部编辑
- 自动保存编辑后的图片

### 4. Volcengine Doubao Seedance - 豆包Seedance视频生成节点 (新增)
- 火山引擎豆包Seedance视频生成模型
- 支持文生视频、图生视频和首尾帧图生视频三种模式
- 支持两种模型：pro和lite-i2v版本
- lite-i2v模型支持首尾帧图生视频（传入2张图片）
- 支持所有模型文本命令参数：分辨率、宽高比、时长、帧率等
- 支持多种视频分辨率：480p、720p、1080p
- 支持9种宽高比和2种特殊比例模式
- 支持5秒和10秒视频时长选择
- 异步任务处理，自动轮询查询结果
- 自动下载和保存视频文件

## 安装

1. 克隆此仓库到 ComfyUI 的 custom_nodes 目录：
```bash
cd ComfyUI/custom_nodes
git clone https://github.com/your-repo/ComfyUI-JM-Volcengine-API.git
```

2. 安装依赖：
```bash
cd ComfyUI-JM-Volcengine-API
pip install -r requirements.txt
```

3. 重启 ComfyUI

## 使用方法

### Volcengine SeeDream V3 使用
1. 在节点列表中找到 `JM-Volcengine-API/Seedream` 分类
2. 添加 `Volcengine SeeDream V3` 节点
3. 配置参数：
   - **access_key**: 火山引擎访问密钥
   - **secret_key**: 火山引擎访问密钥
   - **prompt**: 图片生成提示词
   - **aspect_ratio**: 选择宽高比
   - **guidance_scale**: 引导强度 (可选)
   - **seed**: 随机种子 (可选)
   - **use_pre_llm**: 是否使用预处理LLM (可选)
   - **filename_prefix**: 保存文件名前缀 (可选)

### Volcengine I2V S2.0Pro 使用
1. 在节点列表中找到 `JM-Volcengine-API/I2V` 分类
2. 添加 `Volcengine I2V S2.0Pro` 节点
3. 配置参数：
   - **access_key**: 火山引擎访问密钥AccessKey
   - **secret_key**: 火山引擎访问密钥SecretKey
   - **image**: 输入图片 (连接图片节点)
   - **aspect_ratio**: 选择视频宽高比
   - **prompt**: 视频生成提示词 (可选，最大150字符)
   - **seed**: 随机种子 (可选，-1表示随机)
   - **filename_prefix**: 保存文件名前缀 (可选)

### Volcengine Img Edit V3.0 使用
1. 在节点列表中找到 `JM-Volcengine-API/ImgEdit` 分类
2. 添加 `Volcengine Img Edit V3.0` 节点
3. 配置参数：
   - **access_key**: 火山引擎访问密钥AccessKey
   - **secret_key**: 火山引擎访问密钥SecretKey
   - **image**: 输入图片 (连接图片节点)
   - **prompt**: 编辑指令，建议长度<=120字符，使用自然语言描述
   - **scale**: 文本描述影响程度 (可选，0.0-1.0，默认0.5)
   - **seed**: 随机种子 (可选，-1表示随机)
   - **filename_prefix**: 保存文件名前缀 (可选)
   - **return_url**: 是否返回图片URL链接 (可选，默认True，24小时有效)

### Volcengine Doubao Seedance 使用 (新增功能)
1. 在节点列表中找到 `JM-Volcengine-API/Video` 分类
2. 添加 `Volcengine Doubao Seedance` 节点
3. 配置参数：
   - **ark_api_key**: 火山方舟API密钥
   - **model**: 模型ID (doubao-seedance-1-0-pro-250528 或 doubao-seedance-1-0-lite-i2v-250428)
   - **prompt**: 视频生成提示词，支持中英文
   - **first_frame**: 首帧图片 (可选，图生视频模式)
   - **last_frame**: 尾帧图片 (可选，首尾帧图生视频模式)
   - **resolution**: 视频分辨率 (可选，480p/720p/1080p)
   - **ratio**: 视频宽高比 (可选，9种比例+特殊模式)
   - **duration**: 视频时长 (可选，5秒或10秒)
   - **framepersecond**: 帧率 (可选，16或24)
   - **watermark**: 是否包含水印 (可选)
   - **seed**: 随机种子 (可选，-1表示随机)
   - **camerafixed**: 是否固定摄像头 (可选)
   - **filename_prefix**: 保存文件名前缀 (可选)

## 参数说明

### SeeDream V3 参数
- **宽高比选项**：
  - 1:1 → 1536×1536
  - 4:3 → 1472×1104
  - 3:2 → 1584×1056
  - 16:9 → 1664×936
  - 9:16 → 936×1664
  - 21:9 → 2016×864

- **guidance_scale**: 1.0-20.0，控制生成图片与提示词的匹配程度
- **use_pre_llm**: 是否使用预处理大语言模型优化提示词

### I2V S2.0Pro 参数
- **支持的宽高比**：
  - 16:9 → 适合横向视频
  - 4:3 → 传统电视比例
  - 1:1 → 正方形视频
  - 3:4 → 竖向视频
  - 9:16 → 手机竖屏视频
  - 21:9 → 超宽屏视频
  - 9:21 → 超高竖屏视频

- **提示词优化建议**：
  - 与输入图片内容保持一致
  - 描述期望的动作和运镜效果
  - 支持中英文，建议使用简洁明确的描述
  - 可以包含镜头切换、人物动作、情绪演绎等描述

### Img Edit V3.0 参数
- **prompt**: 编辑指令，支持中英文，建议长度<=120字符，描述具体的编辑需求，例如：
  - "把天空改成夜晚"
  - "给人物添加墨镜"  
  - "改变背景颜色为蓝色"
  - "背景换成演唱会现场"
  - "添加一道彩虹"
  - "删除图上的女孩"
- **scale**: 文本描述影响程度，范围0.0-1.0，默认0.5
  - 0.0-0.3: 轻微编辑，主要保持原图特征
  - 0.4-0.6: 平衡编辑，文本和原图影响相当
  - 0.7-1.0: 强度编辑，更倾向于遵循文本描述
- **return_url**: 控制返回格式
  - True: 返回24小时有效的图片URL链接（便于分享和下载）
  - False: 返回Base64编码数据（数据更安全，但体积较大）
- **使用建议**：
  - 使用清晰的，分辨率高的底图
  - 编辑指令使用自然语言即可
  - 每次编辑使用单指令会更好
  - 局部编辑时指令描述尽量精准
  - 发现编辑效果不明显时，可以调整scale数值

### Doubao Seedance 参数 (新增)
- **支持的视频分辨率**：
  - 480p → 低分辨率
  - 720p → 标准高清（默认）
  - 1080p → 全高清

- **支持的宽高比**：
  - 21:9 → 超宽屏比例
  - 16:9 → 标准横屏比例
  - 4:3 → 传统电视比例
  - 1:1 → 正方形比例
  - 3:4 → 竖屏比例
  - 9:16 → 手机竖屏比例
  - 9:21 → 超高竖屏比例
  - keep_ratio → 保持输入图片的宽高比
  - adaptive → 根据输入图片自动选择最合适的宽高比（默认）

- **视频时长**：
  - 5秒（默认）
  - 10秒

- **帧率选项**：
  - 16fps → 较低帧率
  - 24fps → 标准帧率（默认）

- **图片输入方式**（图生视频模式）：
  - first_frame → 首帧图片输入
  - last_frame → 尾帧图片输入

- **模型选择**：
  - doubao-seedance-1-0-pro-250528 → 专业版模型，支持文生视频和单图生视频
  - doubao-seedance-1-0-lite-i2v-250428 → 轻量版图生视频模型，支持首尾帧图生视频

- **使用模式**：
  - 文生视频：仅输入提示词
  - 首帧图生视频：连接first_frame输入+提示词
  - 尾帧图生视频：连接last_frame输入+提示词
  - 首尾帧图生视频：连接first_frame和last_frame输入+提示词（推荐使用lite-i2v模型）

- **使用建议**：
  - 提示词描述要清晰具体，避免过于抽象
  - 图生视频模式下，输入图片质量会影响生成效果
  - 首尾帧模式下，两张图片的宽高比应该一致，系统会以首帧为准自动裁剪尾帧
  - 参数名称直观：first_frame表示首帧，last_frame表示尾帧，用户一目了然
  - 建议根据实际需求选择合适的分辨率和时长
  - 使用keep_ratio或adaptive可以更好地适配输入图片

## 输出说明

### SeeDream V3 输出
- **image**: 生成的图片张量，可连接到其他节点
- **image_url**: 图片的临时URL链接
- **local_image_path**: 本地保存的图片文件路径

### I2V S2.0Pro 输出
- **video_url**: 生成的视频URL链接 (有效期1小时)
- **local_video_path**: 本地保存的视频文件路径

### Img Edit V3.0 输出
- **image**: 编辑后的图片张量，可连接到其他节点
- **image_url**: 图片的URL链接（当return_url=True时）或Base64数据信息（当return_url=False时）
- **local_image_path**: 本地保存的图片文件路径

### Doubao Seedance 输出 (新增)
- **video_path**: 本地保存的视频文件路径

## 注意事项

### 通用注意事项
1. 需要有效的火山引擎访问密钥
2. 网络连接需要稳定
3. 生成的内容需要符合平台规范

### SeeDream V3 特定注意事项
- 图片生成为同步处理，通常几秒内完成
- 生成的图片会自动保存到ComfyUI的output目录
- 临时URL链接有效期较短，建议及时保存

### I2V S2.0Pro 特定注意事项
- 视频生成为异步处理，通常需要几分钟时间
- 程序会自动轮询查询结果，请耐心等待
- 生成的视频时长固定为5秒
- 视频URL有效期为1小时，请及时下载保存
- 输入图片和提示词需要通过内容审核
- 建议根据输入图片的实际比例选择合适的aspect_ratio

### Img Edit V3.0 特定注意事项
- 使用SeedEdit 3.0指令编辑模型，服务标识固定为"seededit_v3.0"
- 编辑效果取决于输入图片质量和编辑指令的准确性
- 建议使用清晰、具体的编辑指令以获得更好的效果
- 提示词建议长度<=120字符，过长可能导致编辑异常
- 不同的scale值会产生不同程度的编辑效果
- 任务为异步处理，程序会自动轮询查询结果
- 编辑后的图片保持原图的基本构图和主体结构
- 输入图片格式支持JPEG、PNG，最大5MB，分辨率最大4096×4096

### Doubao Seedance 特定注意事项 (新增)
- 视频生成为异步处理，通常需要几分钟时间
- 程序会自动轮询查询结果，请耐心等待
- 支持文生视频、图生视频和首尾帧图生视频三种模式
- 图生视频模式下，输入图片质量会影响生成效果
- 首尾帧模式需要使用lite-i2v模型，连接first_frame和last_frame两个输入
- 首尾帧图片的宽高比不一致时，以首帧图片为主，尾帧会自动裁剪适配
- 参数名称已优化：first_frame和last_frame直观明确，无需额外的角色设置
- 生成的视频URL有效期为24小时，请及时下载保存
- 输入图片和提示词需要通过内容审核
- 建议根据实际用途选择合适的分辨率和时长参数
- 所有模型文本命令参数都可以通过UI直接设置
- 使用keep_ratio或adaptive可以更好地适配输入图片比例

## 错误处理

### 常见错误及解决方案

#### SeeDream V3
- **认证失败**: 检查access_key和secret_key是否正确
- **参数错误**: 确认提示词长度和参数范围
- **网络错误**: 检查网络连接状态

#### I2V S2.0Pro
- **认证失败**: 检查AccessKey和SecretKey是否正确并有相应权限
- **图片审核未通过**: 检查输入图片内容是否符合平台规范
- **文本审核未通过**: 检查提示词内容是否合规
- **任务超时**: 可能服务器繁忙，可稍后重试
- **宽高比不匹配**: 建议选择与输入图片比例接近的aspect_ratio

#### Img Edit V3.0
- **认证失败**: 检查AccessKey和SecretKey是否正确并有相应权限
- **编辑指令错误**: 检查编辑指令是否清晰明确，避免过于复杂的描述
- **提示词过长**: 确保提示词长度不超过120字符
- **参数超出范围**: 确认scale参数在0.0-1.0范围内
- **图片格式不支持**: 确保输入图片为JPEG或PNG格式，大小不超过5MB
- **任务超时**: 可能服务器繁忙，任务处理时间过长，可稍后重试
- **任务未找到或过期**: 任务可能已过期（12小时），请重新提交

#### Doubao Seedance (新增)
- **认证失败**: 检查ARK API密钥是否正确并有相应权限
- **模型不可用**: 确认所选模型是否已开通并可正常使用
- **提示词审核未通过**: 检查提示词内容是否符合平台规范
- **图片审核未通过**: 检查输入图片内容是否符合平台规范
- **参数错误**: 确认所有参数值是否在支持范围内
- **首尾帧图片错误**: 使用首尾帧模式时确保正确连接first_frame和last_frame输入
- **模型与功能不匹配**: pro模型不支持首尾帧，lite-i2v模型专为图生视频设计
- **任务超时**: 可能服务器繁忙，可稍后重试
- **视频生成失败**: 检查提示词和参数设置，重新尝试
- **下载失败**: 网络连接问题，检查网络状态

## 技术实现

### SeeDream V3
- 使用火山引擎AWS V4签名算法进行认证
- 支持URL和Base64两种图片返回格式
- 自动处理ComfyUI张量格式转换

### I2V S2.0Pro
- 实现火山引擎标准签名V4算法
- 异步任务处理机制，支持轮询查询
- 图片自动转换为Base64格式上传
- 完整的错误处理和重试机制
- 视频文件自动下载和命名管理

### Img Edit V3.0
- 实现完整的火山引擎SeedEdit 3.0异步接口调用
- 支持任务提交和轮询查询的异步处理机制
- 智能图片格式转换和处理
- 支持URL和Base64两种返回格式
- 完善的错误处理和异常捕获
- 自动文件命名和保存管理

### Doubao Seedance (新增)
- 实现火山方舟标准API调用流程
- 支持异步任务提交和轮询查询机制
- 完整的模型文本命令参数支持
- 智能图片格式转换和Base64编码
- 支持文生视频、图生视频和首尾帧图生视频三种模式
- 支持多张图片输入和角色配置
- 完善的错误处理和重试机制
- 视频文件自动下载和命名管理
- 支持所有官方模型参数配置

## 系统要求
- ComfyUI 环境
- Python 3.8+
- 稳定的网络连接
- 有效的火山引擎API访问权限

## 更新日志

### v4.0.0 (最新)
- 新增 Volcengine Doubao Seedance 视频生成节点
- 支持火山引擎豆包Seedance模型的文生视频和图生视频功能
- 完整支持所有模型文本命令参数：分辨率、宽高比、时长、帧率、水印、种子、摄像头固定等
- 支持3种分辨率、9种宽高比和2种特殊比例模式
- 实现异步任务处理和自动轮询查询
- 自动视频下载和文件命名管理
- 优化用户界面参数配置

### v3.0.0
- 新增 Volcengine Img Edit V3.0 图生图指令编辑节点（SeedEdit 3.0）
- 支持根据文字指令智能编辑图片内容
- 实现异步任务处理机制，支持任务提交和轮询查询
- 支持scale参数调节文本描述影响程度
- 完善的错误处理和用户提示
- 优化文件保存和命名机制

### v2.0.0
- 新增 Volcengine I2V S2.0Pro 图生视频节点
- 支持从图片生成高质量5秒视频
- 支持7种视频宽高比选择
- 实现异步任务处理和自动轮询
- 添加完整的火山引擎签名认证
- 支持视频自动下载和保存

### v1.0.0
- 初始版本
- 支持 Volcengine SeeDream V3 文生图功能
- 支持1.5K分辨率和多种宽高比
- 实现AWS V4签名认证
- 支持图片自动保存和URL返回

## 技术支持

如有问题或建议，请提交Issue或Pull Request。

## 许可证

本项目采用 MIT 许可证。