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

# Create World

> Creates a World Labs Marble world generation task

Generate explorable 3D worlds with World Labs Marble. This is an asynchronous API: create responses return a task identity and a `poll_url` for status checks.

Supported models are `marble-1.0`, `marble-1.1`, and `marble-1.1-plus`. World Labs documents `marble-1.0-draft`, but AI Sonar does not expose draft generation in this endpoint yet.

## Request Body

<ParamField body="model" type="string" default="marble-1.0">
  Marble model to use: `marble-1.0`, `marble-1.1`, or `marble-1.1-plus`.
</ParamField>

<ParamField body="prompt" type="string">
  Text prompt for text-only generation or as guidance with image/video inputs.
</ParamField>

<ParamField body="world_prompt" type="object">
  Native World Labs `world_prompt` object for advanced callers. Supported prompt types are `text`, `image`, `multi-image`, and `video`.
</ParamField>

<ParamField body="image" type="string">
  Base64 or data URL image prompt.
</ParamField>

<ParamField body="image_url" type="string">
  Image URL prompt.
</ParamField>

<ParamField body="images" type="array">
  Multiple image prompts for shortcut multi-image generation. Provide up to 4 images. For native World Labs reconstruction mode, pass `world_prompt.type="multi-image"` with `reconstruct_images: true` and up to 8 images.
</ParamField>

<ParamField body="video_url" type="string">
  Video URL prompt.
</ParamField>

<ParamField body="is_pano" type="boolean | string">
  For image inputs, set `true` for an existing panorama, `false` for a normal single image, or `auto`.
</ParamField>

<ParamField body="seed" type="integer">
  Optional seed from 0 through 4294967295.
</ParamField>

<ParamField body="display_name" type="string">
  Optional display name for the generated world, up to 64 characters.
</ParamField>

<ParamField body="tags" type="array">
  Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
</ParamField>

<ParamField body="permission" type="object">
  Optional World Labs permission object.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Public task ID for polling.
</ResponseField>

<ResponseField name="task_id" type="string">
  Async task identifier alias.
</ResponseField>

<ResponseField name="operation_id" type="string">
  World Labs operation ID.
</ResponseField>

<ResponseField name="poll_url" type="string">
  Preferred polling URL for this task.
</ResponseField>

<ResponseField name="status" type="string">
  Task status: `pending`, `processing`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="world_marble_url" type="string">
  URL for the generated Marble world when completed.
</ResponseField>

<ResponseField name="glb_url" type="string">
  Collider mesh GLB URL when available.
</ResponseField>

<ResponseField name="pano_url" type="string">
  Panorama image URL when available.
</ResponseField>

## Pricing

World Labs bills in credits. AI Sonar pre-deducts the request-type maximum and settles from the completed operation's `cost.total_credits` when available. Standard Marble requests are up to 1,600 credits. `marble-1.1-plus` requests are up to 3,100 credits.

## Scope

These management endpoints cover AI Sonar-owned media assets and completed generated worlds. AI Sonar still does not expose `marble-1.0-draft` generation or standalone pano/depth tools.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.aisonar.dev/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"
    }'
  ```

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

  response = requests.post(
      "https://api.aisonar.dev/v1/worlds/generations",
      headers={"Authorization": "Bearer sk-your-api-key"},
      json={
          "model": "marble-1.1",
          "prompt": "A quiet coastal town at sunset with narrow alleys and warm lights",
      },
  )

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.aisonar.dev/v1/worlds/generations', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'marble-1.1',
      prompt: 'A quiet coastal town at sunset with narrow alleys and warm lights'
    })
  });

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