Skip to main content

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​

EndpointScopePurpose
POST /v1/worlds/requests/{request_id}/exports/{type}worlds:writeStart an export, or return it when it is ready.
GET /v1/worlds/requests/{request_id}/exports/{type}worlds:readCheck an export. Add ?download=1 to download it, or ?download=1&variant=raw for the raw floorplan render.
GET /v1/worlds/requests/{request_id}/exportsworlds:readList the mesh, mesh-simplified and floorplan exports of a world.
GET /v1/worlds/requests/{request_id}/splatworlds:readDownload the splat.
GET /v1/worlds/requests/{request_id}/panoramaworlds:readDownload the panorama.
GET /v1/worlds/requests/{request_id}/camerasworlds:readDownload the reconstructed cameras of a capture.
GET /v1/worlds/requests/{request_id}/meshworlds:readDownload 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​

FileWhere to get itEcho 2Echo HQEcho 3Textured mesh models
Splat (spz, sog, ply)/splat, zipYesYesYesNo
Panorama/panoramaYesYesNoNo
Collision mesh (mesh, mesh-simplified)ExportYesYesYesNo
FloorplanExport, zipYesYesYes, built automaticallyNo
Reconstructed cameras/cameras, zipNoNoYesNo
Textured mesh GLB/mesh, zipNoNoNoYes
ZipExportYesYesYesYes, 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.

FormatUse it for
spzSmallest file. Read it with Niantic's spz library or any SPZ viewer.
sogPlayCanvas and SuperSplat.
plyTools 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"
}
}
FieldMeaning
origin_xzWorld X and Z at the centre of the image.
image_x_axis_xz, image_y_axis_xzWorld directions of image right and image down.
extent_mWorld meters covered by the full image width and height.
cut_height_yWorld Y of the roof cut. Splats above it are not drawn. null if unknown.
scene_boundsWorld bounding box of the scene.
imageThe floorplan PNG: its size, meters per pixel and transforms.
raw_imageThe 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"] }'
AssetEntry in the zipAvailable for
spzsplat.spzSplat worlds
sogsplat.sogSplat worlds
plysplat.plySplat worlds
meshmesh.plySplat worlds
floorplanfloorplan.png, floorplan.json and, when the world kept it, floorplan.raw.png (coordinates)Splat worlds
camerascameras.jsonEcho 3 worlds with reconstructed cameras
glbtextured_mesh.glbTextured mesh worlds
glb-uncompressedtextured_mesh_uncompressed.glbTextured 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​

HTTPerror.codeWhen it happens
400INVALID_INPUTUnknown export type, zip asset name or variant. Only the floorplan has a variant, raw.
404REQUEST_NOT_FOUNDThe request doesn't exist or belongs to another account.
404CAMERAS_NOT_AVAILABLE/cameras on a world that has no reconstructed cameras.
409RESOURCE_NOT_READYThe world hasn't finished, a download isn't ready yet, or variant=raw on a floorplan that kept no raw render.
409UNSUPPORTED_FOR_OUTPUT_TYPEThe 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.