Tripo3D

ComfyUI 노드

ComfyUI 노드

ComfyUI-Tripo는 Tripo의 공식 ComfyUI 커스텀 노드 확장입니다. 텍스트, 이미지 또는 멀티뷰 이미지를 이용한 3D 생성을 ComfyUI 워크플로에 통합하며, 모델 가져오기, 텍스처링, 정제, 메시 처리, 로우 폴리 최적화, 스타일 변환, 리깅, 애니메이션 리타게팅, 형식 변환 및 리토폴로지도 지원합니다.

항목 값
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-Manager, Comfy Registry, comfy-cli.

한 가지 방법을 선택해 설치한 뒤 ComfyUI를 다시 시작하세요.

  1. ComfyUI-Manager: Custom Nodes Manager에서 Tripo for ComfyUI를 검색해 설치합니다.
  2. comfy-cli:
Bash
comfy node registry-install comfyui-tripo
  1. 소스에서 설치:
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. 프로젝트 디렉터리 config.json의 TRIPO_API_KEY 필드.

Generate와 Import는 apikey를 제공하고, 후속 노드는 결정된 Key를 MODEL_INFO로 받습니다. 실제 Key를 스크린샷, workflow, 로그 또는 저장소에 노출하지 마세요.

환경 변수 실행 예시

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 텍스트, 이미지 또는 멀티뷰로 모델을 생성합니다. STRING model_file + MODEL_INFO
TripoImportModel Tripo: Import model 로컬 모델 또는 URL을 가져옵니다. MODEL_INFO
TripoTextureModel Tripo: Texture model 모델에 텍스처를 생성합니다. STRING model_file + MODEL_INFO
TripoRefineModel Tripo: Refine Draft model 호환 초안 모델을 정제합니다. STRING model_file + MODEL_INFO
TripoMeshSegmentation Tripo: Segment mesh 메시를 분할합니다. STRING model_file + MODEL_INFO
TripoMeshCompletion Tripo: Complete mesh 분할된 메시를 보완합니다. STRING model_file + MODEL_INFO
TripoSmartLowPoly Tripo: Smart low poly 로우 폴리 모델을 생성합니다. STRING model_file + MODEL_INFO
TripoStylizeModel Tripo: Stylize model 기하학 스타일을 적용합니다. STRING model_file + MODEL_INFO
TripoAnimateRigNode Tripo: Rig model 모델을 자동 리깅합니다. STRING model_file + MODEL_INFO
TripoAnimateRetargetNode Tripo: Retarget rigged model 프리셋 애니메이션을 적용합니다. STRING model_file + MODEL_INFO
TripoConvertNode Tripo: Convert model 모델을 변환하고 내보냅니다. STRING model_file

Preview 3D는 ComfyUI 노드이며 11개 Tripo 노드에 포함되지 않습니다.

연결과 데이터 흐름

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은 미리보기나 파일 처리에 쓰는 다운로드된 파일 경로입니다.
  • MODEL_INFO에는 task_id, 결정된 apikey, file_prefix, output_directory가 들어 있습니다.
  • 외부 모델은 먼저 TripoImportModel을 거쳐야 하며 파일 경로만으로 MODEL_INFO를 대체할 수 없습니다.
  • Tripo 처리를 계속하려면 MODEL_INFO를 연결하세요.

전체 노드 파라미터

‘필수’는 노드 정의에서 필수로 지정된 입력을 나타냅니다. 빈 apikey는 환경 변수나 설정으로 대체될 수 있습니다. ‘—’는 명시적인 기본값이 없음을 나타냅니다.

생성 및 가져오기

TripoAPIDraft — Tripo: Generate model

텍스트, 이미지 또는 멀티뷰로 모델을 생성합니다.

입력 타입 필수 기본값 값 / 범위
mode ENUM 예 첫 번째 값 text_to_model, image_to_model, multiview_to_model
apikey STRING 예 빈 값 API key 또는 대체 설정
prompt STRING multiline 아니요 빈 값 text_to_model
negative_prompt STRING multiline 아니요 빈 값 —
image IMAGE 아니요 — image_to_model 소스; multiview_to_model 정면 이미지
image_left IMAGE 아니요 — multiview_to_model
image_back IMAGE 아니요 — multiview_to_model
image_right IMAGE 아니요 — multiview_to_model
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 —
image_seed INT 아니요 42 text_to_model
model_seed INT 아니요 42 —
texture_seed INT 아니요 42 —
texture_quality ENUM 아니요 standard standard, detailed
geometry_quality ENUM 아니요 standard standard, detailed; image_to_model
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; 이미지/multiview 모드
file_prefix STRING 아니요 빈 값 —
output_directory STRING 아니요 빈 값 —

출력: STRING model_file + MODEL_INFO. 선행 조건: 없음. 주요 실패 조건: 조건 입력/Key 누락, API 작업 또는 출력 이동 실패. 최소 연결: 텍스트/이미지 → TripoAPIDraft → Preview 3D.

세 가지 모드의 조건부 필수 입력은 다음과 같습니다.

