TokenLab

Worlds

Create World

Creates a World Labs Marble world generation task

POST
/v1/worlds/generations

Generate explorable 3D worlds with World Labs Marble. This is an asynchronous API: create responses return a task identity. Poll GET /v1/tasks/{id} with the task id for status.

Choose a currently available Marble model using the Models API.

Request Body

modelstringdefault: marble-1.0

Choose a currently available Marble model using the Models API.

promptstring

Text prompt for text-only generation, or guidance for image and video inputs. Up to 4000 characters. Send at least one of world_prompt, prompt, image, image_url, images, or video_url.

world_promptobject

Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. A content reference can point at a file you uploaded with Prepare Media Asset Upload: { "source": "media_asset", "media_asset_id": "..." }.

imagestring

Base64 or data URL image prompt.

image_urlstring

Image URL prompt.

imagesarray

Multiple image prompts for shortcut multi-image generation. Provide up to 4 images, each a URL, a Base64 or data URL string, or an object with uri, image_url, or url and an optional azimuth number. For native World Labs reconstruction mode, pass world_prompt.type="multi-image" with reconstruct_images: true and up to 8 images.

video_urlstring

Video URL prompt.

is_panoboolean | string

For image inputs, set true for an existing panorama, false for a normal single image, or auto.

seedinteger

Optional seed from 0 through 4294967295.

display_namestring

Optional display name for the generated world, up to 64 characters.

tagsarray

Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.

permissionobject

Optional visibility and access settings: public, allow_id_access, allowed_readers, and allowed_writers. public: true requests a publicly visible world.

Response

idstring

Public task ID. Poll GET /v1/tasks/{id} with it.

task_idstring

Async task identifier alias.

operation_idstring

World Labs operation ID.

poll_urlstring

World status URL under /v1/worlds/generations/{id}. This is a compatibility endpoint. Poll GET /v1/tasks/{id} with id instead.

statusstring

Task status: pending, processing, completed, or failed.

world_marble_urlstring

URL for the generated Marble world when completed.

glb_urlstring

Collider mesh GLB URL when available.

pano_urlstring

Panorama image URL when available.

Pricing

See the Pricing API for current rates. The final billed amount is shown in your usage records.

Errors

  • 400 invalid_request: no prompt input was sent, or a field is out of range. param names the field.
  • 400 model_not_found or unsupported_endpoint: the model is not a callable Marble model.
  • 403 media_asset_not_owned or 404 media_asset_not_found: a media_asset_id in world_prompt belongs to another Workspace or does not exist.
  • 402: the balance is too low to start the task.

Request

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"    }  }}

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Value in

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

Optional key that makes a create request safe to retry. Send a new unique value, such as a UUID, for each task. A retry with the same key and the same body returns the result of the original create request, usually the original task, and does not create, dispatch, or charge a second task. A different body with a key that was already accepted is rejected with 409. A key longer than 255 characters is ignored, and the request then has no idempotency protection. See Retry safely with an idempotency key.

Length1 <= length <= 255

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json