Skip to main content

SpAItial Developer API Service Description

Last updated: September 23, 2026

This page describes the customer-facing scope, principal features, and current limitations of the SpAItial Developer API. It is intended to help customers evaluate and operate integrations with the service.

Service scope​

The SpAItial Developer API is an authenticated REST API for programmatically creating and retrieving AI-generated 3D worlds. The production API is available at https://api.spaitial.ai, and customers manage API access through developers.spaitial.ai.

Customers can submit text, supported images, equirectangular 360° panoramas, or edited panoramas to an asynchronous generation workflow. Completed jobs provide access to a 3D Gaussian Splat, panorama, thumbnail, and hosted viewer. Supported export operations can produce additional artifacts.

This description covers the public Developer API and its published endpoints. The interactive web application is a separate service described in the SpAItial App Service Description.

Primary features​

FeatureDescription
API authentication and scopesCreate bearer API keys with explicit scopes and revoke them through the developer portal.
Model discoveryList the generation models available to an API key, including model descriptions, credit costs, and estimated durations.
Input methodsGenerate from text, an image URL, an inline base64 image, a temporary uploaded file, a 360° panorama, or a supported edited panorama.
Asynchronous world generationSubmit a job, inspect its status and progress, cancel eligible jobs, and fetch completed results.
Polling and webhooksPoll job status or configure a webhook to receive terminal job events.
Generated outputsRetrieve authenticated download endpoints for splats and panoramas, along with thumbnail and viewer URLs.
Panorama editingCreate and retrieve temporary edited panoramas for use in subsequent world-generation requests.
File handlingUpload, list, and reference temporary private image inputs.
Error and usage controlsUse stable error codes, idempotency keys, validation feedback, and rate-limit headers to operate an integration reliably.

The API reference documents the current request and response schemas for each published endpoint.

Access and service requirements​

Customers need:

  • A SpAItial developer account.
  • A server-side integration capable of protecting a bearer API key.
  • An API key with the scopes required by each requested operation.
  • Sufficient eligible credits for credit-consuming operations.
  • The ability to process asynchronous job states, errors, retries, and expiring resources.

See Authentication, Credits and Billing, and the API Reference for current requirements.

Limitations and customer considerations​

  • Generated results vary. Worlds and panorama edits are produced by generative AI. Results may not precisely reproduce an input or prompt and may contain visual, geometric, or semantic artifacts.
  • Generation is asynchronous. A successful submission accepts a job for processing; it does not mean generation is complete. Published durations are estimates, and jobs can fail or be cancelled. Integrations must inspect the terminal status before requesting results.
  • Rate limits apply per API key. The default limits are 60 general requests per minute, 10 world-creation requests per minute, and 120 download requests per minute. A world-creation request consumes both its world-create bucket and the general bucket. Account-specific limits may differ.
  • Authentication and credits are required. Requests can be rejected because a key is missing, invalid, revoked, expired, or insufficiently scoped. Credit-consuming requests can also be rejected when the account lacks enough eligible credits.
  • Inputs are screened. User-controlled inputs are subject to content moderation. Optional suitability validation can identify image-quality issues, but it is not a safety system and is skipped by default unless the customer enables it.
  • Some resources are temporary. Uploaded files and edited panoramas have a 24-hour lifetime. Download endpoints redirect to short-lived signed URLs, so integrations should resolve them shortly before downloading.
  • Input and output constraints apply. Supported file types, file sizes, input shapes, models, and output formats are limited to those documented in the current API schema. Model availability can vary by account.
  • Failures require explicit handling. Integrations should branch on stable error codes, honor Retry-After, use backoff with jitter for retryable failures, and use idempotency keys for retried mutating requests.
  • API keys are server-side secrets. The API is not designed for keys to be embedded in browser code, mobile applications, or other software distributed to end users.

Customer responsibilities​

Customers are responsible for:

  • Keeping API keys secret, assigning only necessary scopes, and revoking keys that may have been exposed.
  • Providing content they are authorized to process.
  • Reviewing generated results before relying on or distributing them.
  • Implementing appropriate timeout, retry, idempotency, error-handling, and webhook-handling behavior.
  • Consuming temporary input and panorama resources before they expire.
  • Monitoring credit consumption and applicable rate limits.

Use of the service is also governed by the Terms of Service and Privacy Policy.

For service questions or support, contact [email protected].

This description is updated when material changes are made to the Developer API's scope, features, requirements, or limitations.