API Overview

The Splat3D API lets you create 3D Gaussian Splat scenes programmatically. All endpoint documentation on this tab is auto-generated from the OpenAPI specification.

Base URL

https://api.splat-3d.com

All endpoints are prefixed with /v1/.

Authentication

Every request requires a Bearer token in the Authorization header:

Authorization: Bearer s3d_your_key_here

See Authentication for details on creating and managing API keys.

Request format

Request bodies must be JSON sent with Content-Type: application/json (curl -d sends form encoding unless you add that header), and create, /process and /retrain answer a body of any other type with 415 invalid_input, before anything is created or charged. The body of /process and /retrain is optional: none, or an empty one, means {}.

Response format

Success responses

All successful responses use the same envelope:

{
  "data": { ... },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

List endpoints include pagination metadata:

{
  "data": [ ... ],
  "meta": {
    "request_id": "...",
    "next_cursor": "MjAyNi0wNC0xM1QxMjowMDowMC4xMjM0NTYrMDA6MDA",
    "has_more": true,
    "count": 50
  }
}

Error responses

Errors use a consistent structure:

{
  "error": {
    "code": "invalid_input",
    "message": "iterations: Number must be less than or equal to 50000"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

A request that fails the endpoint’s schema also lists each problem in details, one {field, message} per field:

{
  "error": {
    "code": "invalid_input",
    "message": "preset: Invalid enum value. Expected 'fast' | 'standard' | 'quality' | 'ultra' | 'custom', received 'nope'",
    "details": [
      {
        "field": "preset",
        "message": "Invalid enum value. Expected 'fast' | 'standard' | 'quality' | 'ultra' | 'custom', received 'nope'"
      }
    ]
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

meta can hold more than request_id: a 429 names its limit there (see the error codes below). Treat a code you don’t recognize by its HTTP status; new codes may be added.

Request IDs

Every response includes a unique request_id in the meta object and as an X-Request-Id header. Include this ID when contacting support about a specific request.

Retrying scene processing

POST /v1/scenes/{id}/process reserves at most one API launch for a scene. Repeat the same body to replay its saved result without another credit deduction, processing-quota increment, or GPU dispatch. You can supply an Idempotency-Key of 1–128 printable ASCII characters without spaces. If supplied, send the same key on every retry. Keys belong to the user, so changing API keys does not create another launch. A different body or key for an already reserved scene returns 409 conflict. Reusing a key on another scene also returns 409. Without a key, the scene ID and effective request body identify the launch. The meta.request_id remains unique to each HTTP request. A successful response means the launch was accepted. If Modal times out or returns an uncertain error, the reservation stays in place and retries replay acceptance. Poll GET /v1/scenes/{id} for the authoritative outcome; do not create another scene to retry an uncertain launch. The webhook and scheduled reconciler resolve the original job. A worker interruption before dispatch can leave a reservation pending until reconciliation fails and refunds it. Configuration, source-file, and signing failures before reservation do not charge credits. Definite dispatch rejection or capture-data storage failure records a failed result and refunds the captured charge once. Repeating that request returns the saved failure; it does not start a new attempt. Successful acceptance is also replayed after the scene finishes, so use GET to inspect its current status. These guarantees apply to the public /process route. Scene creation and /retrain are not retry-safe yet: /retrain creates a new scene on each request. Do not automatically retry those endpoints or submit the same scene simultaneously through the dashboard and API.

Error codes

HTTP Status	Code	Description
`400`	`invalid_input`	A path, query, header or body value failed validation, a create, `PATCH`, `/process` or `/retrain` body has a key the endpoint doesn’t take, or a JSON body doesn’t parse. The message describes which field and why; a schema failure also lists each problem in `details` as `{field, message}`, e.g. `{"field": "presets", "message": "unrecognized key"}`. Includes any Pydantic 422 errors translated from the Modal backend (`translatePydantic422` in `api/src/lib/scenes.ts`).
`400`	`source_missing`	`POST /v1/scenes/{id}/process` only: the scene’s source file isn’t in storage, e.g. the upload never finished. Nothing was charged. Upload it again (the upload URL from create lasts 24 hours; after that, create a new scene), then call `/process` again.
`401`	`unauthorized`	Missing or invalid API key.
`402`	`insufficient_credits`	You don’t have enough credits to process this scene at the requested quality tier (`processScene` in `api/src/lib/scenes.ts`).
`403`	`forbidden`	No endpoint sends it now. A scene another account owns answers `404`, as an unknown id does.
`403`	`insufficient_scope`	The API key’s scopes don’t cover the endpoint, e.g. a Read key on create, `PATCH`, `DELETE`, `/process`, `/retrain` or `/cancel`. The message names the scope needed. Nothing was read, changed or charged.
`404`	`not_found`	The requested scene or resource doesn’t exist, was deleted, or belongs to another account. These are not told apart.
`409`	`conflict`	The scene is in a state that doesn’t allow this action (e.g., already processing), or on `DELETE` it changed while being deleted. Try again.
`409`	`retry_blocked`	`/retrain` only: the scene failed in a way a retry repeats (too few usable images, too few frames matched, or a crash in training on this file). No credits were charged. Upload a new capture, or for the last two, retrain at a different tier. A scene whose `sfm` or `training` values differ from its tier’s defaults is never refused for the last two, since a retrain resets them. Values with no tier default, such as `training.strategy` or `sfm.options`, carry over to the retrain and don’t count.
`413`	`payload_too_large`	Uploaded file exceeds the 5 GB upload cap, the same on every plan. `/process` and `/retrain` refuse it before charging credits.
`422`	`source_unusable`	`/process` and `/retrain`: the uploaded file can’t be reconstructed. It is empty, a video under 30 seconds (read from its MP4 or MOV header; a length that can’t be read launches), a photo upload that isn’t a zip, or a zip with fewer than 5 JPEG or PNG photos and not exactly one `wide.mov` (HEIC, WebP and other formats are skipped; the message names them). `details` holds the rule, e.g. `{"field": "photo_count", "value": 3, "allowed": {"min": 5}}` or `{"field": "video_seconds", "value": 12.4, "allowed": {"min": 30}}`. Nothing was charged. After `/process` the scene stays `uploading`: upload a usable file to the same upload URL (it lasts 24 hours from create) and call `/process` again, or create a new scene. `/retrain` creates no new version.
`429`	`quota_exceeded` / `queue_full` / `rate_limited`	Either a monthly quota was hit (`quota_exceeded`), or, at `/process` and `/retrain`, as many of your scenes are processing as your plan allows (`queue_full`, with `Retry-After: 120`; nothing was charged), or you sent more requests this minute than the rate limit allows (`rate_limited`, with `Retry-After: 60`; nothing was done). All put `limit` in `meta`. The `code` field disambiguates.
`500`	`internal_error`	Something went wrong on our end. Retry or contact support with the request ID.
`502`	`upstream_error`	`/process` and `/retrain`: the GPU backend refused the launch, or the capture data could not be stored. The charge was refunded. Repeating the same `/process` request returns this saved failure.
`503`	`service_unavailable`	Temporary failure on our side, e.g. a database blip. It is not an answer about your key or scene. Reads, `DELETE` and `/process` carry `Retry-After`: repeat the same request after that many seconds. Create, `PATCH`, `/retrain` and `/cancel` carry none, because a repeated create or `/retrain` makes another scene: check `GET /v1/scenes` before sending them again.

Pagination

List endpoints use cursor-based pagination:

Parameter	Type	Default	Description
`cursor`	`string`	—	`meta.next_cursor` from the previous page
`limit`	`integer`	`50`	Items per page (1-100)

The cursor is opaque: pass it back unchanged. It is URL-safe, so it needs no encoding. A cursor the API can’t read answers 400 invalid_input. Scenes come newest first, and each list item has the shape GET /v1/scenes/{id} returns.

# First page
curl https://api.splat-3d.com/v1/scenes?limit=20 \
  -H "Authorization: Bearer $SPLAT3D_API_KEY"

# Next page (next_cursor from the previous response)
curl "https://api.splat-3d.com/v1/scenes?limit=20&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SPLAT3D_API_KEY"

Endpoints summary

Method	Endpoint	Description
`POST`	`/v1/scenes`	Create a scene and get a presigned upload URL. Supported inputs lists the `content_type` for each input
`GET`	`/v1/scenes`	List your scenes (paginated)
`GET`	`/v1/scenes/{id}`	Get scene status, metrics and URLs
`PATCH`	`/v1/scenes/{id}`	Update scene metadata (title, address, visibility)
`DELETE`	`/v1/scenes/{id}`	Delete a scene. Every call answers `404` for it at once; a daily cleanup removes its files 24 to 48 hours later. An unfinished scene is cancelled first, under the cancel refund rules
`POST`	`/v1/scenes/{id}/process`	Start the reconstruction pipeline
`POST`	`/v1/scenes/{id}/retrain`	Process a scene’s source again as a new scene, at the tier `quality_tier` or `preset` names. The source scene is left as it is
`POST`	`/v1/scenes/{id}/cancel`	Cancel a running job
`GET`	`/v1/scenes/{id}/download`	Download the 3D model: SPZ by default, otherwise SOG, then PLY. SOG or PLY on request, or SPZ (`404` if the scene has none)
`GET`	`/v1/scenes/{id}/thumbnail`	Get the scene thumbnail image. A public scene’s needs no key. A private scene’s goes to its owner’s key only: anyone else gets `404`
`GET`	`/v1/usage`	Return usage and quota summary for the current billing period

Create answers scene_id and upload_url, /process answers scene_id, and /retrain answers the new scene as scene_id and the scene it came from as source_scene_id. Each also carries id, the same as scene_id. Create and /process still send the older sceneId and uploadUrl, which are deprecated: read the snake_case keys. A /retrain refused before any charge keeps no new scene; after a 502 the new scene stays, failed and refunded.

Processing lifecycle

A scene moves through these statuses: While processing, status reflects the current pipeline stage. (Some older scenes report running_sfm, a legacy alias of estimating_poses, or one of the retired preview stages preview_extracting, preview_generating and preview_compressing.) A launch reports extracting_frames first, at 0% while it waits for a GPU, which can take minutes. At any point before complete, you can cancel processing. A cancel before the job starts, or within 10 seconds after, refunds the scene’s credits. The job starts around when /process returns. A later cancel keeps the processing charge; only an AI Enhance charge reserved at upload comes back. The cancel response says what came back, in refunded and refunded_credits. If something goes wrong, the status becomes failed with an error message and the scene’s credits are refunded automatically. The server fails and refunds a stuck job itself: one still queued after 90 minutes, or still processing after 150 (checked every 10 minutes). You will always reach a terminal status (complete, failed, or cancelled) without intervention.

Tracking progress

Poll GET /v1/scenes/{id} to track progress. The response is a flat SceneDetail object (sceneDetailSchema in api/src/routes/schemas.ts) regardless of state — SDKs can decode it with a single type. The list and PATCH return the same object. Key fields:

Field	Type	When populated
`status`	`string`	Always, the stored status, the same on every call (`uploading`, `extracting_frames`, `estimating_poses`, `training`, `exporting`, `compressing`, `complete`, `failed`, `cancelled`; older scenes may show `running_sfm` or a retired `preview_*` stage)
`processing_stage`	`string \| null`	While processing — the stage the job reports live, which can be ahead of `status`. `null` otherwise, including once `complete`
`processing_pct`	`number \| null`	While processing — 0-100 progress. `null` otherwise, including once `complete`
`processing_error`	`string \| null`	On `failed` or `cancelled`
`preset`	`string \| null`	From creation on: `fast`, `standard`, `quality`, `ultra` or `custom`. `null` when the scene’s stored parameters name none
`processing_started_at`	`string \| null`	Once processing is launched
`processing_completed_at`	`string \| null`	On `complete`
`training_time_seconds`	`number \| null`	Set on `complete`, kept if the scene later fails: the GPU training stage alone. The whole job runs from `processing_started_at` to `processing_completed_at`
`spz_size_bytes`, `sog_size_bytes`, `ply_size_bytes`	`number \| null`	On `complete`, each when the scene has that file
`num_gaussians`	`number \| null`	On `complete`
`psnr`	`number \| null`	Set on `complete`, kept if the scene later fails: mean PSNR over the training images, so usually higher than `psnr_holdout`
`psnr_holdout`	`number \| null`	On `complete` if images were held out (`output.holdout_ratio` above 0; every preset but `fast` by default)
`ssim_holdout`	`number \| null`	On `complete` if images were held out, as `psnr_holdout`
`viewer_url`, `download_url`, `format`	`string \| null`	On `complete`. `download_url` is `/download` without `format`, so it sends the file `format` names, and only to your API key. The response’s `X-Splat-Format` header decides: when that file is missing from storage, the next one is sent
`thumbnail_url`	`string \| null`	Once the scene has a thumbnail. A private scene’s needs your API key
`created_at`, `updated_at`	`string`	Always, UTC with milliseconds, e.g. `2026-04-13T12:00:00.000Z`

Poll at 5–10 second intervals and stop once status reaches complete, failed, or cancelled. A 503 while polling is transient: keep polling after its Retry-After.

Webhooks

Create a scene with a webhook_url (https:// only) to get a POST when it finishes: scene.completed or scene.failed, whose pages list every field. A cancel sends nothing, nor does a retrain’s new version or a launch that /process answers with an error. Answer any 2xx; anything else is retried, 3 attempts in all. Redirects are followed, and a 301, 302 or 303 arrives as a GET without the body, so register the final URL. Add a webhook_secret and each request carries X-Splat-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> keyed with your secret. Check it against the body bytes as received:

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300; // refuse replays of old requests

function verifySignature(header, rawBody, secret) {
  if (!header) {
    return false;
  }

  const { t, v1 = "" } = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
  const received = Buffer.from(v1);
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= TOLERANCE_SECONDS;

  // Compare bytes: timingSafeEqual throws on buffers of different lengths.
  return fresh && received.length === expected.length && timingSafeEqual(received, expected);
}

​API Overview

​Base URL

​Authentication

​Request format

​Response format

​Success responses

​Error responses

​Request IDs

​Retrying scene processing

​Error codes

​Pagination

​Endpoints summary

​Processing lifecycle

​Tracking progress

​Webhooks