Exports
Every finished world comes with its main file at a fixed download endpoint. Other formats, such as collision meshes, a floorplan render or a zip of everything, are built when you ask for them with POST /v1/worlds/requests/{request_id}/exports/{type}. Exports don't cost credits.
Endpoints
| Endpoint | Scope | Purpose |
|---|---|---|
POST /v1/worlds/requests/{request_id}/exports/{type} | worlds:write | Start an export, or return it when it is ready. |
GET /v1/worlds/requests/{request_id}/exports/{type} | worlds:read | Check an export. Add ?download=1 to download it, or ?download=1&variant=raw for the raw floorplan render. |
GET /v1/worlds/requests/{request_id}/exports | worlds:read | List the mesh, mesh-simplified and floorplan exports of a world. |
GET /v1/worlds/requests/{request_id}/splat | worlds:read | Download the splat. |
GET /v1/worlds/requests/{request_id}/panorama | worlds:read | Download the panorama. |
GET /v1/worlds/requests/{request_id}/cameras | worlds:read | Download the reconstructed cameras of a capture. |
GET /v1/worlds/requests/{request_id}/mesh | worlds:read | Download the GLB of a textured mesh world. |
Download endpoints redirect (302) to a signed URL that works for about 5 minutes. Store the API URL, not the signed one, and call it again when you need the file.
Exports by model
| File | Where to get it | Echo 2 | Echo HQ | Echo 3 | Textured mesh models |
|---|---|---|---|---|---|
Splat (spz, sog, ply) | /splat, zip | Yes | Yes | Yes | No |
| Panorama | /panorama | Yes | Yes | No | No |
Collision mesh (mesh, mesh-simplified) | Export | Yes | Yes | Yes | No |
| Floorplan | Export, zip | Yes | Yes | Yes, built automatically | No |
| Reconstructed cameras | /cameras, zip | No | No | Yes | No |
| Textured mesh GLB | /mesh, zip | No | No | No | Yes |
| Zip | Export | Yes | Yes | Yes | Yes, GLBs only |
Textured mesh models are private models that some accounts have.
Splat
Set output_format to spz (default), sog or ply when you create the world. GET /splat returns that format, and the zip export bundles all three.
| Format | Use it for |
|---|---|
spz | Smallest file. Read it with Niantic's spz library or any SPZ viewer. |
sog | PlayCanvas and SuperSplat. |
ply | Tools that read the standard 3D Gaussian splatting PLY layout. |
Collision mesh
mesh and mesh-simplified are triangle meshes in PLY format, built from the splat for physics, collision and navigation. They are not textured models. mesh-simplified is the same surface with far fewer faces. Requesting either one builds both, so the second is ready at the same time.
Floorplan
floorplan is a top-down PNG render of the splat. It shows the layout, but it is not a measured plan. Echo 3 worlds start building it as soon as they finish, so check its status before you request it. For other worlds, POST …/exports/floorplan starts the render.
A READY floorplan export carries a floorplan object that maps the image's pixels to world coordinates. A zip that includes the floorplan carries the same object in its status and webhook, and bundles it as floorplan.json.
Some older floorplans were saved without a coordinate frame. They report NOT_REQUESTED, and requesting the export renders a new one.
Floorplan to world coordinates
World coordinates are meters with +Y up, the frame of the Spaitial viewer. splat.spz stores OpenCV coordinates (+X right, +Y down, +Z forward), which readers such as Niantic's spz library give you with default options. World coordinates are those with Y and Z negated: world = (x, -y, -z), the same 180° turn about X the reconstructed cameras use for a Y-up viewer. splat.ply and splat.sog are converted from splat.spz and are usually Y-up already, but files converted long ago keep the SPZ frame. If a file's bounds match scene_bounds only after negating Y and Z, treat it like splat.spz.
The floorplan looks straight down, so each pixel is a point on the floor plane, at world X and Z. Pixel coordinates start at the top-left corner of the image, and pixel centres sit at +0.5.
{
"type": "floorplan",
"status": "READY",
"download_url": "https://api.spaitial.ai/v1/worlds/requests/req_abc123/exports/floorplan?download=1",
"floorplan": {
"version": 1,
"coordinate_system": "spaitial-world-v1",
"projection": "orthographic-top-down",
"origin_xz": [0.4, -1.1],
"image_x_axis_xz": [1, 0],
"image_y_axis_xz": [0, 1],
"extent_m": [12.096, 12.096],
"cut_height_y": 1.244,
"scene_bounds": { "min": [-5.2, -0.1, -6.4], "max": [6.0, 3.1, 4.2] },
"image": {
"width_px": 1024,
"height_px": 1024,
"meters_per_pixel": [0.0118125, 0.0118125],
"world_xz_from_pixel": [[0.0118125, 0, -5.648], [0, 0.0118125, -7.148], [0, 0, 1]],
"pixel_from_world_xz": [[84.6561, 0, 478.1376], [0, 84.6561, 605.1217], [0, 0, 1]],
"download_url": "https://api.spaitial.ai/v1/worlds/requests/req_abc123/exports/floorplan?download=1"
},
"raw_image": {
"width_px": 1024,
"height_px": 1024,
"meters_per_pixel": [0.0118125, 0.0118125],
"world_xz_from_pixel": [[0.0118125, 0, -5.648], [0, 0.0118125, -7.148], [0, 0, 1]],
"pixel_from_world_xz": [[84.6561, 0, 478.1376], [0, 84.6561, 605.1217], [0, 0, 1]],
"download_url": "https://api.spaitial.ai/v1/worlds/requests/req_abc123/exports/floorplan?download=1&variant=raw"
},
"generated_at": "2026-11-18T09:12:00.000Z"
}
}
| Field | Meaning |
|---|---|
origin_xz | World X and Z at the centre of the image. |
image_x_axis_xz, image_y_axis_xz | World directions of image right and image down. |
extent_m | World meters covered by the full image width and height. |
cut_height_y | World Y of the roof cut. Splats above it are not drawn. null if unknown. |
scene_bounds | World bounding box of the scene. |
image | The floorplan PNG: its size, meters per pixel and transforms. |
raw_image | The render before cleanup, or null if the world didn't keep one. |
world_xz_from_pixel and pixel_from_world_xz are 2D affine transforms written as 3×3 row-major matrices, so [x, z, 1] = world_xz_from_pixel · [px, py, 1]. To place a world point on the image:
const [[a, b, tx], [c, d, tz]] = floorplan.image.pixel_from_world_xz;
const px = a * x + b * z + tx;
const py = c * x + d * z + tz;
The PNG you download is cleaned up by an image model so it reads as a floor plan. It keeps the layout, but small details can move by a few pixels. When you need exact positions, use raw_image and download it with GET …/exports/floorplan?download=1&variant=raw.
In a zip, floorplan.json names the files instead of linking them ("file": "floorplan.png", "file": "floorplan.raw.png"). It describes the images in that zip, so use it rather than the live export if the floorplan has been rendered again since.
Zip
A zip export bundles files under fixed names, plus a manifest.json. Without a body it includes every asset the world has. To pick a subset, send include:
curl -sX POST "https://api.spaitial.ai/v1/worlds/requests/$REQUEST_ID/exports/zip" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "include": ["spz", "floorplan"] }'
| Asset | Entry in the zip | Available for |
|---|---|---|
spz | splat.spz | Splat worlds |
sog | splat.sog | Splat worlds |
ply | splat.ply | Splat worlds |
mesh | mesh.ply | Splat worlds |
floorplan | floorplan.png, floorplan.json and, when the world kept it, floorplan.raw.png (coordinates) | Splat worlds |
cameras | cameras.json | Echo 3 worlds with reconstructed cameras |
glb | textured_mesh.glb | Textured mesh worlds |
glb-uncompressed | textured_mesh_uncompressed.glb | Textured mesh worlds that delivered a plain GLB |
Each zip is identified by its set of assets. Asking again for the same set returns the finished zip (200), and a new set starts a new build (202). Files the world doesn't have yet, such as a mesh nobody requested, are built first, so a full zip can take several minutes. To check a subset, pass the same set as ?include=spz,floorplan on GET …/exports/zip.
Textured mesh worlds
Worlds from a textured mesh model deliver GLB files instead of a splat. Download them with GET /mesh?variant=meshopt (default, compressed with EXT_meshopt_compression) or GET /mesh?variant=uncompressed (plain glTF 2.0 for DCC tools and game engines). Their only export is a zip of glb and glb-uncompressed. The splat, mesh, mesh-simplified and floorplan exports need a splat, so they answer 409 UNSUPPORTED_FOR_OUTPUT_TYPE.
Start an export and download it
Request the export. A 202 means it is building:
curl -sX POST "https://api.spaitial.ai/v1/worlds/requests/$REQUEST_ID/exports/mesh" \
-H "Authorization: Bearer $API_KEY"
{ "type": "mesh", "status": "PROCESSING" }
Poll its status until it is READY:
curl -s "https://api.spaitial.ai/v1/worlds/requests/$REQUEST_ID/exports/mesh" \
-H "Authorization: Bearer $API_KEY"
{
"type": "mesh",
"status": "READY",
"download_url": "https://api.spaitial.ai/v1/worlds/requests/req_abc123/exports/mesh?download=1",
"created_at": "2026-11-19T09:00:00Z",
"updated_at": "2026-11-19T09:00:00Z"
}
Then follow download_url:
curl -sL "https://api.spaitial.ai/v1/worlds/requests/$REQUEST_ID/exports/mesh?download=1" \
-H "Authorization: Bearer $API_KEY" -o mesh.ply
status is one of NOT_REQUESTED, PROCESSING, READY or FAILED. If the world was created with a webhook, you also get a world.export.completed or world.export.failed event when the export finishes. See Webhooks for the payload.
Errors
| HTTP | error.code | When it happens |
|---|---|---|
400 | INVALID_INPUT | Unknown export type, zip asset name or variant. Only the floorplan has a variant, raw. |
404 | REQUEST_NOT_FOUND | The request doesn't exist or belongs to another account. |
404 | CAMERAS_NOT_AVAILABLE | /cameras on a world that has no reconstructed cameras. |
409 | RESOURCE_NOT_READY | The world hasn't finished, a download isn't ready yet, or variant=raw on a floorplan that kept no raw render. |
409 | UNSUPPORTED_FOR_OUTPUT_TYPE | The world has no such file, for example mesh on a textured mesh world or cameras in a zip for a world without them. |
See Errors for the error format.