Tripo3D

ComfyUI 节点

ComfyUI 节点

ComfyUI-Tripo 是 Tripo 官方提供的 ComfyUI 自定义节点扩展，可在 ComfyUI 工作流中通过文本、单张图片或多视图图片生成 3D 模型，并支持模型导入、贴图、精修、网格处理、低模化、风格化、绑骨、动画重定向、格式转换和重拓扑。

项目 值
Node 项目版本 1.3.0
源码标签 v1.3.1.1
源码仓库 VAST-AI-Research/ComfyUI-Tripo

功能与变更记录

功能

  • 根据文本提示生成 3D 模型。
  • 根据图片生成 3D 模型。
  • 通过 model_url 从 URL 导入模型。
  • 支持模型拆件能力。
  • 为 3D 模型绑骨并生成动画。
  • 转换模型格式并重新拓扑。

变更记录

  • 2026-06-30：新增 Mesh Segmentation v2.0 模型拆件，并支持通过 model_url 直接导入 URL。
  • 2026-05-28：新增模型导入。
  • 2025-06-19：更新到最新 API，并增加更多节点。
  • 2025-03-31：改用 tripo3d 包。
  • 2025-02-24：移除 glbviewer。
  • 2025-02-01：适配新版 API，并改用 Preview 3D 查看模型。
  • 2024-11-11：适配新版 API。
  • 2024-10-14：新增模型转换。
  • 2024-09-13：支持 model_version v2.0-20240919。

安装方式

任选一种方式安装，完成后重启 ComfyUI。

ComfyUI-Manager

打开 Custom Nodes Manager，搜索 Tripo for ComfyUI 并安装。

comfy-cli

通过 Comfy Registry 安装 comfy-cli，然后执行：

Bash
comfy node registry-install comfyui-tripo

从源码安装

将仓库放到 ComfyUI/custom_nodes/ComfyUI-Tripo，然后安装依赖：

Bash
cd ComfyUI/custom_nodes
git clone https://github.com/VAST-AI-Research/ComfyUI-Tripo.git
python -m pip install -r ComfyUI-Tripo/requirements.txt

API Key 配置

先在 Tripo 平台创建 API Key，再使用以下任一方式配置。

节点项目按以下顺序获取 API Key：

  1. 节点中非空的 apikey 输入。
  2. TRIPO_API_KEY 环境变量。
  3. ComfyUI-Tripo 项目目录中 config.json 的 TRIPO_API_KEY 字段。

Generate 和 Import 节点提供 apikey 输入；下游节点通过 MODEL_INFO 接收已经解析的 Key。

不得在截图、共享工作流、日志或代码仓库中暴露真实 API Key。共享工作流前应清空 apikey，本地使用优先选择环境变量。

环境变量启动示例

Windows：

Shell
set TRIPO_API_KEY=tsk_XXXXXXX
python.exe main.py [--cpu]

Linux 或 macOS：

Bash
TRIPO_API_KEY=tsk_XXXXXXX python main.py [--cpu]

节点总览

ComfyUI-Tripo 提供以下 11 个 Tripo 节点：

内部 ID 界面名称 能力 输出
TripoAPIDraft Tripo: Generate model 文本、图片或多视图生成模型 model_file、MODEL_INFO
TripoImportModel Tripo: Import model 导入本地模型或模型 URL MODEL_INFO
TripoTextureModel Tripo: Texture model 模型贴图 model_file、MODEL_INFO
TripoRefineModel Tripo: Refine Draft model 草模精修 model_file、MODEL_INFO
TripoMeshSegmentation Tripo: Segment mesh 网格分割 model_file、MODEL_INFO
TripoMeshCompletion Tripo: Complete mesh 网格补全 model_file、MODEL_INFO
TripoSmartLowPoly Tripo: Smart low poly 智能低模 model_file、MODEL_INFO
TripoStylizeModel Tripo: Stylize model 模型风格化 model_file、MODEL_INFO
TripoAnimateRigNode Tripo: Rig model 自动绑骨 model_file、MODEL_INFO
TripoAnimateRetargetNode Tripo: Retarget rigged model 动画重定向 model_file、MODEL_INFO
TripoConvertNode Tripo: Convert model 模型格式转换与导出 model_file

