Génération 3D

La génération 3D est asynchrone. POST /v1/3d/generations crée une tâche TokenLab ; les réponses de statut complété retournent des actifs de modèle téléchargeables tels que model_url et, lorsque disponible, des URL spécifiques au format.

Choisissez le type d’entrée

Flux de travail	Entrée requise	Champs optionnels	Remarques
Texte à 3D	`model`, `prompt`	`format`, `quality`, `style`, `seed`	Meilleur pour générer un nouvel actif à partir d’une description
Image à 3D	`model`, `prompt`, `image` ou `image_url`	`format`, `quality`, `style`, `seed`	Utilisez uniquement lorsque le modèle sélectionné prend en charge l’entrée d’image

Interrogez le catalogue de modèles avant de décider quelles options exposer : Utilisez le type d’entrée plutôt qu’un champ operation pour cet endpoint. Les metadata du modèle signalent les capacités 3D sous la forme text-to-3d et/ou image-to-3d ; 3d-generation n’est pas une opération de requête publique.

curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"

Les exemples Tripo actuels incluent tripo-h3.1 pour les workflows text/image-to-3D de haute qualite et tripo-p1.0 pour la generation d assets 3D de style production. Utilisez Models API pour confirmer le type d entree et le format de sortie. Ne supposez pas que chaque modèle 3D prend en charge les deux types d’entrée ou chaque format de sortie. Vérifiez le détail du modèle sélectionné avant d’envoyer image, image_url, format, quality, style ou seed.

Créer une tâche 3D

curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo-h3.1",
    "prompt": "Un robot mascotte stylisé en low-poly avec une topologie propre",
    "format": "glb",
    "quality": "standard"
  }'

Pour l’image à 3D, utilisez une image_url publique lorsque cela est possible. Utilisez image en ligne/base64 uniquement lorsque votre client envoie intentionnellement des médias privés et que votre backend est préparé pour des corps de requête plus volumineux.

Choix de format de sortie

glb est généralement le meilleur choix par défaut pour les aperçus web.
fbx et obj sont utiles pour les pipelines DCC lorsque le modèle sélectionné les prend en charge.
usdz est utile pour les flux de travail AR d’Apple lorsqu’il est exposé par le modèle.
Des valeurs de quality plus élevées peuvent augmenter la latence et le coût. Exposez-les comme des choix explicites pour l’utilisateur, pas comme des valeurs par défaut cachées.
seed est utile pour la reproductibilité uniquement lorsque le modèle le respecte.

Interroger et stocker des actifs

Utilisez d’abord le poll_url retourné. Si votre client a besoin d’un itinéraire fixe, utilisez GET /v1/tasks/{id}.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Les tâches complétées retournent model_url et peuvent inclure glb_url, fbx_url, obj_url ou usdz_url. Téléchargez ou mettez en cache l’actif sélectionné dans votre propre produit si les utilisateurs ont besoin d’un accès répété, d’un historique de versions ou de téléchargements à long terme.

Liste de contrôle de production

Conservez task_id, poll_url, modèle, format demandé et votre propre ID d’enregistrement d’actif.
Reprenez l’interrogation après un rafraîchissement de page plutôt que de créer une tâche en double.
Validez la taille et l’accessibilité de l’image source avant de créer la tâche.
Gardez les URL des actifs générés hors des pages publiques, sauf si l’utilisateur a la permission d’accéder à l’actif.
Enregistrez billing_transaction_id lorsqu’il est présent pour une réconciliation ultérieure.

Erreurs courantes

Symptôme	Cause probable	Solution
La réponse de création n’a pas d’URL d’actif	La génération 3D est asynchrone	Interrogez jusqu’à un statut terminal
Format demandé manquant	Le modèle n’a pas retourné ce format	Revenez à `model_url` ou choisissez un modèle qui prend en charge le format
Image à 3D rejetée	Le modèle sélectionné est uniquement textuel ou l’URL de l’image est inaccessible	Vérifiez le détail du modèle et validez l’URL
Actifs en double	Le chemin de réessai a recréé la tâche après un délai d’attente	Conservez l’identité de la tâche avant de réessayer

Référence API

Sujet	Référence
Créer 3D	Créer 3D
Obtenir le statut 3D	Obtenir le statut 3D
Obtenir le statut de la tâche	Obtenir le statut de la tâche
Lister les modèles	Lister les modèles
Facturation et tarification	Facturation et tarification

Démarrage

Guides essentiels

Guides médias

Choisissez le type d’entrée

Créer une tâche 3D

Choix de format de sortie

Interroger et stocker des actifs

Liste de contrôle de production

Erreurs courantes

Référence API

​Choisissez le type d’entrée

​Créer une tâche 3D

​Choix de format de sortie

​Interroger et stocker des actifs

​Liste de contrôle de production

​Erreurs courantes

​Référence API

Choisissez le type d’entrée

Créer une tâche 3D

Choix de format de sortie

Interroger et stocker des actifs

Liste de contrôle de production

Erreurs courantes

Référence API