Worlds

Crear mundo

Crea una tarea de generación de mundos con World Labs Marble

POST
/v1/worlds/generations

Genera mundos 3D explorables con World Labs Marble. Esta es una API asíncrona: las respuestas de creación devuelven una identidad de tarea. Consulta periódicamente GET /v1/tasks/{id} con el id de la tarea para conocer el estado.

Elige un modelo Marble disponible actualmente mediante la API de modelos.

Cuerpo de la solicitud

modelstringpredeterminado: marble-1.0

Elige un modelo Marble disponible actualmente mediante la API de modelos.

promptstring

Prompt de texto para generación basada únicamente en texto, o guía para entradas de imagen y video. Hasta 4000 caracteres. Envía al menos uno de world_prompt, prompt, image, image_url, images o video_url.

world_promptobject

Objeto world_prompt nativo de World Labs para usuarios avanzados. Los tipos de prompt admitidos son text, image, multi-image y video. Una referencia de contenido puede apuntar a un archivo que hayas subido con Preparar subida de recursos multimedia: { "source": "media_asset", "media_asset_id": "..." }.

imagestring

Prompt de imagen en Base64 o data URL.

image_urlstring

Prompt de URL de imagen.

imagesarray

Múltiples prompts de imagen para la generación rápida de varias imágenes. Proporciona hasta 4 imágenes, cada una como una URL, una cadena en Base64 o data URL, o un objeto con uri, image_url o url y un número azimuth opcional. Para el modo de reconstrucción nativo de World Labs, pasa world_prompt.type="multi-image" con reconstruct_images: true y hasta 8 imágenes.

video_urlstring

Prompt de URL de video.

is_panoboolean | string

Para entradas de imagen, establece true para un panorama existente, false para una imagen individual normal, o auto.

seedinteger

Semilla opcional de 0 a 4294967295.

display_namestring

Nombre para mostrar opcional para el mundo generado, de hasta 64 caracteres.

tagsarray

Etiquetas opcionales de World Labs. Proporciona hasta 10 etiquetas, cada una de hasta 32 caracteres.

permissionobject

Configuraciones opcionales de visibilidad y acceso: public, allow_id_access, allowed_readers y allowed_writers. public: true solicita un mundo visible públicamente.

Respuesta

idstring

ID público de la tarea. Consúltalo periódicamente mediante GET /v1/tasks/{id}.

task_idstring

Alias del identificador de la tarea asíncrona.

operation_idstring

ID de operación de World Labs.

poll_urlstring

URL de estado del mundo bajo /v1/worlds/generations/{id}. Este es un endpoint de compatibilidad. En su lugar, consulta periódicamente GET /v1/tasks/{id} con id.

statusstring

Estado de la tarea: pending, processing, completed o failed.

world_marble_urlstring

URL del mundo Marble generado cuando se completa.

glb_urlstring

URL del archivo GLB de la malla de colisión cuando esté disponible.

pano_urlstring

URL de la imagen panorámica cuando esté disponible.

Pricing

Consulta la API de precios para ver las tarifas actuales. El importe final facturado se muestra en tus registros de uso.

Errors

  • 400 invalid_request: no se envió ninguna entrada de prompt o un campo está fuera de rango. param indica el campo.
  • 400 model_not_found o unsupported_endpoint: el modelo no es un modelo Marble ejecutable.
  • 403 media_asset_not_owned o 404 media_asset_not_found: un media_asset_id en world_prompt pertenece a otro Workspace o no existe.
  • 402: el saldo es demasiado bajo para iniciar la tarea.

Solicitud

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"
  }'
{  "id": "string",  "task_id": "string",  "operation_id": "string",  "status": "pending",  "poll_url": "string",  "world_id": "string",  "world_marble_url": "string",  "model_url": "string",  "glb_url": "string",  "pano_url": "string",  "thumbnail_url": "string",  "caption": "string",  "error": "string",  "error_details": {    "projection_version": 0,    "status": 400,    "message": "string",    "type": "string",    "code": "string",    "param": "string",    "retryable": true,    "upstream": {      "source": "string",      "code": "string",      "message": "string",      "param": "string"    }  }}

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Clave opcional que hace que una solicitud de creación sea segura para reintentar. Envíe un nuevo valor único, como un UUID, para cada tarea. Un reintento con la misma clave y el mismo cuerpo devuelve el resultado de la solicitud de creación original, generalmente la tarea original, y no crea, envía ni cobra una segunda tarea. Un cuerpo diferente con una clave que ya fue aceptada se rechaza con 409. Se ignora una clave de más de 255 caracteres y la solicitud no tendrá protección de idempotencia. Consulte Reintente de forma segura con una clave de idempotencia.

Longitud1 <= length <= 255

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json