# AI3D API v2 model: worldlabs2-images-to-splat

Reconstruct an SPZ Gaussian-splat scene from posed images and returned depth.

Working world-building tutorial: https://api.ai3d.dev/v2/demos/chisel
Compare a room and an extended fit, inspect the reused RGBD and rejected depth,
and download the actual SPZ artifacts. The repository's world_demo.mjs CLI
prepares the layout and saves each explicit generation/reconstruction stage.
New reconstruction requires an eligible AI3D operator key.

- Provider: worldlabs2 (World Labs Atlas / Marble beta).
- Provider task: posedImages2Splats.
- Operator keys only during beta; customer keys and mobile tokens cannot submit.
- AI3D defaults to refine: false and always sends that value explicitly.
- World Labs currently lists 500 credits ($0.50) for a successful draft and
  5,000 credits ($5) for a successful refined run. These are provider prices,
  not AI3D customer quotes. Upstream image/depth generation is additional.

POST https://api.ai3d.dev/v2/jobs with an operator bearer key and a stable
Idempotency-Key. Set model to worldlabs2-images-to-splat and input to:

{
  "posedFrames": [
    {"imageAsset":{"assetId":"asset_image_1"},"camera":{"extrinsics":{"position":[0,1.45,0.8],"quaternion":[0,0,0,1],"coordinateSystem":"rub"},"intrinsics":{"fx":900,"fy":900,"cx":640,"cy":360,"width":1280,"height":720}},"depth":{"depthAsset":{"assetId":"asset_depth_1"}}},
    {"imageAsset":{"assetId":"asset_image_2"},"camera":{"extrinsics":{"position":[0.4,1.45,0.8],"quaternion":[0,0,0,1],"coordinateSystem":"rub"},"intrinsics":{"fx":900,"fy":900,"cx":640,"cy":360,"width":1280,"height":720}},"depth":{"depthAsset":{"assetId":"asset_depth_2"}}}
  ],
  "refine": false,
  "enhancePrompt": false,
  "prompt": "A quiet kitchen with warm oak furniture and late-afternoon daylight"
}

At least two frames are required; this integration accepts up to 32. Each
image, camera and linear EXR depth must describe the same view, with all frames
sharing one image size and coordinate frame. Keep returned cameras and depth
together. Use public HTTPS URLs or provider asset IDs from the same project.
The input blockout depth is layout guidance; reconstruct from returned output
depth rather than treating the blockout as the generated scene's geometry.

Optional `regionOfInterest` focuses the reconstruction on one oriented box, or on a list of up to 16. Each box is
{"frame": {"position": [x, y, z], "quaternion": [x, y, z, w], "coordinateSystem": "rub"}, "halfExtents": [hx, hy, hz]},
with half-extents in metres. A box should enclose the geometry of interest and the space it is viewed from; the rest of
the scene is still reconstructed from the frames. A failed job's `error` names World Labs' stable reason when it gives
one, for example `Atlas beta task failed: EXECUTION_FAILED`.

For a room, World Labs recommends 8–16 overlapping, well-distributed views.
Cover the floor, walls, occlusions and the area to explore. Inspect consistency
before reconstruction: contradictory furniture creates ghosted geometry.

Poll the normal AI3D job endpoint. A successful draft returns draftSplat;
refinement returns refinedSplats keyed by splat count. Both are archived as
SPZ artifacts alongside durable atlas-response.json metadata. Public jobs can
be explored at https://api.ai3d.dev/viewer/JOB_ID?walk=on. On keys eligible for
hosted publication, publish: true requests permanent hosted output. Pass a resulting SPZ asset to
worldlabs2-splat-to-mesh for GLB extraction when needed.

To extend a scene, keep the accepted RGBD frames and generate additional,
overlapping views in the same coordinate frame using Chisel or Atlas. Submit
the original and additional frames together for a new reconstruction. This
is a new splat fit, not an in-place edit of the old SPZ. Reused inputs do not
guarantee unchanged geometry in the fitted overlap.

References:
- https://docs.atlas-beta.worldlabs.ai/posed-images-to-splats
- https://docs.atlas-beta.worldlabs.ai/splat-best-practices
- https://docs.atlas-beta.worldlabs.ai/api-reference/posed-images2-splats