ComfyUI Extension: ComfyUI-JM-Volcengine-API
volcengine comfyui api
Custom Nodes (0)
README
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秒视频时长选择
- 异步任务处理,自动轮询查询结果
- 自动下载和保存视频文件
安装
- 克隆此仓库到 ComfyUI 的 custom_nodes 目录:
cd ComfyUI/custom_nodes
git clone https://github.com/your-repo/ComfyUI-JM-Volcengine-API.git
- 安装依赖:
cd ComfyUI-JM-Volcengine-API
pip install -r requirements.txt
- 重启 ComfyUI
使用方法
Volcengine SeeDream V3 使用
- 在节点列表中找到
JM-Volcengine-API/Seedream
分类 - 添加
Volcengine SeeDream V3
节点 - 配置参数:
- access_key: 火山引擎访问密钥
- secret_key: 火山引擎访问密钥
- prompt: 图片生成提示词
- aspect_ratio: 选择宽高比
- guidance_scale: 引导强度 (可选)
- seed: 随机种子 (可选)
- use_pre_llm: 是否使用预处理LLM (可选)
- filename_prefix: 保存文件名前缀 (可选)
Volcengine I2V S2.0Pro 使用
- 在节点列表中找到
JM-Volcengine-API/I2V
分类 - 添加
Volcengine I2V S2.0Pro
节点 - 配置参数:
- access_key: 火山引擎访问密钥AccessKey
- secret_key: 火山引擎访问密钥SecretKey
- image: 输入图片 (连接图片节点)
- aspect_ratio: 选择视频宽高比
- prompt: 视频生成提示词 (可选,最大150字符)
- seed: 随机种子 (可选,-1表示随机)
- filename_prefix: 保存文件名前缀 (可选)
Volcengine Img Edit V3.0 使用
- 在节点列表中找到
JM-Volcengine-API/ImgEdit
分类 - 添加
Volcengine Img Edit V3.0
节点 - 配置参数:
- 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 使用 (新增功能)
- 在节点列表中找到
JM-Volcengine-API/Video
分类 - 添加
Volcengine Doubao Seedance
节点 - 配置参数:
- 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: 本地保存的视频文件路径
注意事项
通用注意事项
- 需要有效的火山引擎访问密钥
- 网络连接需要稳定
- 生成的内容需要符合平台规范
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 许可证。