Preview 3D 是 ComfyUI 提供的预览节点，不计入以上 11 个 Tripo Node。

节点连接与数据流

flowchart LR
    G["Generate model"] -->|MODEL_INFO| P["模型处理"]
    I["Import model"] -->|MODEL_INFO| P
    P -->|MODEL_INFO| R["Rig model"]
    R -->|MODEL_INFO| A["Retarget rigged model"]
    A -->|MODEL_INFO| C["Convert model"]
  • model_file 是生成或处理任务下载后的文件路径，可连接 ComfyUI 的预览或文件处理节点。
  • MODEL_INFO 是下游 Tripo Node 使用的任务上下文，包含 task_id、解析后的 apikey、file_prefix 和 output_directory。
  • 来自节点链外部的普通模型必须先经过 TripoImportModel；单独的文件路径不能替代 MODEL_INFO。
  • 需要继续执行 Tripo 处理时应连接 MODEL_INFO，而不是把 model_file 当作任务上下文。

完整节点参数

“必填”表示节点参数是否必须提供；apikey 可留空以使用环境变量或配置文件回退。“—”表示没有显式默认值。

生成与导入

TripoAPIDraft — Tripo: Generate model

创建工作流中的第一个 Tripo 任务，无前置节点。

输入参数 类型 必填 默认值 枚举或范围
mode ENUM 是 第一个枚举值 text_to_model、image_to_model、multiview_to_model
apikey STRING 是 空 API Key 或回退配置
prompt STRING，多行 否 空 文本提示词
negative_prompt STRING，多行 否 空 负向提示词
image IMAGE 否 — 单图输入；多视图模式下为正面图
image_left IMAGE 否 — 可选左视图
image_back IMAGE 否 — 可选后视图
image_right IMAGE 否 — 可选右视图
model_version ENUM 否 v3.1-20260211 v1.4-20240625、v2.0-20240919、v2.5-20250123、v3.0-20250812、v3.1-20260211
texture BOOLEAN 否 true 是否生成贴图
pbr BOOLEAN 否 true 是否生成 PBR 贴图
image_seed INT 否 42 文本模式使用的图像种子
model_seed INT 否 42 模型种子
texture_seed INT 否 42 贴图种子
texture_quality ENUM 否 standard standard、detailed
geometry_quality ENUM 否 standard standard、detailed；仅图片模式
texture_alignment ENUM 否 original_image original_image、geometry
face_limit INT 否 -1 -1–500000；小于等于 0 时按未设置传递
quad BOOLEAN 否 false 是否请求四边面拓扑
compress BOOLEAN 否 false 是否压缩输出
generate_parts BOOLEAN 否 false 是否生成部件
smart_low_poly BOOLEAN 否 false 是否启用智能低模
auto_size BOOLEAN 否 false 是否自动调整模型尺寸
orientation ENUM 否 default default、align_image；图片和多视图模式
file_prefix STRING 否 空 下载文件名前缀
output_directory STRING 否 空 目标目录覆盖值

模式限制：

模式 条件必填输入 说明
text_to_model prompt 为空时提示 “Prompt is required”
image_to_model image 缺失时提示 “Image is required”
multiview_to_model image image 是正面图；左、后、右视图可选

输出：STRING model_file 和 MODEL_INFO。常见失败：条件输入缺失、API Key 缺失或无效、API 任务失败、输出文件移动失败。最小连接：提示词或图片 → TripoAPIDraft → Preview 3D；需要后处理时连接 MODEL_INFO。

TripoImportModel — Tripo: Import model

为不在当前节点链中产生的模型建立 Tripo 任务上下文。

