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 and a poll_url for status checks.
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 as guidance with image/video inputs.
Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video.
Base64 or data URL image prompt.
Image URL prompt.
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.
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 for polling.
Async task identifier alias.
World Labs operation ID.
Preferred polling URL for this task.
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; a returned cost.total_credits value is generation usage, not a currency amount.
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", "cost": {}, "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"
Request Body
application/json
Response
application/json
application/json
application/json