Models

Every POST /v1/worlds request must set model to one of the ids your key can use. There is no default: a missing model (or "default") fails with 400 INVALID_INPUT, and the error lists the models enabled for your key. Discover them 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": "Echo 2",
      "description": "Standard image/panorama to 3D Gaussian splat pipeline.",
      "is_default": false,
      "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"
    }
  ]
}

Pass one of the listed id values (Echo 2, Echo HQ, …) as model.

Public models

These two are enabled on every developer account unless your account is configured otherwise.

Echo 2

Echo 2 is the fast, general-purpose pipeline.

Field	Value
API id	`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": "Echo 2",
    "input": {
      "type": "text",
      "prompt": "A sunlit Tuscan villa courtyard at golden hour"
    }
  }'

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​

Echo 2​

Echo HQ​

Using a model​

Private models​