Tripo3D

Nœuds ComfyUI

Nœuds ComfyUI

ComfyUI-Tripo est l’extension officielle de nœuds personnalisés de Tripo pour ComfyUI. Elle intègre aux workflows ComfyUI la génération 3D à partir de texte, d’images ou de vues multiples, ainsi que l’import de modèles, le texturage, l’affinage, le traitement de maillages, l’optimisation low-poly, la stylisation, le rigging, le retargeting d’animation, la conversion de formats et la retopologie.

Élément Valeur
Version du projet Node 1.3.0
Tag source v1.3.1.1
Dépôt VAST-AI-Research/ComfyUI-Tripo

Fonctions et journal des modifications

Fonctions

  • Générer des modèles 3D à partir de texte.
  • Générer des modèles 3D à partir d’images.
  • Importer des modèles depuis une URL avec model_url.
  • Prend en charge la séparation des parties du modèle.
  • Rigger et animer des modèles 3D.
  • Convertir les formats et retopologiser les modèles.

Journal des modifications

  • 2026-06-30 : ajout de Mesh Segmentation v2.0 pour découper les modèles en pièces et de l’import direct par URL avec model_url.
  • 2026-05-28 : ajout de l’import de modèles.
  • 2025-06-19 : mise à jour vers la dernière API et ajout de nœuds.
  • 2025-03-31 : adoption du package tripo3d.
  • 2025-02-24 : suppression de glbviewer.
  • 2025-02-01 : adaptation à la nouvelle API et adoption de Preview 3D pour l’affichage.
  • 2024-11-11 : adaptation à la nouvelle API.
  • 2024-10-14 : ajout de la conversion de modèles.
  • 2024-09-13 : prise en charge de model_version v2.0-20240919.

Installation

Outils officiels : ComfyUI-Manager, Comfy Registry et comfy-cli.

Choisissez une méthode puis redémarrez ComfyUI.

  1. ComfyUI-Manager: Recherchez Tripo for ComfyUI dans Custom Nodes Manager et installez-le.
  2. comfy-cli:
Bash
comfy node registry-install comfyui-tripo
  1. Depuis les sources:
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

Configuration de l’API Key

Créez d’abord une API Key sur la plateforme Tripo, puis configurez-la avec l’une des méthodes ci-dessous.

La clé est résolue dans cet ordre :

  1. Entrée apikey non vide du nœud.
  2. Variable d’environnement TRIPO_API_KEY.
  3. Champ TRIPO_API_KEY de config.json dans le répertoire du projet.

Generate et Import exposent apikey ; les nœuds suivants reçoivent la clé résolue via MODEL_INFO. N’exposez jamais une vraie clé dans des captures, workflows, journaux ou dépôts.

Exemples de lancement avec variable d’environnement

Windows :

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

Linux ou macOS :

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

Vue d’ensemble des nœuds

ComfyUI-Tripo fournit les 11 nœuds Tripo suivants :

Internal ID Display name Capacité Sortie
TripoAPIDraft Tripo: Generate model Génère un modèle depuis du texte, une image ou plusieurs vues. STRING model_file + MODEL_INFO
TripoImportModel Tripo: Import model Importe un modèle local ou une URL. MODEL_INFO
TripoTextureModel Tripo: Texture model Texture un modèle. STRING model_file + MODEL_INFO
TripoRefineModel Tripo: Refine Draft model Affine un brouillon compatible. STRING model_file + MODEL_INFO
TripoMeshSegmentation Tripo: Segment mesh Segmente un maillage. STRING model_file + MODEL_INFO
TripoMeshCompletion Tripo: Complete mesh Complète un maillage segmenté. STRING model_file + MODEL_INFO
TripoSmartLowPoly Tripo: Smart low poly Crée un modèle low-poly. STRING model_file + MODEL_INFO
TripoStylizeModel Tripo: Stylize model Applique un style géométrique. STRING model_file + MODEL_INFO
TripoAnimateRigNode Tripo: Rig model Réalise le rigging automatique. STRING model_file + MODEL_INFO
TripoAnimateRetargetNode Tripo: Retarget rigged model Applique une animation prédéfinie. STRING model_file + MODEL_INFO
TripoConvertNode Tripo: Convert model Convertit et exporte un modèle. STRING model_file

Preview 3D est fourni par ComfyUI et ne compte pas parmi les 11 nœuds Tripo.

Connexions et flux de données

