Generate a Video

Submit an Avatar ID and an audio URL, poll the job, and download the MP4 when it is ready. You can also supply a background image and control the output size, framing, color, and idle time.

The Video API is in private beta and requires separate access from the Avatar API. Request access through Spatius Studio feedback. Use the same App ID and API key for both APIs once access is enabled.

Endpoint	Purpose
`POST /v1/open/videos`	Accept a job and return `jobId`, `status`, and `createdAt`.
`GET /v1/open/video-jobs/{jobId}`	Read progress, failure details, and a fresh download URL when ready.
`GET /v1/open/video-jobs`	List your account’s jobs, newest first, with optional status filters.

Create, poll, and download

This Bash example requires curl, jq, and uuidgen. Replace the credential and source URL placeholders. The source URL must return a supported audio file with the correct Content-Type.

set -euo pipefail
export SPATIUS_APP_ID='<your-app-id>'
export SPATIUS_API_KEY='<your-api-key>'
export SPATIUS_AVATAR_ID='<your-avatar-id>'
AUDIO_URL='https://example.com/media/speech.wav'
BASE_URL='https://console.spatius.ai/v1/open'
REQUEST_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')

BODY=$(jq -n --arg avatar "$SPATIUS_AVATAR_ID" --arg audio "$AUDIO_URL" \
  --arg request "$REQUEST_ID" \
  '{avatarId:$avatar,audioUrl:$audio,requestId:$request}')

# Keep REQUEST_ID and BODY unchanged when retrying this creation.
CREATED=$(curl --fail-with-body --silent --show-error --retry 3 \
  "$BASE_URL/videos" \
  -H "X-App-ID: $SPATIUS_APP_ID" -H "X-API-Key: $SPATIUS_API_KEY" \
  -H 'Content-Type: application/json' --data "$BODY")
JOB_ID=$(jq -er '.jobId' <<< "$CREATED")
printf 'Job ID: %s\n' "$JOB_ID"

while true; do
  DETAIL=$(curl --fail-with-body --silent --show-error --retry 3 \
    "$BASE_URL/video-jobs/$JOB_ID" \
    -H "X-App-ID: $SPATIUS_APP_ID" -H "X-API-Key: $SPATIUS_API_KEY")
  STATUS=$(jq -er '.job.status' <<< "$DETAIL")
  jq '{status:.job.status,progress:.job.progress,error:.job.error}' <<< "$DETAIL"
  case "$STATUS" in
    succeeded)
      DOWNLOAD_URL=$(jq -er '.videoUrl' <<< "$DETAIL")
      curl --fail --location --show-error "$DOWNLOAD_URL" --output video.mp4
      break ;;
    failed|expired) exit 1 ;;
    *) sleep 15 ;;
  esac
done

Only avatarId and audioUrl are required. Add backgroundUrl, name, or video settings when needed. The Create a Video reference lists every field and response.

Access and safe retries

Use a public Avatar, an Avatar actively assigned to your account, or one explicitly allowed for your account. Spatius checks Avatar access when accepting the request and again before rendering. Apps owned by the same account share video jobs, retry keys, and limits. A job owned by another account returns 404. Video access can allow reads while creation is paused; removing access also revokes reads.

Creation request	Result
New `requestId`, or no `requestId`	Create a new job.
Same `requestId` and normalized input	Return the existing job’s current status without counting another creation.
Same `requestId`, different input	Return `409` with `conflict`.

Omitted video.width, video.height, and video.fit are distinct from explicit values for retry comparison. For example, omitting video and sending video: {width: 1024, height: 1024, fit: "crop"} with the same requestId returns 409, even when both would produce the same output. Other omitted presentation settings remain equivalent to their documented defaults. Keep the UUID and request body unchanged when retrying a timeout or uncertain response. To render again after a terminal failure, use a new UUID. The body field requestId is your retry key; error.requestId and the response header X-Request-ID identify an individual HTTP request for support.

Requests accepted before the change to background-based sizing used fixed defaults for omitted dimensions and fit. Replaying one of those requests after the change can return 409 even with the original body. Check the existing job before choosing a new requestId, which creates another render.

Media requirements

Input	Supported Content-Type	Maximum size	Maximum duration
Audio (WAV)	`audio/wav`, `audio/x-wav`, `audio/wave`, `audio/vnd.wave`	500 MiB	20 minutes
Background image	`image/png`, `image/jpeg`, `image/webp`	50 MiB	—

Use public HTTP(S) URLs, including signed URLs. Embedded usernames/passwords and private-network destinations are rejected. Authentication headers are not forwarded to source hosts. Each connection and redirect is checked. Keep source URLs accessible for the preparation window of up to 30 minutes; each transfer has a five-minute deadline. Only WAV audio inputs up to 20 minutes long are supported. Empty files and application/octet-stream are not supported. Audio decoding and duration checks happen asynchronously, so acceptance does not guarantee a successful render.

