Guides médias
Génération 3D
Créez des modèles 3D téléchargeables à partir de texte ou d'images
La génération 3D est asynchrone. POST /v1/3d/generations crée une tâche TokenLab ; les réponses avec un statut terminé renvoient des ressources de modèle téléchargeables telles que model_url et, lorsqu'ils sont disponibles, des URLs spécifiques au format.
Les fichiers de modèles 3D téléchargeables sont conservés sous forme de copies automatiques pendant 30 jours, et leurs URLs sont des URLs de résultats média TokenLab. Les enregistrements de tâches et les ressources enregistrées séparément suivent leur propre cycle de vie. Voir Rétention des données.
Choisir le type d'entrée
| Entrée | Requis | Champs optionnels | Notes |
|---|---|---|---|
| Text-to-3D | model, prompt | format, quality, style, seed | Idéal pour générer une nouvelle ressource à partir d'une description |
| Image-to-3D | model, image_url ou image ; aussi prompt quand le modèle l'indique | format, quality, style, seed | À utiliser uniquement lorsque le modèle sélectionné prend en charge l'entrée d'image |
operation est optionnel et peut être text-to-3d ou image-to-3d. Si vous ne le spécifiez pas, TokenLab utilise image-to-3d lorsque vous envoyez image ou image_url, et text-to-3d dans le cas contraire. Si vous l'envoyez, il doit correspondre aux entrées. Un modèle avec text-to-3d accepte des prompts ; un modèle avec image-to-3d accepte une entrée d'image.
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
-H "Authorization: Bearer sk-your-api-key"Ne présumez pas que chaque modèle 3D prend en charge les deux types d'entrée ou tous les formats de sortie. Vérifiez les détails 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": "A stylized low-poly robot mascot with clean topology"
}'Pour le mode image-to-3D, utilisez une URL https lorsque la source peut être récupérée depuis Internet. Utilisez l'image en base64 image uniquement sur un modèle dont les détails listent image ; certains modèles n'acceptent que image_url.
Formats de sortie
glbfonctionne bien pour les aperçus web.fbxetobjsont utiles pour les pipelines DCC lorsque le modèle sélectionné les prend en charge.usdzest utile pour les flux de travail AR Apple lorsqu'il est exposé par le modèle.- Des valeurs de
qualityplus élevées peuvent augmenter le temps d'attente et le coût. Affichez ce choix à l'utilisateur. seedn'affecte la répétabilité que sur les modèles qui le prennent en charge.
Obtenir le modèle terminé
Appelez GET /v1/tasks/{id} avec l' id ou task_id renvoyé.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Les tâches terminées renvoient model_url et peuvent inclure glb_url, fbx_url, obj_url ou usdz_url. Téléchargez ou mettez en cache la ressource sélectionnée dans votre propre produit si les utilisateurs ont besoin d'un accès répété, d'un historique des versions ou de téléchargements à long terme.
Maintenir le résultat disponible
- Persistez
task_id,poll_url, le modèle, le format demandé et votre propre ID d'enregistrement de ressource. - Reprenez le polling 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 URLs des ressources générées hors des pages publiques, sauf si l'utilisateur a la permission d'accéder à la ressource.
- Enregistrez
billing_transaction_idlorsqu'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 de ressource | La génération 3D est asynchrone | Poller jusqu'au statut final |
| Format demandé manquant | Le modèle n'a pas renvoyé ce format | Repliez-vous sur model_url ou choisissez un modèle qui prend en charge le format |
| Image-to-3D rejeté | Le modèle sélectionné est uniquement textuel ou l'URL de l'image est inaccessible | Vérifiez les détails du modèle et validez l'URL |
| Ressources en double | Le chemin de réessai a recréé la tâche après un délai d'attente | Stockez 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 |