ComfyUI-JM-Volcengine-API

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 目录：

cd ComfyUI/custom_nodes
git clone https://github.com/your-repo/ComfyUI-JM-Volcengine-API.git

2. 安装依赖：

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 许可证。