Presentation settings

Field in `video`	Default	Allowed values
`width`, `height`	Derived from the background image when available; otherwise 1024 for each omitted dimension. See the sizing rules below.	Even integers from 64 to 1920; combined area at most 2,073,600 pixels.
`fit`	`contain` when both dimensions are omitted and the background image’s dimensions are available; otherwise `crop`.	`crop`, `contain`
`backgroundColor`	`#000000`	Six-digit RGB hex color.
`backgroundFit`	`cover`	`cover`, `contain`, `stretch`
`leadInSeconds`, `leadOutSeconds`	0	Finite numbers from 0 to 60; additional idle time.

Output sizing

Omit both dimensions: Spatius uses the background image’s pixel dimensions when available. It scales oversized images down proportionally to fit the dimension and pixel-area limits, then rounds each dimension down to an even number, with a minimum of 64 pixels. An omitted fit becomes contain.
Supply one dimension: When the background image’s dimensions are available, Spatius derives the missing dimension from its aspect ratio and applies the same even-number rounding and 64-pixel minimum. An omitted fit remains crop. The resulting dimensions must meet the limits; an invalid derived size can fail the job during preparation.
Supply both dimensions: Spatius uses those dimensions. An omitted fit remains crop.
No background image, or its dimensions cannot be read: Each omitted dimension falls back to 1024, and an omitted fit becomes crop.

An explicit fit always takes precedence. For example, a 1920 × 1080 background with width, height, and fit omitted produces a 1920 × 1080 video using contain. To request a fixed square output, send video: {width: 1024, height: 1024, fit: "crop"}. Opening and closing transitions are included even when additional idle time is zero. Output duration can therefore exceed audio duration, with timing rounded to video frames. Spatius manages encoding settings.

Progress and downloads

Status	Meaning
`queued`	Accepted and waiting to start.
`processing`	Preparing media or rendering. Inspect `job.progress.stage`.
`succeeded`	MP4 ready; the detail response includes `videoUrl` and `videoUrlExpiresAt`.
`failed`	Terminal failure; inspect `job.error`. No new render starts automatically.
`expired`	Output has expired, or a submission remained unresolved for seven days.

Poll every 15 seconds. Progress stages describe work, not percentages or completion estimates. List Video Jobs accepts repeated filters such as statuses=queued&statuses=processing and uses the shared pagination rules. List responses contain summaries without download links. Output is currently retained for seven days after render submission. Use job.expiresAt as the retention deadline. Detail reads return fresh links, currently valid for 15 minutes, capped by that deadline. Download without App authentication headers and save the MP4 in your own storage if you need it longer. If a link refresh returns 503, retry the detail request; the saved job remains successful. After output expiry, the job returns expired without a link, while history remains available. Refreshing a link does not extend retention.

Job errors

Job failures appear under job.error, separately from HTTP request errors. Use code to decide what to fix. retryable means a new job may succeed after addressing the cause; it does not restart the failed job.

Code	Action
`source_unavailable`	Check that the media URL remains publicly accessible.
`unsupported_media_type`, `empty_media`, `media_too_large`	Fix the file or Content-Type.
`preparation_timeout`	Use a source that can finish within the preparation deadline.
`app_access_revoked`, `avatar_forbidden`	Restore App or Avatar access.
`session_token_expired`, `checksum_mismatch`, `render_failed`	Check `retryable`; submit a new job when appropriate.
`renderer_rejected`, `invalid_manifest`	Check the request; contact support with the job ID if it persists.

Limits

Video access requires explicit account limits. Creation and read counters are independent of the Avatar API, and all Apps owned by one account share them. Accepted jobs count even if they later fail; repeated requests that return an existing job do not count again.

Video limit	Hard ceiling; your configured limit may be lower
Creations per minute / hour / rolling 24 hours	20 / 200 / 2,000
Reads per minute	1,200
Reads per second / burst	20 / 40

The Console API checks video access and request rates. It does not impose an active-video-job quota; the video service manages execution concurrency. Back off after 429 responses. The Video API does not reserve Avatar Creations; video generation consumes 250 credits per minute. See Video Generation Pricing for credit estimates. This version supports URL inputs and polling. Public uploads, developer callbacks, cancellation, text-to-speech, and permanent output storage are not available.

Start Here

Avatar API

Video API

Generate a Video

Create, poll, and download

Access and safe retries

Media requirements

Presentation settings

Output sizing

Progress and downloads

Job errors

Limits

Next steps

Create a Video

Get a Video Job

​Create, poll, and download

​Access and safe retries

​Media requirements

​Presentation settings

​Output sizing

​Progress and downloads

​Job errors

​Limits

​Next steps

Create a Video

Get a Video Job

Create, poll, and download

Access and safe retries

Media requirements

Presentation settings

Output sizing

Progress and downloads

Job errors

Limits

Next steps