Getting Started

The SpAItial Developer API is a REST interface for generating 3D worlds from text prompts or images.

Base URL

Base URL

All requests go to https://api.spaitial.ai. The examples on this page assume that base. If you're pointing at a non-production environment, swap it for the one issued to you.

Prerequisites

1. A developer account for SpAItial

   Sign up at developers.spaitial.ai. API access is public for all users.

2. An API key

   Keys look like spt_live_… and are issued from the developer portal — see Authentication. Treat them like passwords and keep them secret.

3. Credits on your account

   World generation uses credits shared across the app and API; reads, status polling, and downloads are not charged as generation. One credit equals $0.01. Echo 2 - Standard costs 160 credits, and Echo 2 (HQ) costs 800 credits. Free users receive 1,600 starter credits, enough for 10 Echo 2 - Standard generations or 2 Echo 2 (HQ) generations.

Integrating with an AI coding assistant?

Install the SpAItial API skill so your coding assistant has the full API reference, auth rules, endpoint schemas, webhooks, errors, and rate limits available locally.

npx skills add spaitial-dev/spaitial-api-skill

You can also load the LLM Skills page directly as a single self-contained reference.

Billing at a glance

Plan	Included credits	Echo 2 - Standard generations	Echo 2 (HQ) generations
Free	800 once	5 once	1 once
Standard	7,500/month	~46/month	~9/month
Pro	15,000/month	~93/month	~18/month

Included subscription credits are used before purchased credits. Standard and Pro subscribers can purchase additional credits. Larger workloads and Echo 3 API access require Enterprise.

Your first request

List the models available to your key. This is a good way to confirm auth is set up correctly. See Models for Echo 2 and Echo HQ.

curl https://api.spaitial.ai/v1/models \
  -H "Authorization: Bearer spt_live_..."

A successful response returns a JSON object describing the models available to your account.

Build the request from JavaScript

Tweak the prompt below and click Run to see the shape of the request your client would send. No network calls are made — this is purely for shape verification.

Live Editor

function CreateWorldPreview() {
  const apiKey = "spt_live_REPLACE_ME";
  const body = {
    input: {
      type: "text",
      prompt: "A sunlit Tuscan villa courtyard at golden hour",
    },
    model: "default",
    title: "Tuscan villa courtyard",
    // "spz" (default) or "sog" (PlayCanvas-optimized; adds ~25s)
    output_format: "spz",
    visibility: { is_public: false, is_listed: false },
  };

  const requestShape = {
    url: "https://api.spaitial.ai/v1/worlds",
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body,
  };

  return (
    <pre
      style={{
        fontSize: 13,
        padding: 12,
        borderRadius: 10,
        background: "rgba(127, 127, 127, 0.08)",
        margin: 0,
      }}
    >
      {JSON.stringify(requestShape, null, 2)}
    </pre>
  );
}

Result

Loading...

Generating a world

Generation is asynchronous. You submit a job, then either poll for status or let the API call your webhook when it's done. When status becomes COMPLETED, you can fetch the result, which contains signed URLs for the splat, panorama, and thumbnail.

Lifecycle at a glance

Endpoints used

Step	Endpoint	Notes
1. Upload (image flow only)	POST /v1/files	Returns a file_id to reference in step 2. Skip for text prompts.
2. Submit	POST /v1/worlds	Returns 202 with request_id and status: "PENDING".
3. Poll	GET /v1/worlds/requests/{request_id}	Returns status and progress (0–1).
4. Fetch result	GET /v1/worlds/requests/{request_id}/result	Available once status is COMPLETED.
Cancel	POST /v1/worlds/requests/{request_id}/cancel	Only valid while PENDING or PROCESSING.

Polling cadence

Most jobs finish in 6–8 minutes. A reasonable poll loop is every 5–10 seconds with backoff after the first minute. Prefer a webhook over tight polling. Pass webhook: { url: "https://your-host/spaitial" } in the create request and we'll POST COMPLETED / FAILED / CANCELLED events to it.

See the API Reference (in the left sidebar) for full request/response schemas, then Rate Limits for per-key throughput and Errors for the error envelope.