输入参数 类型 必填 默认值 枚举或范围
apikey STRING 是 空 API Key 或回退配置
model_file 文件选择 否 none ComfyUI 输入目录中的模型
model_url STRING 否 空 模型直链
file_prefix STRING 否 空 传递给下游下载文件的前缀
output_directory STRING 否 空 传递给下游下载文件的目录

非空 model_url 的优先级高于 model_file；二者都为空时节点失败。上传控件接受 .glb、.fbx、.obj、.stl、.ply、.3mf 和 .gltf，后端输入扫描还识别 .zip。

输出：仅 MODEL_INFO。常见失败：没有提供来源、本地文件不存在、URL 无法获取、格式被拒绝或导入任务失败。最小连接：本地文件或 URL → TripoImportModel → 任意接收 MODEL_INFO 的处理节点。

模型处理

TripoTextureModel — Tripo: Texture model

需要来自 Generate、Import 或兼容处理节点的 MODEL_INFO。

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 上游任务上下文
model_version ENUM 否 v3.0-20250812 v2.5-20250123、v3.0-20250812
texture BOOLEAN 否 true 是否启用贴图
pbr BOOLEAN 否 true 是否生成 PBR 贴图
texture_seed INT 否 42 贴图种子
texture_quality ENUM 否 standard standard、detailed
texture_alignment ENUM 否 original_image original_image、geometry
text_prompt STRING，多行 否 空 贴图引导文本
image_prompt IMAGE 否 — 贴图参考图
style_image IMAGE 否 — 风格参考图
part_names STRING，多行 否 空 每行一个部件名
compress BOOLEAN 否 false 是否压缩输出
bake BOOLEAN 否 true 是否烘焙贴图

输出：STRING model_file 和 MODEL_INFO。常见失败：任务上下文不兼容、参考图无效或 API 任务失败。最小连接：Generate/Import 的 MODEL_INFO → TripoTextureModel → Preview 3D 或其他处理节点。

TripoRefineModel — Tripo: Refine Draft model

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 草模任务上下文

输出：STRING model_file 和 MODEL_INFO。上游任务必须是可精修的草模；上下文不兼容或 API 任务失败都会导致失败。最小连接：Generate 草模的 MODEL_INFO → TripoRefineModel → Preview 3D。

TripoMeshSegmentation — Tripo: Segment mesh

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 上游任务上下文
model_version ENUM 是 v1.0-20250506 v1.0-20250506、v2.0-20260430
segmentation_granularity ENUM 否 balanced simple、balanced、detailed
ref_image IMAGE 否 — 分割参考图
split_by_connectivity BOOLEAN 否 true 是否按连通性拆分

segmentation_granularity、ref_image 和 split_by_connectivity 只在 v2.0-20260430 下发送，v1 会忽略它们。输出：STRING model_file 和 MODEL_INFO。常见失败：模型不兼容、参考图无效或 API 任务失败。最小连接：Generate/Import 的 MODEL_INFO → TripoMeshSegmentation → Completion 或 Preview 3D。

TripoMeshCompletion — Tripo: Complete mesh

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 分割模型任务上下文
model_version ENUM 是 v1.0-20250506 v1.0-20250506
part_names STRING，多行 否 空 每行一个部件名

输出：STRING model_file 和 MODEL_INFO。任务不适合补全或 API 任务失败会导致失败。最小连接：Segment 的 MODEL_INFO → TripoMeshCompletion → Preview 3D。

TripoSmartLowPoly — Tripo: Smart low poly

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 上游任务上下文
model_version ENUM 是 P-v2.0-20251225 P-v2.0-20251225
quad BOOLEAN 否 false 是否请求四边面拓扑
part_names STRING，多行 否 空 每行一个部件名
face_limit INT 否 10000 -1–20000
bake BOOLEAN 否 true 是否烘焙输出

输出：STRING model_file 和 MODEL_INFO。常见失败：模型或部件不兼容、API 任务失败。最小连接：Generate/Import 的 MODEL_INFO → TripoSmartLowPoly → Preview 3D 或 Convert。

TripoStylizeModel — Tripo: Stylize model

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 上游任务上下文
style ENUM 是 第一个枚举值 lego、voxel、voronoi、minecraft
block_size INT 是 80 1–1000

