ComfyUI Extension: ComfyUI-JM-Volcengine-API

Authored by synthetai

Created

Updated

2 stars

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秒视频时长选择
    • 异步任务处理，自动轮询查询结果
    • 自动下载和保存视频文件

    安装

    1. 克隆此仓库到 ComfyUI 的 custom_nodes 目录：
    cd ComfyUI/custom_nodes
git clone https://github.com/your-repo/ComfyUI-JM-Volcengine-API.git
    1. 安装依赖：
    cd ComfyUI-JM-Volcengine-API
pip install -r requirements.txt
    1. 重启 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 许可证。