> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Génération 3D

> Créez des tâches de texte à 3D ou d'image à 3D, interrogez les actifs terminés et gérez les fichiers de modèle téléchargeables.

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 :

```bash theme={null}
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

```bash theme={null}
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}`.

```bash theme={null}
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 contrat 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](/fr/api-reference/3d/create-3d)                               |
| Obtenir le statut 3D          | [Obtenir le statut 3D](/fr/api-reference/3d/get-3d-status)               |
| Obtenir le statut de la tâche | [Obtenir le statut de la tâche](/fr/api-reference/tasks/get-task-status) |
| Lister les modèles            | [Lister les modèles](/fr/api-reference/models/list-models)               |
| Facturation et tarification   | [Facturation et tarification](/fr/guides/billing)                        |