Guías de medios
Generación 3D
Cree modelos 3D descargables a partir de texto o imágenes
La generación 3D es asíncrona. POST /v1/3d/generations crea una tarea de TokenLab; las respuestas de estado completado devuelven recursos de modelos descargables como model_url y, cuando están disponibles, URLs específicas de formato.
Los archivos de modelos 3D descargables se mantienen como copias automáticas durante 30 días, y sus URLs son URLs de resultados multimedia de TokenLab. Los registros de tareas y los recursos guardados por separado siguen su propio ciclo de vida. Consulte Retención de datos.
Elija el tipo de entrada
| Entrada | Requerido | Campos opcionales | Notas |
|---|---|---|---|
| Texto a 3D | model, prompt | format, quality, style, seed | Ideal para generar un nuevo recurso a partir de una descripción |
| Imagen a 3D | model, image_url o image; también prompt cuando el modelo lo indique | format, quality, style, seed | Úselo solo cuando el modelo seleccionado admita entrada de imagen |
operation es opcional y puede ser text-to-3d o image-to-3d. Si lo omite, TokenLab utiliza image-to-3d cuando envía image o image_url, y text-to-3d en caso contrario. Si lo envía, debe coincidir con las entradas. Un modelo con text-to-3d acepta prompts; un modelo con image-to-3d acepta entrada de imagen.
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
-H "Authorization: Bearer sk-your-api-key"No asuma que todos los modelos 3D admiten ambos tipos de entrada o todos los formatos de salida. Verifique los detalles 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": "A stylized low-poly robot mascot with clean topology"
}'Para imagen a 3D, utilice una URL https cuando la fuente pueda obtenerse de internet. Utilice image en base64 en línea solo en un modelo cuyos detalles indiquen image; algunos modelos solo aceptan image_url.
Formatos de salida
glbfunciona bien para vistas previas web.fbxyobjson útiles para pipelines DCC cuando el modelo seleccionado los admite.usdzes útil para flujos de trabajo de RA (AR) de Apple cuando el modelo lo expone.- Los valores de
qualitymás altos pueden aumentar el tiempo de espera y el costo. Muestre esa opción al usuario. seedafecta la repetibilidad solo en modelos que lo admiten.
Obtener el modelo finalizado
Llame a GET /v1/tasks/{id} con el id o task_id devuelto.
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. Descargue o almacene en caché el recurso seleccionado en su propio producto si los usuarios necesitan acceso repetido, historial de versiones o descargas de larga duración.
Mantener el resultado disponible
- Persista
task_id,poll_url, el modelo, el formato solicitado y su propio ID de registro de recurso. - Reanude el sondeo (polling) después de actualizar la página en lugar de crear una tarea duplicada.
- Valide el tamaño y la accesibilidad de la imagen de origen antes de crear la tarea.
- Mantenga las URLs de los recursos generados fuera de las páginas públicas a menos que el usuario tenga permiso para acceder al recurso.
- Registre
billing_transaction_idcuando esté presente para una conciliación posterior.
Errores comunes
| Síntoma | Causa probable | Solución |
|---|---|---|
| La respuesta de creación no tiene URL de recurso | La generación 3D es asíncrona | Realice sondeos hasta obtener un estado terminal |
| Falta el formato solicitado | El modelo no devolvió ese formato | Vuelva a model_url o elija un modelo que admita el formato |
| Imagen a 3D rechazada | El modelo seleccionado es solo de texto o la URL de la imagen no es accesible | Verifique los detalles del modelo y valide la URL |
| Recursos duplicados | La ruta de reintento recreó la tarea después de un tiempo de espera | Almacene la identidad de la tarea antes de reintentar |
Referencia de la 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 |