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:
| Entrada | Campo |
|---|---|
| Texto | prompt, hasta 4,000 caracteres |
| Una imagen | image_url, o image como Base64 o una URL de datos; is_pano indica si ya es una panorámica |
| Varias imágenes | images, hasta 4 |
| Video | video_url |
| Avanzado | world_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
| Tema | Referencia |
|---|---|
| Crear mundo | Crear mundo |
| Obtener estado de tarea | Obtener estado de tarea |
| Obtener estado de mundo (compatibilidad) | Obtener estado de mundo |
| Preparar carga de activo multimedia | Preparar carga de activo multimedia |
| Obtener activo multimedia | Obtener activo multimedia |
| Listar mundos | Listar mundos |
| Obtener mundo | Obtener mundo |
| Eliminar mundo | Eliminar mundo |
| Trabajos asíncronos | Trabajos asíncronos |
| Guía de generación 3D | Guía de generación 3D |