Passer au contenu principal
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 travailEntrée requiseChamps optionnelsRemarques
Texte à 3Dmodel, promptformat, quality, style, seedMeilleur pour générer un nouvel actif à partir d’une description
Image à 3Dmodel, prompt, image ou image_urlformat, quality, style, seedUtilisez 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 : 
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"
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 contrat 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": "tripo3d-v2.5",
    "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ômeCause probableSolution
La réponse de création n’a pas d’URL d’actifLa génération 3D est asynchroneInterrogez jusqu’à un statut terminal
Format demandé manquantLe modèle n’a pas retourné ce formatRevenez à model_url ou choisissez un modèle qui prend en charge le format
Image à 3D rejetéeLe modèle sélectionné est uniquement textuel ou l’URL de l’image est inaccessibleVérifiez le contrat du modèle et validez l’URL
Actifs en doubleLe chemin de réessai a recréé la tâche après un délai d’attenteConservez l’identité de la tâche avant de réessayer

​
Référence API

SujetRéférence
Créer 3DCréer 3D
Obtenir le statut 3DObtenir le statut 3D
Obtenir le statut de la tâcheObtenir le statut de la tâche
Lister les modèlesLister les modèles
Facturation et tarificationFacturation et tarification