Quickstart

This guide walks you through creating a 3D scene from a video using the Splat3D API. By the end, you’ll have a shareable 3D Gaussian Splat.

You’ll need an API key. Create one from the Splat3D dashboard under Settings > API Keys.

Set your API key

export SPLAT3D_API_KEY="s3d_your_key_here"

Step 1: Create a scene

Create a scene and get a presigned upload URL. This tells Splat3D what you’re uploading and how you want it processed. Uploading a photo zip, an ARKit capture or a COLMAP model instead? Supported inputs has the content_type and packaging for each.

# Keep the response: the next steps need its sceneId and uploadUrl (parsed with jq).
RESPONSE=$(curl -s -X POST https://api.splat-3d.com/v1/scenes \
  -H "Authorization: Bearer $SPLAT3D_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Scene",
    "content_type": "video/mp4",
    "preset": "standard"
  }')
SCENE_ID=$(echo "$RESPONSE" | jq -r '.data.sceneId')
UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.data.uploadUrl')

import os

import requests

SPLAT3D_API_KEY = os.environ["SPLAT3D_API_KEY"]

response = requests.post(
    "https://api.splat-3d.com/v1/scenes",
    headers={"Authorization": f"Bearer {SPLAT3D_API_KEY}"},
    json={
        "title": "My First Scene",
        "content_type": "video/mp4",
        "preset": "standard",
    },
)
data = response.json()["data"]
scene_id = data["sceneId"]
upload_url = data["uploadUrl"]

const SPLAT3D_API_KEY = process.env.SPLAT3D_API_KEY;

const response = await fetch("https://api.splat-3d.com/v1/scenes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${SPLAT3D_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "My First Scene",
    content_type: "video/mp4",
    preset: "standard",
  }),
});
const { data } = await response.json();
const { sceneId, uploadUrl } = data;

Response:

{
  "data": {
    "sceneId": "a1b2c3d4e5f6",
    "uploadUrl": "https://..."
  },
  "meta": {
    "request_id": "..."
  }
}

Step 2: Upload your video

Upload your video file directly to the presigned URL. The PUT goes straight to cloud storage and bypasses the API entirely.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @walkthrough.mp4

Upload size cap. Uploads are capped at 5 GB on every plan, and the upload URL lasts 24 hours. The size is checked authoritatively at POST /v1/scenes/{id}/process against the actual bytes in R2 — exceeding the cap returns 413 payload_too_large before any credits are charged. See Upload limits.

Record at least 30 seconds: /process refuses a shorter video with 422 source_unusable, before charging. For best results, record a slow, steady walkthrough. Avoid fast movements and ensure good lighting. 30-60 seconds of footage typically produces great results.

Step 3: Start processing

Once the upload completes, kick off the reconstruction pipeline.

curl -X POST https://api.splat-3d.com/v1/scenes/$SCENE_ID/process \
  -H "Authorization: Bearer $SPLAT3D_API_KEY"

requests.post(
    f"https://api.splat-3d.com/v1/scenes/{scene_id}/process",
    headers={"Authorization": f"Bearer {SPLAT3D_API_KEY}"},
)

await fetch(`https://api.splat-3d.com/v1/scenes/${sceneId}/process`, {
  method: "POST",
  headers: { Authorization: `Bearer ${SPLAT3D_API_KEY}` },
});

Step 4: Poll for completion

The pipeline takes about 8 minutes on fast, 15 on standard, 25 on quality and 45 on ultra (see Quality Presets). Poll the scene status until it’s complete.

curl https://api.splat-3d.com/v1/scenes/$SCENE_ID \
  -H "Authorization: Bearer $SPLAT3D_API_KEY"

import time

while True:
    response = requests.get(
        f"https://api.splat-3d.com/v1/scenes/{scene_id}",
        headers={"Authorization": f"Bearer {SPLAT3D_API_KEY}"},
    )
    data = response.json()["data"]
    pct = data["processing_pct"]  # null unless processing
    print(f"Status: {data['status']}" + (f" ({pct}%)" if pct is not None else ""))

    if data["status"] == "complete":
        break
    elif data["status"] in ("failed", "cancelled"):
        print("Processing failed:", data.get("processing_error"))
        break

    time.sleep(15)

