> ## 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.

# Generación 3D

> Crea tareas de texto a 3D o de imagen a 3D, consulta activos completados y maneja archivos de modelo descargables.

La generación 3D es asincrónica. `POST /v1/3d/generations` crea una tarea de TokenLab; las respuestas de estado completadas devuelven activos de modelo descargables como `model_url` y, cuando están disponibles, URLs específicas de formato.

## Elegir El Tipo De Entrada

| Flujo de trabajo | Entrada requerida                        | Campos opcionales                    | Notas                                                             |
| ---------------- | ---------------------------------------- | ------------------------------------ | ----------------------------------------------------------------- |
| Texto a 3D       | `model`, `prompt`                        | `format`, `quality`, `style`, `seed` | Mejor para generar un nuevo activo a partir de una descripción    |
| Imagen a 3D      | `model`, `prompt`, `image` o `image_url` | `format`, `quality`, `style`, `seed` | Usar solo cuando el modelo seleccionado soporte entrada de imagen |

Consulta el catálogo de modelos antes de decidir qué opciones exponer:

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

No asumas que cada modelo 3D soporta ambos tipos de entrada o cada formato de salida. Verifica el contrato del modelo seleccionado antes de enviar `image`, `image_url`, `format`, `quality`, `style` o `seed`.

## Crear Una Tarea 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 mascota estilizado de baja poligonización con topología limpia",
    "format": "glb",
    "quality": "standard"
  }'
```

Para imagen a 3D, usa un `image_url` público cuando sea posible. Usa `image` en línea/base64 solo cuando tu cliente envíe intencionalmente medios privados y tu backend esté preparado para cuerpos de solicitud más grandes.

## Opciones De Formato De Salida

* `glb` es generalmente el valor predeterminado más seguro para vistas previas web.
* `fbx` y `obj` son útiles para flujos de trabajo DCC cuando el modelo seleccionado los soporte.
* `usdz` es útil para flujos de trabajo de AR de Apple cuando es expuesto por el modelo.
* Valores de `quality` más altos pueden aumentar la latencia y el costo. Exponlos como opciones explícitas para el usuario, no como valores predeterminados ocultos.
* `seed` es útil para la reproducibilidad solo cuando el modelo lo respeta.

## Consultar Y Almacenar Activos

Usa primero el `poll_url` devuelto. Si tu cliente necesita una ruta fija, usa `GET /v1/tasks/{id}`.

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

Las tareas completadas devuelven `model_url` y pueden incluir `glb_url`, `fbx_url`, `obj_url` o `usdz_url`. Descarga o almacena el activo seleccionado en tu propio producto si los usuarios necesitan acceso repetido, historial de versiones o descargas prolongadas.

## Lista De Verificación De Producción

* Persiste `task_id`, `poll_url`, modelo, formato solicitado y tu propio ID de registro de activo.
* Reanuda la consulta después de la actualización de la página en lugar de crear una tarea duplicada.
* Valida el tamaño y la accesibilidad de la imagen de origen antes de crear la tarea.
* Mantén las URLs de activos generados fuera de las páginas públicas a menos que el usuario tenga permiso para acceder al activo.
* Registra `billing_transaction_id` cuando esté presente para una reconciliación posterior.

## Errores Comunes

| Síntoma                                         | Causa probable                                                                | Solución                                                       |
| ----------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
| La respuesta de creación no tiene URL de activo | La generación 3D es asíncrona                                                 | Consulta hasta obtener un estado terminal                      |
| Formato solicitado faltante                     | El modelo no devolvió ese formato                                             | Recurre a `model_url` o elige un modelo que soporte el formato |
| Imagen a 3D rechazada                           | El modelo seleccionado es solo de texto o la URL de la imagen no es accesible | Verifica el contrato del modelo y valida la URL                |
| Activos duplicados                              | La ruta de reintento recreó la tarea después de un tiempo de espera           | Almacena la identidad de la tarea antes de reintentar          |

## Referencia API

| Tema                    | Referencia                                                         |
| ----------------------- | ------------------------------------------------------------------ |
| Crear 3D                | [Crear 3D](/es/api-reference/3d/create-3d)                         |
| Obtener Estado 3D       | [Obtener Estado 3D](/es/api-reference/3d/get-3d-status)            |
| Obtener Estado de Tarea | [Obtener Estado de Tarea](/es/api-reference/tasks/get-task-status) |
| Listar Modelos          | [Listar Modelos](/es/api-reference/models/list-models)             |
| Facturación y Precios   | [Facturación y Precios](/es/guides/billing)                        |