Worlds
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. Poll GET /v1/tasks/{id} with the task id for status.
Choose a currently available Marble model using the Models API.
Request Body
marble-1.0Choose a currently available Marble model using the Models API.
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.
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": "..." }.
Base64 or data URL image prompt.
Image URL prompt.
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 URL prompt.
For image inputs, set true for an existing panorama, false for a normal single image, or auto.
Optional seed from 0 through 4294967295.
Optional display name for the generated world, up to 64 characters.
Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
Optional visibility and access settings: public, allow_id_access, allowed_readers, and allowed_writers. public: true requests a publicly visible world.
Response
Public task ID. Poll GET /v1/tasks/{id} with it.
Async task identifier alias.
World Labs operation ID.
World status URL under /v1/worlds/generations/{id}. This is a compatibility endpoint. Poll GET /v1/tasks/{id} with id instead.
Task status: pending, processing, completed, or failed.
URL for the generated Marble world when completed.
Collider mesh GLB URL when available.
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.paramnames the field.400 model_not_foundorunsupported_endpoint: the model is not a callable Marble model.403 media_asset_not_ownedor404 media_asset_not_found: amedia_asset_idinworld_promptbelongs 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 API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
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"
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.
1 <= length <= 255Request Body
application/json
Response
application/json
application/json
application/json
application/json
application/json