Marble World API explained: endpoints, code examples and exports (independent guide)

The Marble World API is the only way to generate World Labs 3D worlds programmatically today, and the platform Atlas is expected to arrive on. This guide, from an independent site not affiliated with World Labs, covers inputs, the request flow, model choice, exports, costs and the mistakes people make. The official reference is docs.worldlabs.ai/api; request shapes below are illustrative.

What the World API is

World Labs opened the World API on January 21, 2026. It takes text, a single image, multiple images, a 360° panorama or a video, and returns a navigable 3D world that can be rendered in the browser or exported to other tools (World Labs). The underlying model is Marble; since April 2, 2026 the default is Marble 1.1, with Marble 1.1 Plus available for auto-expanding worlds (Radiance Fields).

Everything you generate is a Gaussian-splat scene: millions of small coloured ellipsoids that render on consumer GPUs and in WebGL. If you have not worked with splats before, drop the sample into the free splat viewer to get a feel for them.

Inputs

All five are listed in the launch post (World Labs). On this site the same inputs map to the image to 3D world, text to 3D world and video to 3D world tools.

Quickstart

1. Create an account on the World Labs developer platform and generate an API key.
2. Buy credits: $1 per 1,250, minimum $5 (pricing).
3. Send a generate request.
4. Poll the returned operation until it completes.
5. Export the world as .spz or .ply and open it.

curl -X POST https://api.worldlabs.ai/marble/v1/worlds:generate \
-H "WLT-Api-Key: $WORLDLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "marble-1.0-draft",
  "world_prompt": {
    "type": "text",
    "text_prompt": "a foggy pine forest at dawn with a wooden footbridge"
  }
}'

# poll the operation id the call returns

curl https://api.worldlabs.ai/marble/v1/operations/$OPERATION_ID \
-H "WLT-Api-Key: $WORLDLABS_API_KEY"

# check remaining credits

curl https://api.worldlabs.ai/marble/v1/credits \
-H "WLT-Api-Key: $WORLDLABS_API_KEY"

import os, time, requests

API = "https://api.worldlabs.ai"
H = {"WLT-Api-Key": os.environ["WORLDLABS_API_KEY"]}

op = requests.post(
f"{API}/marble/v1/worlds:generate",
headers=H,
json={
"model": "marble-1.0-draft",
"world_prompt": {"type": "text", "text_prompt": "a foggy pine forest at dawn"},
},
timeout=30,
).json()

# poll by operation id; back off from 3 s to 15 s

delay = 3
while True:
status = requests.get(
f"{API}/marble/v1/operations/{op['operation_id']}", headers=H, timeout=30
).json()
if status["done"]:
break
time.sleep(delay)
delay = min(delay * 2, 15)

world = status["response"]
print(world["world_id"], world["assets"]["splats"]["spz_urls"]["full_res"])
print(status["cost"]) # itemised: what you were actually charged

const API = 'https://api.worldlabs.ai';
const headers = { 'WLT-Api-Key': process.env.WORLDLABS_API_KEY, 'Content-Type': 'application/json' };

const op = await fetch(API + '/marble/v1/worlds:generate', {
method: 'POST',
headers,
body: JSON.stringify({
model: 'marble-1.0-draft',
world_prompt: { type: 'text', text_prompt: 'a foggy pine forest at dawn' },
}),
signal: AbortSignal.timeout(30_000),
}).then((r) => r.json());

let delay = 3000;
for (;;) {
const status = await fetch(API + '/marble/v1/operations/' + op.operation_id, { headers }).then((r) => r.json());
if (status.done) {
const world = status.response;
console.log(world.world_id, world.assets.splats.spz_urls.full_res, status.cost);
break;
}
await new Promise((r) => setTimeout(r, delay));
delay = Math.min(delay * 2, 15_000);
}

These calls were run against the live API on September 13, 2026. The generate response carries operation_id, done, error, metadata, response and cost — there is no operation_url to follow, so build the poll URL from the id yourself. A longer, step-by-step version is in the TypeScript quickstart.

Models: marble-1.1 vs marble-1.1 Plus

marble-1.1 is the default. The April 2, 2026 release improved image quality, lighting and artefact handling over Marble 1.0 (Radiance Fields, release notes). One world costs 1,500 credits, about $1.20.

