Skip to main content
The Spatius API lets your backend create and manage avatars programmatically. Submit a source image, and receive a custom avatar.
The Spatius API is currently in private beta and is not available to all users. To request access, submit a feedback ticket at app.spatius.ai/feedback/create. If you receive forbidden with “API Avatar creation is disabled” or “Open API access is not configured”, your account has not been enrolled yet.

​
How avatar creation works

Avatar creation is asynchronous. A single POST /avatars call accepts the job; a background worker then downloads, validates, and preprocesses the image, and generates the Avatar through the same pipeline used by Spatius Studio.
1

Submit a creation job

Call POST /avatars with a public image URL. The API validates your quota, concurrency, and Avatar Creations balance, reserves a creation, and returns a jobId with status queued.
2

Poll the job

Call GET /avatar-jobs/{jobId} every 5–10 seconds. The job moves from queued to processing, then to a terminal state.
3

Use the Avatar ID

When the job reaches succeeded, read avatarId from the job and use it in your SDK integration. If the job reaches failed, inspect error.code and error.retryable.

​
Job statuses

​
Source image requirements

The source image is validated asynchronously, after the job is accepted. A job whose image fails validation ends in failed with a specific error code, so submit images that already meet these rules:
  • Public HTTP(S) URL that responds within 3 seconds
  • JPEG or PNG, at most 5 MiB
  • Shorter side at least 340 pixels
  • PNG images must be fully opaque
  • Exactly one clearly visible face

​
Billing

Each creation job reserves one Avatar Creation when it is accepted. The reservation is captured when preprocessing completes, and released if the job fails before that point. When the balance is insufficient, POST /avatars is rejected with 402 and code insufficient_avatar_units. You can view your current available Avatar Creations at app.spatius.ai/avatars/creations.

​
Next steps

Authentication

Authenticate with the X-App-ID and X-API-Key header pair.

Errors and Limits

Error envelope, status codes, job failure codes, and rate limits.