flowchart LR
    G["Generate model"] -->|MODEL_INFO| P["Traitement du modèle"]
    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 est le chemin du fichier téléchargé destiné à la prévisualisation ou au traitement.
  • MODEL_INFO contient task_id, l’apikey résolue, file_prefix et output_directory.
  • Un modèle externe doit d’abord passer par TripoImportModel ; un chemin de fichier ne remplace pas MODEL_INFO.
  • Connectez MODEL_INFO pour poursuivre le traitement Tripo.

Référence complète des nœuds

« Obligatoire » indique les entrées requises par la définition du nœud. Un apikey vide peut utiliser l’environnement ou la configuration. Un tiret indique qu’aucune valeur par défaut explicite n’est définie.

Génération et import

TripoAPIDraft — Tripo: Generate model

Génère un modèle depuis du texte, une image ou plusieurs vues.

Entrée Type Obligatoire Défaut Valeurs / plage
mode ENUM Oui première valeur text_to_model, image_to_model, multiview_to_model
apikey STRING Oui vide API key ou configuration de secours
prompt STRING multiline Non vide text_to_model
negative_prompt STRING multiline Non vide —
image IMAGE Non — image_to_model source; multiview_to_model vue avant
image_left IMAGE Non — multiview_to_model
image_back IMAGE Non — multiview_to_model
image_right IMAGE Non — multiview_to_model
model_version ENUM Non v3.1-20260211 v1.4-20240625, v2.0-20240919, v2.5-20250123, v3.0-20250812, v3.1-20260211
texture BOOLEAN Non true —
pbr BOOLEAN Non true —
image_seed INT Non 42 text_to_model
model_seed INT Non 42 —
texture_seed INT Non 42 —
texture_quality ENUM Non standard standard, detailed
geometry_quality ENUM Non standard standard, detailed; image_to_model
texture_alignment ENUM Non original_image original_image, geometry
face_limit INT Non -1 -1–500000; ≤ 0 est considéré comme non défini
quad BOOLEAN Non false —
compress BOOLEAN Non false —
generate_parts BOOLEAN Non false —
smart_low_poly BOOLEAN Non false —
auto_size BOOLEAN Non false —
orientation ENUM Non default default, align_image; modes image/multiview
file_prefix STRING Non vide —
output_directory STRING Non vide —

Sortie: STRING model_file + MODEL_INFO. Prérequis: aucun. Échecs fréquents: entrée conditionnelle/clé manquante, tâche API ou déplacement de sortie en échec. Connexion minimale: Texte/image → TripoAPIDraft → Preview 3D.

Les trois modes imposent les entrées conditionnelles suivantes :

mode Obligatoire selon le mode Remarque
text_to_model prompt prompt ne doit pas être vide.
image_to_model image image est requis.
multiview_to_model image image est la vue avant ; gauche, arrière et droite sont facultatives.

TripoImportModel — Tripo: Import model

Importe un modèle local ou une URL.

Entrée Type Obligatoire Défaut Valeurs / plage
apikey STRING Oui vide API key ou configuration de secours
model_file file selector Non none répertoire input de ComfyUI
model_url STRING Non vide URL directe
file_prefix STRING Non vide propagé aux nœuds suivants
output_directory STRING Non vide propagé aux nœuds suivants

Sortie: MODEL_INFO. Prérequis: fichier local ou URL. Échecs fréquents: source absente/inaccessible, format refusé ou import en échec. Connexion minimale: fichier local ou URL → TripoImportModel → MODEL_INFO.

Un model_url non vide est prioritaire sur model_file. Sans les deux, le nœud échoue. Le contrôle accepte .glb, .fbx, .obj, .stl, .ply, .3mf et .gltf ; le backend détecte aussi .zip.

Traitement du modèle

TripoTextureModel — Tripo: Texture model

Texture un modèle.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte de tâche amont
model_version ENUM Non v3.0-20250812 v2.5-20250123, v3.0-20250812
texture BOOLEAN Non true —
pbr BOOLEAN Non true —
texture_seed INT Non 42 —
texture_quality ENUM Non standard standard, detailed
texture_alignment ENUM Non original_image original_image, geometry
text_prompt STRING multiline Non vide —
image_prompt IMAGE Non — —
style_image IMAGE Non — —
part_names STRING multiline Non vide one name per line
compress BOOLEAN Non false —
bake BOOLEAN Non true —

Sortie: STRING model_file + MODEL_INFO. Prérequis: Generate / Import MODEL_INFO. Échecs fréquents: contexte incompatible, image invalide ou échec API. Connexion minimale: Generate / Import → TripoTextureModel → Preview 3D.

TripoRefineModel — Tripo: Refine Draft model

Affine un brouillon compatible.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte de brouillon

