> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear World

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

Genera mundos 3D explorables con World Labs Marble. Esta API es asíncrona: las respuestas de creación devuelven una identidad de tarea y una `poll_url` para comprobar el estado.

Los modelos compatibles son `marble-1.0`, `marble-1.1` y `marble-1.1-plus`. World Labs documenta `marble-1.0-draft`, pero TokenLab todavía no expone la generación draft en este endpoint.

## Cuerpo de la solicitud

<ParamField body="model" type="string" default="marble-1.0">
  Modelo Marble a usar: `marble-1.0`, `marble-1.1` o `marble-1.1-plus`.
</ParamField>

<ParamField body="prompt" type="string">
  Prompt de texto para generación solo con texto o como guía con entradas de imagen/vídeo.
</ParamField>

<ParamField body="world_prompt" type="object">
  Objeto nativo de World Labs `world_prompt` para llamadas avanzadas. Los tipos soportados son `text`, `image`, `multi-image` y `video`.
</ParamField>

<ParamField body="image" type="string">
  Prompt de imagen en Base64 o data URL.
</ParamField>

<ParamField body="image_url" type="string">
  Prompt mediante URL de imagen.
</ParamField>

<ParamField body="images" type="array">
  Varios prompts de imagen para generación multi-image rápida. Proporciona hasta 4 imágenes. 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.
</ParamField>

<ParamField body="video_url" type="string">
  Prompt mediante URL de vídeo.
</ParamField>

<ParamField body="is_pano" type="boolean | string">
  Para entradas de imagen, usa `true` para un panorama existente, `false` para una imagen normal, o `auto`.
</ParamField>

<ParamField body="seed" type="integer">
  Seed opcional de 0 a 4294967295.
</ParamField>

<ParamField body="display_name" type="string">
  Nombre visible opcional para el mundo generado, hasta 64 caracteres.
</ParamField>

<ParamField body="tags" type="array">
  Tags opcionales de World Labs. Hasta 10 tags, 32 caracteres cada uno.
</ParamField>

<ParamField body="permission" type="object">
  Objeto permission de World Labs opcional.
</ParamField>

## Respuesta

<ResponseField name="id" type="string">
  ID público de tarea para polling.
</ResponseField>

<ResponseField name="task_id" type="string">
  Alias del identificador de tarea asíncrona.
</ResponseField>

<ResponseField name="operation_id" type="string">
  ID de operación de World Labs.
</ResponseField>

<ResponseField name="poll_url" type="string">
  URL de polling preferida para esta tarea.
</ResponseField>

<ResponseField name="status" type="string">
  Estado de la tarea: `pending`, `processing`, `completed` o `failed`.
</ResponseField>

<ResponseField name="world_marble_url" type="string">
  URL del mundo Marble generado cuando finaliza.
</ResponseField>

<ResponseField name="glb_url" type="string">
  URL GLB de la malla collider si está disponible.
</ResponseField>

<ResponseField name="pano_url" type="string">
  URL de imagen panorámica si está disponible.
</ResponseField>

## Precios

World Labs factura en credits. TokenLab descuenta primero el máximo del tipo de solicitud y liquida según `cost.total_credits` de la operation completada cuando está disponible. Las solicitudes Marble estándar llegan hasta 1.600 credits. `marble-1.1-plus` llega hasta 3.100 credits.

## Alcance

Estos endpoints de gestión cubren medios propiedad de TokenLab y Worlds generados completados. TokenLab todavía no expone generación `marble-1.0-draft` ni herramientas pano/depth independientes.

<RequestExample>
  ```bash cURL theme={null}
  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": "Un tranquilo pueblo costero al atardecer con callejones estrechos y luces cálidas"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tokenlab.sh/v1/worlds/generations",
      headers={"Authorization": "Bearer sk-your-api-key"},
      json={
          "model": "marble-1.1",
          "prompt": "Un tranquilo pueblo costero al atardecer con callejones estrechos y luces cálidas",
      },
  )

  task = response.json()
  print(task["id"], task["poll_url"])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.tokenlab.sh/v1/worlds/generations', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'marble-1.1',
      prompt: 'Un tranquilo pueblo costero al atardecer con callejones estrechos y luces cálidas'
    })
  });

  const task = await response.json();
  console.log(task.id, task.poll_url);
  ```
</RequestExample>