Skip to main content
POST
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

string
default:"marble-1.0"
Choose a currently available Marble model using the Models API.
string
Text prompt for text-only generation or as guidance with image/video inputs.
object
Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video.
string
Base64 or data URL image prompt.
string
Image URL prompt.
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.
string
Video URL prompt.
boolean | string
For image inputs, set true for an existing panorama, false for a normal single image, or auto.
integer
Optional seed from 0 through 4294967295.
string
Optional display name for the generated world, up to 64 characters.
array
Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
object
Optional visibility and access settings: public, allow_id_access, allowed_readers, and allowed_writers. public: true requests a publicly visible world.

Response

string
Public task ID for polling.
string
Async task identifier alias.
string
World Labs operation ID.
string
Preferred polling URL for this task.
string
Task status: pending, processing, completed, or failed.
string
URL for the generated Marble world when completed.
string
Collider mesh GLB URL when available.
string
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.

Authorizations

Authorization
string
header
required

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

Headers

X-TokenLab-Delivery-Policy
enum<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, upstream acceptance, or persistent resource creation.

Available options:
auto,
verified,
official

Body

application/json
world_prompt
object
required

Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. Content references may use source=media_asset with a media_asset_id prepared by /v1/worlds/media-assets/prepare-upload.

model
enum<string>
default:marble-1.0

Marble model to use. Defaults to marble-1.0 to match the current World Labs compatibility default when model is omitted.

Available options:
marble-1.0,
marble-1.1,
marble-1.1-plus
prompt
string

Text prompt used for text or guided image/video world generation.

display_name
string

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

Maximum string length: 64
image
string

Base64 or data URL image prompt.

image_url
string<uri>

Image URL prompt.

images
(string | object)[]

Shortcut multi-image prompts. Provide up to 4 images. Use native world_prompt.reconstruct_images=true for up to 8 images.

Maximum array length: 4
video_url
string<uri>

Video URL prompt.

is_pano

Whether an image prompt is an existing panorama. Use true for pano input, false for single-image input, or auto.

seed
integer

Optional seed from 0 through 4294967295.

Required range: 0 <= x <= 4294967295
tags
string[]

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

Maximum array length: 10
Maximum string length: 32
permission
object

Optional World Labs permission object.

user
string

End-user identifier.

Response

Task created

id
string
task_id
string
operation_id
string
status
enum<string>
Available options:
pending,
processing,
completed,
failed
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
object