Sortie: STRING model_file + MODEL_INFO. Prérequis: MODEL_INFO d’un brouillon compatible. Échecs fréquents: brouillon non compatible ou échec API. Connexion minimale: Generate draft → TripoRefineModel → Preview 3D.

TripoMeshSegmentation — Tripo: Segment mesh

Segmente un maillage.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte de tâche amont
model_version ENUM Oui v1.0-20250506 v1.0-20250506, v2.0-20260430
segmentation_granularity ENUM Non balanced simple, balanced, detailed; v2 uniquement
ref_image IMAGE Non — v2 uniquement
split_by_connectivity BOOLEAN Non true v2 uniquement

Sortie: STRING model_file + MODEL_INFO. Prérequis: Generate / Import MODEL_INFO. Échecs fréquents: modèle/référence incompatible ou échec API. Connexion minimale: Generate / Import → TripoMeshSegmentation → Completion / Preview.

segmentation_granularity, ref_image et split_by_connectivity ne sont envoyés qu’avec v2.0-20260430 ; v1 les ignore.

TripoMeshCompletion — Tripo: Complete mesh

Complète un maillage segmenté.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte segmenté
model_version ENUM Oui v1.0-20250506 v1.0-20250506
part_names STRING multiline Non vide one name per line

Sortie: STRING model_file + MODEL_INFO. Prérequis: MODEL_INFO segmenté. Échecs fréquents: tâche impropre à la complétion ou échec API. Connexion minimale: Segment → TripoMeshCompletion → Preview 3D.

TripoSmartLowPoly — Tripo: Smart low poly

Crée un modèle low-poly.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte de tâche amont
model_version ENUM Oui P-v2.0-20251225 P-v2.0-20251225
quad BOOLEAN Non false —
part_names STRING multiline Non vide one name per line
face_limit INT Non 10000 -1–20000
bake BOOLEAN Non true —

Sortie: STRING model_file + MODEL_INFO. Prérequis: Generate / Import MODEL_INFO. Échecs fréquents: modèle/parties incompatibles ou échec API. Connexion minimale: Generate / Import → TripoSmartLowPoly → Preview / Convert.

TripoStylizeModel — Tripo: Stylize model

Applique un style géométrique.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte de tâche amont
style ENUM Oui première valeur lego, voxel, voronoi, minecraft
block_size INT Oui 80 1–1000

Sortie: STRING model_file + MODEL_INFO. Prérequis: Generate / Import MODEL_INFO. Échecs fréquents: modèle/style incompatible ou échec API. Connexion minimale: Generate / Import → TripoStylizeModel → Preview 3D.

Rigging et animation

TripoAnimateRigNode — Tripo: Rig model

Réalise le rigging automatique.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte de tâche amont
model_version ENUM Oui v2.0-20250506 v1.0-20240301, v2.0-20250506
out_format ENUM Oui glb glb, fbx
spec ENUM Oui tripo mixamo, tripo

Sortie: STRING model_file + MODEL_INFO. Prérequis: Generate / Import MODEL_INFO. Échecs fréquents: modèle non riggable, aucun rig type ou échec API. Connexion minimale: Generate / Import → TripoAnimateRigNode → Retarget / Preview.

Avant le rigging, le nœud vérifie la compatibilité et obtient un rig type.

TripoAnimateRetargetNode — Tripo: Retarget rigged model

Applique une animation prédéfinie.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte riggé
animation ENUM Oui première valeur 16 presets ci-dessous
out_format ENUM Oui glb glb, fbx
bake_animation BOOLEAN Non true —
export_with_geometry BOOLEAN Non false —

Sortie: STRING model_file + MODEL_INFO. Prérequis: MODEL_INFO riggé. Échecs fréquents: contexte non riggé ou échec API. Connexion minimale: Rig → TripoAnimateRetargetNode → Preview / Convert.

Les 16 valeurs d’animation sont: 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.

Sortie de format

TripoConvertNode — Tripo: Convert model

Convertit et exporte un modèle.

Entrée Type Obligatoire Défaut Valeurs / plage
model_info MODEL_INFO Oui — contexte de tâche amont
format ENUM Oui première valeur GLTF, USDZ, FBX, OBJ, STL, 3MF
quad BOOLEAN Non false —
force_symmetry BOOLEAN Non false —
face_limit INT Non -1 -1–500000
flatten_bottom BOOLEAN Non false —
flatten_bottom_threshold FLOAT Non 0.01 0.0–1.0
texture_size INT Non 4096 128–4096
texture_format ENUM Non JPEG BMP, DPX, HDR, JPEG, OPEN_EXR, PNG, TARGA, TIFF, WEBP
pivot_to_center_bottom BOOLEAN Non false —
scale_factor FLOAT Non 1.0 minimum 0
with_animation BOOLEAN Non true —
pack_uv BOOLEAN Non false —
bake BOOLEAN Non true —
part_names STRING multiline Non vide one name per line
fbx_preset ENUM Non blender blender, mixamo, 3dsmax
export_vertex_colors BOOLEAN Non false —
export_orientation ENUM Non +x +x, +y, -x, -y
animate_in_place BOOLEAN Non false —