输出：STRING model_file 和 MODEL_INFO。常见失败：模型不兼容、当前任务不支持指定风格或 API 任务失败。最小连接：Generate/Import 的 MODEL_INFO → TripoStylizeModel → Preview 3D。

绑骨与动画

TripoAnimateRigNode — Tripo: Rig model

提交绑骨任务前，节点会先检查模型能否绑骨并获取 rig type。

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 上游任务上下文
model_version ENUM 是 v2.0-20250506 v1.0-20240301、v2.0-20250506
out_format ENUM 是 glb glb、fbx
spec ENUM 是 tripo mixamo、tripo

输出：STRING model_file 和 MODEL_INFO。模型不可绑骨、找不到合适的 rig type 或 API 任务失败时会终止。最小连接：Generate/Import 的 MODEL_INFO → TripoAnimateRigNode → Retarget 或 Preview 3D。

TripoAnimateRetargetNode — Tripo: Retarget rigged model

需要已经成功绑骨的模型对应的 MODEL_INFO。

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 已绑骨模型的任务上下文
animation ENUM 是 第一个枚举值 见下方 16 个预设
out_format ENUM 是 glb glb、fbx
bake_animation BOOLEAN 否 true 是否烘焙动画
export_with_geometry BOOLEAN 否 false 导出时是否包含几何体

16 个动画枚举为：preset:idle、preset:walk、preset:run、preset:dive、preset:climb、preset:jump、preset:slash、preset:shoot、preset:hurt、preset:fall、preset:turn、preset:quadruped:walk、preset:hexapod:walk、preset:octopod:walk、preset:serpentine:march 和 preset:aquatic:march。

输出：STRING model_file 和 MODEL_INFO。模型未绑骨、上下文不兼容或 API 任务失败会导致失败。最小连接：Rig 的 MODEL_INFO → TripoAnimateRetargetNode → Preview 3D 或 Convert。

格式输出

TripoConvertNode — Tripo: Convert model

这是一个输出节点，不返回 MODEL_INFO。

输入参数 类型 必填 默认值 枚举或范围
model_info MODEL_INFO 是 — 上游任务上下文
format ENUM 是 第一个枚举值 GLTF、USDZ、FBX、OBJ、STL、3MF
quad BOOLEAN 否 false 是否请求四边面拓扑
force_symmetry BOOLEAN 否 false 是否强制对称
face_limit INT 否 -1 -1–500000
flatten_bottom BOOLEAN 否 false 是否压平底部
flatten_bottom_threshold FLOAT 否 0.01 0.0–1.0
texture_size INT 否 4096 128–4096
texture_format ENUM 否 JPEG BMP、DPX、HDR、JPEG、OPEN_EXR、PNG、TARGA、TIFF、WEBP
pivot_to_center_bottom BOOLEAN 否 false 是否把轴心移动到中心底部
scale_factor FLOAT 否 1.0 最小值 0
with_animation BOOLEAN 否 true 是否保留动画
pack_uv BOOLEAN 否 false 是否打包 UV
bake BOOLEAN 否 true 是否烘焙输出
part_names STRING，多行 否 空 每行一个部件名
fbx_preset ENUM 否 blender blender、mixamo、3dsmax
export_vertex_colors BOOLEAN 否 false 是否导出顶点色
export_orientation ENUM 否 +x +x、+y、-x、-y
animate_in_place BOOLEAN 否 false 是否原地导出动画

输出：STRING model_file。常见失败：源任务不支持目标转换、导出设置无效、API 任务或输出移动失败。最小连接：任意兼容的 MODEL_INFO → TripoConvertNode。

工作流示例

Preview 3D 仅作为可选的 ComfyUI 查看器，不计入 Tripo 节点数量。

