Marble World API guide: endpoints, code examples and exports

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.

# illustrative request shape; verify at docs.worldlabs.ai/api
curl -X POST https://api.worldlabs.ai/marble/v1/worlds:generate \
-H "Authorization: Bearer $WORLDLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"marble-1.1","prompt":"a foggy pine forest at dawn with a wooden footbridge"}'

# check remaining credits
curl https://api.worldlabs.ai/marble/v1/credits \
-H "Authorization: Bearer $WORLDLABS_API_KEY"

import os, time, requests

API = "https://api.worldlabs.ai"  # illustrative; use the base URL from your dashboard
H = {"Authorization": f"Bearer {os.environ['WORLDLABS_API_KEY']}"}

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

# poll the operation the response points to; back off from 3 s to 15 s
delay = 3
while True:
  status = requests.get(op["operation_url"], headers=H, timeout=30).json()
  if status.get("done"):
      break
  time.sleep(delay)
  delay = min(delay * 2, 15)
print(status)  # contains the world id and export links

const API = 'https://api.worldlabs.ai'; // illustrative; use the base URL from your dashboard
const headers = { Authorization: 'Bearer ' + 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.1', prompt: 'a foggy pine forest at dawn' }),
signal: AbortSignal.timeout(30_000),
}).then((r) => r.json());

let delay = 3000;
for (;;) {
const status = await fetch(op.operation_url, { headers }).then((r) => r.json());
if (status.done) { console.log(status); break; }
await new Promise((r) => setTimeout(r, delay));
delay = Math.min(delay * 2, 15_000);
}

The operation URL field name and the completion flag are placeholders for whatever the official response uses; the control flow is what matters. 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; the cubes are the only cost lever above the base price.

Exports

Marble worlds export as Gaussian splats in .spz and .ply, as a mesh, and as a video, and PLY splat export through the API is free (Radiance Fields).

• .ply is the lossless source. Large, but every tool reads it.
• .spz is the compressed format, roughly ten times smaller, 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.
• Video is a rendered fly-through, useful for previews and social posts.

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 is the architecture behind this site’s generator, and it is why the front end never needs 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 3, 2026: $1 buys 1,250 credits, the minimum top-up is $5, a marble-1.1 world is 1,500 credits, each Plus cube is 300 credits, 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 without the Bearer prefix. 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 join the waitlist below to hear when the Atlas endpoint opens.