marble-1.1 Plus adds “dynamic cubes”: the world can expand outward automatically, up to five additional spatial units in a single pass (Radiance Fields). Each extra cube costs 300 credits on top of the base 1,500. Use it for corridors, streets and anything where one room is not enough.

Pick 1.1 by default and switch to Plus only when the bounded world is visibly too small. Above the base price there are two documented cost levers: extra dynamic cubes at 300 credits each, and HQ mesh export at 3,500 credits, about $2.80 (World Labs docs). PLY splat export stays free.

Exports

The API exports Gaussian splats in .spz and .ply and a mesh as GLB (World Labs docs). PLY splat export is free; a high-quality mesh export costs 3,500 credits, about $2.80 (pricing). The API does not export video — recording a fly-through is a feature of the Marble web app, not the World API.

• .ply is the lossless source. Large, but every tool reads it.
• .spz is the compressed format, roughly ten times smaller per Niantic (spz), and the one to host on a CDN.
• Mesh is for engines and DCC tools that do not support splats yet; expect a loss of the soft, view-dependent look. One paid export run returns both a textured and a vertex-coloured GLB, and a world is only charged once for it. A free lower-poly collider mesh also ships with every world.
• Video is a rendered fly-through, useful for previews and social posts — but it comes from the Marble web app’s recording feature, not from an API export call.

Splats render in the browser with Spark, World Labs’ MIT-licensed three.js renderer, which supports .ply, .spz, .splat, .ksplat and .sog (GitHub). That is the library behind the splat viewer on this site. Engine import steps are in the game development guide.

Production architecture

A minimal production setup for the World API has three parts:

1. An enqueue endpoint on your server that validates the user’s input, reserves credits in your own ledger, calls the generate endpoint, and stores the operation identifier with a status of queued.
2. A poller that runs on a schedule or a queue consumer, checks each pending operation with backoff, and on completion downloads the exports and writes them to object storage. Stream the download straight to storage; a .ply can be hundreds of megabytes.
3. A notifier that marks the job done, settles the reserved credits against the actual charge, and emails or pushes the user a link to the viewer.

Keep the World Labs key in the server environment only. Serve the .spz to browsers from your own storage or CDN with long cache headers, and render it with Spark. This site’s generator keeps the key on the server the same way, which is why its front end does not need to know whether Marble or, later, Atlas produced the world.

Viewing results

Open any exported .spz or .ply directly in the online splat viewer: files load locally in the browser and are never uploaded. For engines, import the splat with a Gaussian splatting plugin or use the mesh export; the game development guide walks through Unity, Unreal and Blender.

Costs

As of September 13, 2026: $1 buys 1,250 credits, the minimum top-up is $5, a marble-1.1 world is 1,500 credits, a draft world is 150, each Plus cube is 300, an HQ mesh export is 3,500, API credits do not expire, and PLY export is free (World Labs docs, Radiance Fields). Worked budgets are on the pricing page.

Common errors and tips

• 401 Unauthorized. The key is missing, revoked, or sent in the wrong header. The API reads WLT-Api-Key; an Authorization: Bearer header is ignored and the response is {"message": "No API key found in request"}. Keys live on the server only; never embed them in a client.
• 402 or an insufficient-credits error. Check the credits endpoint before generating and keep auto-refill on for production.
• Blocking on generation. Web requests that wait for a multi-minute operation time out at the edge. Enqueue, poll from a worker, notify.
• Poor multi-image results. Photos that do not overlap, or that include mirrors and moving people, confuse reconstruction. Shoot a slow arc with plenty of overlap.
• Huge downloads. Prefer .spz for anything served to browsers; keep .ply as an archive.
• Timeouts and 5xx. Retry with exponential backoff, three attempts, and a per-request timeout.

What changes with Atlas

Atlas, announced September 1, 2026, builds on Marble and is expected to reach developers on the same platform, but has no public API today (Atlas World Model API). The inputs you prepare for Marble, especially overlapping photos and panoramas, are the same inputs Atlas reconstructs from, so nothing you build here is wasted. See Atlas vs Marble for the full comparison, and follow the changelog or its RSS feed to hear when the Atlas endpoint opens.