Models

Pass model on POST /v1/worlds to choose a pipeline. Omit it, or send "default", to use Echo 2 (Standard). Discover the ids your key can use with GET /v1/models — each entry includes docs_url.

Endpoints

Endpoint	Scope	Purpose
GET `/v1/models`	`worlds:read`	List generation models available to this API key.

List models

API_KEY="spt_live_..."

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

{
  "models": [
    {
      "id": "default",
      "description": "Standard image/panorama to 3D Gaussian splat pipeline.",
      "is_default": true,
      "credit_cost": 160,
      "estimated_duration_seconds": 522,
      "docs_url": "https://docs.spaitial.ai/api/generation-models#default"
    },
    {
      "id": "Echo HQ",
      "description": "Higher-detail, higher-resolution worlds.",
      "is_default": false,
      "credit_cost": 800,
      "estimated_duration_seconds": 3600,
      "docs_url": "https://docs.spaitial.ai/api/generation-models#echo-hq"
    }
  ]
}

The "default" id is virtual — it always points at whatever alias is marked default for your account (Echo 2). The named aliases (Echo 2, Echo HQ, …) are the values you can pass as model.

Public models

These two are available on every developer account.

Default (Echo 2)

Echo 2 is the fast, general-purpose pipeline. This is what you get when you omit model or pass "default".

Field	Value
API id	`default` or `Echo 2`
Best for	Text, image, or panorama → world
Typical time	~8 minutes
Credits	160

curl -sX POST https://api.spaitial.ai/v1/worlds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "input": {
      "type": "text",
      "prompt": "A sunlit Tuscan villa courtyard at golden hour"
    }
  }'

Omitting model is equivalent:

curl -sX POST https://api.spaitial.ai/v1/worlds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "url",
      "image_url": "https://example.com/photo.jpg"
    }
  }'

Echo HQ

Higher detail and resolution. Same input types as Echo 2; longer runtime and higher credit cost.

Field	Value
API id	`Echo HQ`
Best for	Higher-detail / higher-resolution worlds
Typical time	~60 minutes
Credits	800

curl -sX POST https://api.spaitial.ai/v1/worlds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Echo HQ",
    "input": {
      "type": "text",
      "prompt": "A sunlit Tuscan villa courtyard at golden hour"
    }
  }'

The id is case-sensitive and includes the space: "Echo HQ", not "hq" or "echo-hq".

Using a model

curl -sX POST https://api.spaitial.ai/v1/worlds \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Echo HQ",
    "title": "Tuscan courtyard",
    "input": {
      "type": "text",
      "prompt": "A sunlit Tuscan villa courtyard at golden hour"
    }
  }'

See Create a world for the full request body, and Credits and Billing for plan capacity.

Private models

Some accounts are granted extra models. Those appear in GET /v1/models only after they are granted, and their docs_url points at the matching private docs in the developer portal.

Endpoints​

List models​

Public models​

Default (Echo 2)​

Echo HQ​

Using a model​

Private models​