Guías de medios
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:
Usa el tipo de entrada en lugar de un campo operation para este endpoint. Los metadata del modelo informan las capacidades 3D como text-to-3d y/o image-to-3d; 3d-generation no es una operación pública de solicitud.
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
-H "Authorization: Bearer sk-your-api-key"Ejemplos actuales de Tripo incluyen tripo-h3.1 para flujos text/image-to-3D de alta calidad y tripo-p1.0 para generacion de assets 3D de estilo produccion. Usa Models API para confirmar el tipo de entrada y formato de salida.
No asumas que cada modelo 3D soporta ambos tipos de entrada o cada formato de salida. Verifica el detalle del modelo seleccionado antes de enviar image, image_url, format, quality, style o seed.
Crear Una Tarea 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 mascota estilizado de baja poligonización con topología limpia"
}'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
glbes generalmente el valor predeterminado más seguro para vistas previas web.fbxyobjson útiles para flujos de trabajo DCC cuando el modelo seleccionado los soporte.usdzes útil para flujos de trabajo de AR de Apple cuando es expuesto por el modelo.- Valores de
qualitymás altos pueden aumentar la latencia y el costo. Exponlos como opciones explícitas para el usuario, no como valores predeterminados ocultos. seedes ú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}.
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_idcuando 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 detalle 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 |
| Obtener Estado 3D | Obtener Estado 3D |
| Obtener Estado de Tarea | Obtener Estado de Tarea |
| Listar Modelos | Listar Modelos |
| Facturación y Precios | Facturación y Precios |