flowchart LR
    T["文本"] --> GT["Generate model<br/>mode: text_to_model"]
    IM["图片"] --> GI["Generate model<br/>mode: image_to_model"]
    MV["正面图 + 可选视图"] --> GM["Generate model<br/>mode: multiview_to_model"]
    GT --> V["Preview 3D"]
    GI --> V
    GM --> V
  1. Text to Model： 填写 prompt，选择 text_to_model，把 model_file 连接到 Preview 3D。
  2. Image to Model： 将 IMAGE 连接到 image，选择 image_to_model，预览 model_file。
  3. Multiview to Model： 正面图连接 image，可选视图依次连接 image_left、image_back 和 image_right。
  4. Texture Model： Generate 或 Import → 用 MODEL_INFO 连接 Texture → 预览新的 model_file。
  5. Refine Model： 生成兼容草模 → 用 MODEL_INFO 连接 Refine → 预览精修文件。
  6. Rig and Retarget： Generate 或 Import → Rig → Retarget；两段都连接 MODEL_INFO，最后预览或 Convert。
  7. Import and Process： 本地文件或 URL → Import → Segment/Smart low poly/Stylize/Texture。Import 返回任务上下文，不返回预览文件。
  8. Convert and Export： 把 Generate、Import、模型处理、Rig 或 Retarget 最终输出的 MODEL_INFO 连接到 Convert，并选择输出格式。

官方工作流 PNG

以下 6 张 PNG 包含内嵌的 ComfyUI 工作流数据。通过下载链接保存原始 PNG 后，可以将文件拖入 ComfyUI 或手动加载。截图中的参数值仅为工作流示例，实际默认值请查看上方参数表。

Text to Mesh

Tripo Generate model 连接 Preview 3D 的 ComfyUI 文本生成模型工作流

根据文本提示生成模型，并把 model_file 连接到 Preview 3D。

下载原始工作流 PNG

Image to Mesh

Load Image、Tripo Generate model 和 Preview 3D 组成的 ComfyUI 图片生成模型工作流

加载图片，将其连接到 image_to_model 模式的 Generate model，并预览结果。

下载原始工作流 PNG

Multiview Images to Mesh

三个 Load Image 节点连接 Tripo Generate model 和 Preview 3D 的 ComfyUI 多视图工作流

把正面图和可选侧视图连接到 multiview_to_model 模式的 Generate model。

下载原始工作流 PNG

Texture a generated model

Generate model 连接 Texture model 并分别连接 Preview 3D 的 ComfyUI 贴图工作流

把 Generate model 的 MODEL_INFO 传给 Texture model，并预览处理前后的输出。

下载原始工作流 PNG

Refine a draft Mesh

草模 Generate model 任务连接 Refine Draft model 和 Preview 3D 的 ComfyUI 精修工作流

生成兼容草模，把 MODEL_INFO 传给 Refine Draft model，并预览精修后的文件。

下载原始工作流 PNG

Animation / Rig and export

Generate model、Rig model、Preview 3D 和 Convert model 组成的 ComfyUI 绑骨与导出工作流

下载原始工作流 PNG

输出与排障

默认情况下，下载的模型写入 ComfyUI/output。Generate 和 Import 确定 file_prefix 与 output_directory，并通过下游 MODEL_INFO 持续传递。非空前缀会添加到下载文件名开头；非空目录会把文件移动到该目录，目录不存在时会尝试创建。

现象 检查项
TRIPO API key is required 设置非空节点 Key、TRIPO_API_KEY 或 config.json 中的字段。
提示缺少 Prompt/正面图 检查 mode 与条件必填输入是否匹配。
Import 不启动 提供可访问的 model_url 或存在的 model_file；URL 优先。
模型不可绑骨 改用适合的角色模型；riggable 检查失败或没有 rig type 时 Rig 会终止。
API 任务失败 查看返回的 error_code 和 error_msg，同时检查账号权限与余额。
输出无法移动 检查 output_directory 是否有效、可写，以及源文件是否仍然存在。
节点没有出现 重启 ComfyUI，核对仓库目录，并安装 requirements.txt。
Import 上传按钮失败 核对上传控件支持的扩展名，并查看 ComfyUI 上传响应。