Guías de medios

Worlds

Cree mundos Marble explorables a partir de texto, imágenes o video

Worlds crea un entorno Marble que las personas pueden abrir y explorar. Si necesita un objeto descargable en lugar de un entorno, utilice la generación 3D.

Los archivos de World descargables, como splats, mallas e imágenes panorámicas, se conservan como copias automáticas de 30 días con URLs de resultados multimedia de TokenLab. La página interactiva de World y los registros de World no se conservan. Consulte Retención de datos.

Entradas y activos multimedia

Un mundo puede comenzar a partir de texto, una o más imágenes, o video, dependiendo del modelo. Encuentre los modelos Marble (marble-*) en GET /v1/models?recommended_for=3d; su operación es world-generation. Envíe al menos una entrada:

EntradaCampo
Textoprompt, hasta 4,000 caracteres
Una imagenimage_url, o image como Base64 o una URL de datos; is_pano indica si ya es una panorámica
Varias imágenesimages, hasta 4
Videovideo_url
Avanzadoworld_prompt, un objeto de prompt nativo que puede hacer referencia a un activo multimedia cargado

Los campos opcionales son display_name (hasta 64 caracteres), seed, tags (hasta 10) y permission. Los medios reutilizables se pueden cargar una vez y hacer referencia a ellos mediante su ID de activo.

El acceso a los medios y a los registros de World se verifica con la organización propietaria de la API key. Revise las opciones de permission del modelo seleccionado antes de compartir un mundo; un activo devuelto o una URL de visor pueden tener sus propias reglas de acceso.

Crear y consultar (Poll)

La respuesta de creación contiene un ID de tarea y, por lo general, una poll_url. Guarde el ID y luego llame a GET /v1/tasks/{id} con él hasta que el estado sea completed o failed. La poll_url de Worlds apunta a /v1/worlds/generations/{id}, una ruta de compatibilidad. Utilice /v1/tasks/{id} en su lugar.

curl -X POST "https://api.tokenlab.sh/v1/worlds/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "marble-1.1",
    "prompt": "A quiet coastal town at sunset with narrow alleys and warm lights"
  }'

Consulte la tarea con el id de la respuesta de creación:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Gestionar mundos completados

Utilice POST /v1/worlds/list y GET /v1/worlds/{id} para los mundos completados disponibles en su cuenta, y DELETE /v1/worlds/{id} para eliminar uno. Utilice GET /v1/tasks/{id} para tareas de generación pendientes o fallidas. Elimine solo cuando el usuario elimine intencionalmente el mundo generado de su producto.

Errores comunes

  • No asuma que todos los modelos de mundo admiten todos los tipos de entrada.
  • Mantenga las URLs de imágenes o videos firmadas válidas el tiempo suficiente para los reintentos de recuperación del servicio.
  • Almacene el ID de tarea devuelto antes de reintentar después de un tiempo de espera (timeout).
  • Utilice la generación 3D para archivos de modelos descargables en lugar de mundos explorables.

Referencia de la API

TemaReferencia
Crear mundoCrear mundo
Obtener estado de tareaObtener estado de tarea
Obtener estado de mundo (compatibilidad)Obtener estado de mundo
Preparar carga de activo multimediaPreparar carga de activo multimedia
Obtener activo multimediaObtener activo multimedia
Listar mundosListar mundos
Obtener mundoObtener mundo
Eliminar mundoEliminar mundo
Trabajos asíncronosTrabajos asíncronos
Guía de generación 3DGuía de generación 3D

En esta página