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

EntradaRequeridoCampos opcionalesNotas
Texto a 3Dmodel, promptformat, quality, style, seedIdeal para generar un nuevo recurso a partir de una descripción
Imagen a 3Dmodel, image_url o image; también prompt cuando el modelo lo indiqueformat, 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

  • glb funciona bien para vistas previas web.
  • fbx y obj son útiles para pipelines DCC cuando el modelo seleccionado los admite.
  • usdz es útil para flujos de trabajo de RA (AR) de Apple cuando el modelo lo expone.
  • Los valores de quality más altos pueden aumentar el tiempo de espera y el costo. Muestre esa opción al usuario.
  • seed afecta 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_id cuando esté presente para una conciliación posterior.

Errores comunes

SíntomaCausa probableSolución
La respuesta de creación no tiene URL de recursoLa generación 3D es asíncronaRealice sondeos hasta obtener un estado terminal
Falta el formato solicitadoEl modelo no devolvió ese formatoVuelva a model_url o elija un modelo que admita el formato
Imagen a 3D rechazadaEl modelo seleccionado es solo de texto o la URL de la imagen no es accesibleVerifique los detalles del modelo y valide la URL
Recursos duplicadosLa ruta de reintento recreó la tarea después de un tiempo de esperaAlmacene la identidad de la tarea antes de reintentar

Referencia de la API

TemaReferencia
Crear 3DCrear 3D
Obtener estado 3DObtener estado 3D
Obtener estado de tareaObtener estado de tarea
Listar modelosListar modelos
Facturación y preciosFacturación y precios

En esta página