mode 조건부 필수 설명
text_to_model prompt prompt는 비울 수 없습니다.
image_to_model image image가 필요합니다.
multiview_to_model image image는 정면이며 왼쪽, 뒤, 오른쪽은 선택 사항입니다.

TripoImportModel — Tripo: Import model

로컬 모델 또는 URL을 가져옵니다.

입력 타입 필수 기본값 값 / 범위
apikey STRING 예 빈 값 API key 또는 대체 설정
model_file file selector 아니요 none ComfyUI input 디렉터리
model_url STRING 아니요 빈 값 직접 URL
file_prefix STRING 아니요 빈 값 후속 노드로 전달
output_directory STRING 아니요 빈 값 후속 노드로 전달

출력: MODEL_INFO. 선행 조건: 로컬 파일 또는 URL. 주요 실패 조건: 소스 누락/접근 불가, 형식 거부 또는 import 실패. 최소 연결: 로컬 파일 또는 URL → TripoImportModel → MODEL_INFO.

비어 있지 않은 model_url이 model_file보다 우선합니다. 둘 다 없으면 실패합니다. 업로드는 .glb, .fbx, .obj, .stl, .ply, .3mf, .gltf를 받고 백엔드는 .zip도 인식합니다.

모델 처리

TripoTextureModel — Tripo: Texture model

모델에 텍스처를 생성합니다.

입력 타입 필수 기본값 값 / 범위
model_info MODEL_INFO 예 — 상위 작업 컨텍스트
model_version ENUM 아니요 v3.0-20250812 v2.5-20250123, v3.0-20250812
texture BOOLEAN 아니요 true —
pbr BOOLEAN 아니요 true —
texture_seed INT 아니요 42 —
texture_quality ENUM 아니요 standard standard, detailed
texture_alignment ENUM 아니요 original_image original_image, geometry
text_prompt STRING multiline 아니요 빈 값 —
image_prompt IMAGE 아니요 — —
style_image IMAGE 아니요 — —
part_names STRING multiline 아니요 빈 값 한 줄에 한 파트 이름
compress BOOLEAN 아니요 false —
bake BOOLEAN 아니요 true —

출력: STRING model_file + MODEL_INFO. 선행 조건: Generate / Import MODEL_INFO. 주요 실패 조건: 호환되지 않는 컨텍스트, 잘못된 이미지 또는 API 실패. 최소 연결: Generate / Import → TripoTextureModel → Preview 3D.

TripoRefineModel — Tripo: Refine Draft model

호환 초안 모델을 정제합니다.

입력 타입 필수 기본값 값 / 범위
model_info MODEL_INFO 예 — 초안 컨텍스트

출력: STRING model_file + MODEL_INFO. 선행 조건: 정제 가능한 초안 MODEL_INFO. 주요 실패 조건: 정제 불가 초안 또는 API 실패. 최소 연결: Generate draft → 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; v2 only
ref_image IMAGE 아니요 — v2 전용
split_by_connectivity BOOLEAN 아니요 true v2 전용

출력: STRING model_file + MODEL_INFO. 선행 조건: Generate / Import MODEL_INFO. 주요 실패 조건: 호환되지 않는 모델/참조 이미지 또는 API 실패. 최소 연결: Generate / Import → TripoMeshSegmentation → Completion / Preview.

segmentation_granularity, ref_image, split_by_connectivity는 v2.0-20260430에서만 전달되며 v1에서는 무시됩니다.

TripoMeshCompletion — Tripo: Complete mesh

분할된 메시를 보완합니다.

입력 타입 필수 기본값 값 / 범위
model_info MODEL_INFO 예 — 분할 컨텍스트
model_version ENUM 예 v1.0-20250506 v1.0-20250506
part_names STRING multiline 아니요 빈 값 한 줄에 한 파트 이름

출력: STRING model_file + MODEL_INFO. 선행 조건: 분할된 MODEL_INFO. 주요 실패 조건: 보완에 부적합한 작업 또는 API 실패. 최소 연결: Segment → 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 multiline 아니요 빈 값 한 줄에 한 파트 이름
face_limit INT 아니요 10000 -1–20000
bake BOOLEAN 아니요 true —

출력: STRING model_file + MODEL_INFO. 선행 조건: Generate / Import MODEL_INFO. 주요 실패 조건: 호환되지 않는 모델/파트 또는 API 실패. 최소 연결: Generate / Import → TripoSmartLowPoly → Preview / 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. 선행 조건: Generate / Import MODEL_INFO. 주요 실패 조건: 호환되지 않는 모델/스타일 또는 API 실패. 최소 연결: Generate / Import → TripoStylizeModel → Preview 3D.

리깅 및 애니메이션

TripoAnimateRigNode — Tripo: Rig model

모델을 자동 리깅합니다.

입력 타입 필수 기본값 값 / 범위
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. 선행 조건: Generate / Import MODEL_INFO. 주요 실패 조건: 리깅 불가, rig type 없음 또는 API 실패. 최소 연결: Generate / Import → TripoAnimateRigNode → Retarget / Preview.