const poll = async () => {
  while (true) {
    const res = await fetch(
      `https://api.splat-3d.com/v1/scenes/${sceneId}`,
      { headers: { Authorization: `Bearer ${SPLAT3D_API_KEY}` } }
    );
    const { data } = await res.json();
    const pct = data.processing_pct; // null unless processing
    console.log(`Status: ${data.status}${pct === null ? "" : ` (${pct}%)`}`);

    if (data.status === "complete") return data;
    if (data.status === "failed" || data.status === "cancelled") {
      throw new Error(data.processing_error ?? "Scene did not complete");
    }

    await new Promise((r) => setTimeout(r, 15000));
  }
};

The response shape is a flat SceneDetail object — the same fields are always present, just with different values depending on state (sceneDetailSchema in api/src/routes/schemas.ts). status is the stored status, the same on every call; processing_stage and processing_pct are null unless the scene is processing. Processing response (while running):

{
  "data": {
    "id": "a1b2c3d4e5f6",
    "status": "training",
    "processing_stage": "training",
    "processing_pct": 65,
    "processing_error": null,
    "num_gaussians": null,
    "viewer_url": null,
    "download_url": null,
    "format": null
  },
  "meta": { "request_id": "..." }
}

Completed response:

{
  "data": {
    "id": "a1b2c3d4e5f6",
    "status": "complete",
    "processing_stage": null,
    "processing_pct": null,
    "processing_error": null,
    "num_gaussians": 1940000,
    "ssim": 0.91,
    "psnr_holdout": 24.5,
    "ssim_holdout": 0.89,
    "preset": "standard",
    "training_time_seconds": 233.7,
    "viewer_url": "https://splat-3d.com/tour/a1b2c3d4e5f6",
    "download_url": "https://api.splat-3d.com/v1/scenes/a1b2c3d4e5f6/download",
    "format": "spz",
    "lod_meta_url": null
  },
  "meta": { "request_id": "..." }
}

Quality metrics (psnr_holdout, ssim_holdout) are measured on images held out of training, so they are populated only when output.holdout_ratio is above 0. standard, quality and ultra hold out 10% by default; fast holds out none, so its metrics are null.

Step 5: Download the result

Download the reconstructed 3D model. By default you get SPZ, a compact format native viewers load, or SOG for a scene without one; the X-Splat-Format header names the file sent. Add ?format=sog for SOG (optimized for web) or ?format=ply for the raw PLY file.

# Download SOG (web-optimized)
curl -L -o scene.sog \
  "https://api.splat-3d.com/v1/scenes/$SCENE_ID/download?format=sog" \
  -H "Authorization: Bearer $SPLAT3D_API_KEY"

# Download PLY (raw, for offline tools)
curl -L -o scene.ply \
  "https://api.splat-3d.com/v1/scenes/$SCENE_ID/download?format=ply" \
  -H "Authorization: Bearer $SPLAT3D_API_KEY"

The download endpoint answers 200 with the file itself, and only to the
scene owner’s API key: there is no presigned link to hand out. To share a
scene, make it public (PATCH /v1/scenes/{id} with {"is_public": true})
and share its viewer_url. Use -o <filename> (not -O) so curl writes
to a known path instead of trying to derive a name from the URL.

# Download SOG
response = requests.get(
    f"https://api.splat-3d.com/v1/scenes/{scene_id}/download?format=sog",
    headers={"Authorization": f"Bearer {SPLAT3D_API_KEY}"},
)
with open(f"scene-{scene_id}.sog", "wb") as f:
    f.write(response.content)

const res = await fetch(
  `https://api.splat-3d.com/v1/scenes/${sceneId}/download?format=sog`,
  { headers: { Authorization: `Bearer ${SPLAT3D_API_KEY}` } }
);
const blob = await res.blob();

Next steps

Quality Presets

Choose between fast previews and ultra-quality reconstructions.

Training Parameters

Fine-tune the reconstruction pipeline for your specific use case.

Output Formats

Understand SOG vs PLY and when to use each.

API Reference

Full endpoint documentation with all request/response schemas.

Getting Started

Guides

Quickstart

Quickstart

Set your API key

Step 1: Create a scene

Step 2: Upload your video

Step 3: Start processing

Step 4: Poll for completion

Step 5: Download the result

Next steps

Quality Presets

Training Parameters

Output Formats

API Reference

​Quickstart

​Set your API key

​Step 1: Create a scene

​Step 2: Upload your video

​Step 3: Start processing

​Step 4: Poll for completion

​Step 5: Download the result

​Next steps

Quality Presets

Training Parameters

Output Formats

API Reference

Quickstart

Set your API key

Step 1: Create a scene

Step 2: Upload your video

Step 3: Start processing

Step 4: Poll for completion

Step 5: Download the result

Next steps