Sortie: STRING model_file. Prérequis: MODEL_INFO compatible. Échecs fréquents: conversion non prise en charge, réglages invalides ou erreur de sortie. Connexion minimale: MODEL_INFO → TripoConvertNode.

Convert est un nœud de sortie et ne renvoie pas MODEL_INFO.

Exemples de workflows

Preview 3D est seulement un visualiseur ComfyUI facultatif.

flowchart LR
    T["Texte"] --> GT["Generate model<br/>mode: text_to_model"]
    IM["Image"] --> GI["Generate model<br/>mode: image_to_model"]
    MV["Vue avant + vues facultatives"] --> GM["Generate model<br/>mode: multiview_to_model"]
    GT --> V["Preview 3D"]
    GI --> V
    GM --> V
  1. Text to Model : prompt → Generate avec text_to_model → Preview 3D.
  2. Image to Model : IMAGE → image, mode image_to_model → Preview 3D.
  3. Multiview to Model : avant vers image, vues facultatives vers image_left, image_back et image_right.
  4. Texture Model : Generate/Import → MODEL_INFO → Texture → Preview.
  5. Refine Model : brouillon compatible → MODEL_INFO → Refine → Preview.
  6. Rig and Retarget : Generate/Import → Rig → Retarget en reliant MODEL_INFO.
  7. Import and Process : fichier/URL → Import → Segment/Smart low poly/Stylize/Texture.
  8. Convert and Export : MODEL_INFO final → Convert → choisir le format.

PNG officiels des workflows

Les six PNG suivants contiennent les données de workflow ComfyUI. Enregistrez l’original via le lien de téléchargement, puis glissez-le dans ComfyUI ou chargez-le manuellement. Les valeurs de paramètres affichées dans les images sont uniquement des exemples ; les valeurs par défaut actuelles figurent dans les tableaux de paramètres.

Text to Mesh

Workflow texte vers maillage avec Tripo Generate model et Preview 3D

Génère un modèle depuis du texte et envoie model_file à Preview 3D.

Télécharger le PNG original du workflow

Image to Mesh

Workflow image vers maillage avec Load Image, Tripo Generate model et Preview 3D

Charge une image, relie-la à Generate model en mode image_to_model et affiche le résultat.

Télécharger le PNG original du workflow

Multiview Images to Mesh

Workflow multivue avec trois nœuds Load Image, Tripo Generate model et Preview 3D

Relie la vue de face et les vues latérales facultatives à Generate model en mode multiview_to_model.

Télécharger le PNG original du workflow

Texture a generated model

Workflow de texture avec Generate model, Texture model et Preview 3D

Transmet MODEL_INFO de Generate model à Texture model et affiche les deux sorties.

Télécharger le PNG original du workflow

Refine a draft Mesh

Workflow d’affinage avec Generate model, Refine Draft model et Preview 3D

Génère un brouillon compatible, transmet MODEL_INFO à Refine Draft model et affiche le résultat.

Télécharger le PNG original du workflow

Animation / Rig and export

Workflow de rig et export avec Generate model, Rig model, Preview 3D et Convert model

Télécharger le PNG original du workflow

Sortie et dépannage

Les téléchargements vont par défaut dans ComfyUI/output. file_prefix renomme le fichier et output_directory le déplace ; les deux sont propagés dans MODEL_INFO.

Symptôme Vérification
API Key absente Définir la clé du nœud, TRIPO_API_KEY ou config.json.
Prompt/vue avant absent Vérifier le mode et son entrée conditionnelle.
Import ne démarre pas Fournir une URL accessible ou un fichier existant ; l’URL est prioritaire.
Modèle non riggable Utiliser un modèle de personnage adapté.
Tâche API en échec Vérifier error_code, error_msg, accès et solde.
Sortie impossible à déplacer Vérifier le chemin et les droits d’écriture.
Nœuds absents Redémarrer ComfyUI et vérifier le répertoire et requirements.txt.
Échec du chargement Vérifier l’extension et la réponse de chargement ComfyUI.