리깅 전에 노드가 가능 여부를 확인하고 rig type을 가져옵니다.

TripoAnimateRetargetNode — Tripo: Retarget rigged model

프리셋 애니메이션을 적용합니다.

입력 타입 필수 기본값 값 / 범위
model_info MODEL_INFO 예 — 리깅 컨텍스트
animation ENUM 예 첫 번째 값 아래 16개 preset
out_format ENUM 예 glb glb, fbx
bake_animation BOOLEAN 아니요 true —
export_with_geometry BOOLEAN 아니요 false —

출력: STRING model_file + MODEL_INFO. 선행 조건: 리깅된 MODEL_INFO. 주요 실패 조건: 리깅되지 않은 컨텍스트 또는 API 실패. 최소 연결: Rig → TripoAnimateRetargetNode → Preview / Convert.

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.

형식 출력

TripoConvertNode — Tripo: Convert model

모델을 변환하고 내보냅니다.

입력 타입 필수 기본값 값 / 범위
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 —
bake BOOLEAN 아니요 true —
part_names STRING multiline 아니요 빈 값 한 줄에 한 파트 이름
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. 선행 조건: 호환 MODEL_INFO. 주요 실패 조건: 지원하지 않는 변환, 잘못된 설정 또는 출력 실패. 최소 연결: MODEL_INFO → TripoConvertNode.

Convert는 출력 노드이며 MODEL_INFO를 반환하지 않습니다.

workflow 예시

Preview 3D는 선택적인 ComfyUI 뷰어입니다.

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 Generate → Preview 3D.
  2. Image to Model: IMAGE → image, image_to_model → Preview 3D.
  3. Multiview to Model: 정면은 image, 선택 뷰는 image_left, image_back, image_right.
  4. Texture Model: Generate/Import → MODEL_INFO → Texture → Preview.
  5. Refine Model: 호환 초안 → MODEL_INFO → Refine → Preview.
  6. Rig and Retarget: Generate/Import → Rig → Retarget. MODEL_INFO로 연결합니다.
  7. Import and Process: 파일/URL → Import → Segment/Smart low poly/Stylize/Texture.
  8. Convert and Export: 최종 MODEL_INFO → Convert → 형식 선택.

공식 workflow PNG

다음 6개 PNG에는 ComfyUI workflow 데이터가 포함되어 있습니다. 다운로드 링크로 원본을 저장한 뒤 ComfyUI로 끌어오거나 직접 불러오세요. 이미지에 표시된 파라미터 값은 예시이며 현재 기본값은 파라미터 표를 따릅니다.

Text to Mesh

Tripo Generate model과 Preview 3D를 연결한 텍스트-메시 workflow

텍스트로 모델을 생성하고 model_file을 Preview 3D로 보냅니다.

원본 workflow PNG 다운로드

Image to Mesh

Load Image, Tripo Generate model, Preview 3D를 연결한 이미지-메시 workflow

이미지를 불러와 image_to_model 모드의 Generate model에 연결하고 결과를 미리 봅니다.

원본 workflow PNG 다운로드

Multiview Images to Mesh

Load Image 세 개, Tripo Generate model, Preview 3D를 연결한 멀티뷰 workflow

정면 이미지와 선택적 측면 이미지를 multiview_to_model 모드의 Generate model에 연결합니다.

원본 workflow PNG 다운로드

Texture a generated model

Generate model, Texture model, Preview 3D를 연결한 텍스처 workflow

Generate model의 MODEL_INFO를 Texture model로 전달하고 두 출력을 미리 봅니다.

원본 workflow PNG 다운로드

Refine a draft Mesh

Generate model, Refine Draft model, Preview 3D를 연결한 refine workflow

호환 초안을 생성하고 MODEL_INFO를 Refine Draft model로 전달해 결과를 미리 봅니다.

원본 workflow PNG 다운로드

Animation / Rig and export

Generate model, Rig model, Preview 3D, Convert model을 연결한 리깅 및 내보내기 workflow

원본 workflow PNG 다운로드

출력과 문제 해결

다운로드 기본 경로는 ComfyUI/output입니다. file_prefix는 이름을 바꾸고 output_directory는 파일을 이동하며 둘 다 MODEL_INFO로 전달됩니다.

증상 확인
API Key 누락 노드 Key, TRIPO_API_KEY 또는 config.json을 설정합니다.
prompt/정면 누락 mode와 조건부 입력을 확인합니다.
Import가 시작되지 않음 접근 가능한 URL 또는 기존 파일을 지정합니다. URL 우선입니다.
리깅 불가 적합한 캐릭터 모델을 사용합니다.
API 작업 실패 error_code, error_msg, 권한과 잔액을 확인합니다.
출력 이동 실패 대상 경로와 쓰기 권한을 확인합니다.
노드가 보이지 않음 ComfyUI를 다시 시작하고 디렉터리와 requirements.txt를 확인합니다.
업로드 실패 확장자와 ComfyUI 업로드 응답을 확인합니다.