Skip to main content

Base URL

Authentication

Send either:
  • an Unsora API key (uns_*), or
  • a Clerk session token (signed-in dashboard user)
Both resolve to the same user account: the same credits, generations, connected accounts and posts. Create and revoke keys in the dashboard under Developers → API keys (/api-keys). Managing keys needs a dashboard sign-in.

Rate limits

API key requests are limited to 60 requests per minute per key. Over the limit, the API returns 429 with this body:
No rate-limit headers are sent, so back off and retry after a short wait.

Idempotency

For POST create endpoints, pass an Idempotency-Key header so a retried request doesn’t run (or charge) twice.
  • The same key on the same request path replays the stored response for 24 hours
  • Reusing a key with a different request returns 409 IDEMPOTENCY_CONFLICT
  • Replayed responses include Idempotent-Replayed: true
Posts also accept external_id in the body as an idempotency key when the header is omitted.

Plans, credits and errors

  • Posting (create, update, publish and retry a post) needs a paid plan or an active trial. Without one, those requests return 403:
    Listing, reading and deleting posts work on any plan.
  • Generation spends credits. Plans don’t include credits; they come from one-time credit packs that never expire. A job you can’t afford returns 402. See Plans and credits.
  • Credits spent through an API key are linked to that key (apiKeyId) in your credit history.

Models and prices

Models and their credit prices change as providers ship new versions, so don’t hard-code them:
  • GET /catalog lists every video, image and motion-control model with the inputs it accepts
  • POST /catalog/quote returns the exact credit cost of a job before you run it
  • POST /catalog/generate runs any catalog model
Prices are worked out live from the provider’s cost for each job.

Async jobs (polling)

All generation jobs and publishes complete asynchronously. Use polling — the public API doesn’t accept callback or webhook URLs.
  1. POST .../create returns the job id(s) with status QUEUED
  2. Poll the matching status endpoint until COMPLETED or FAILED:
A video job’s model is the model it actually ran on. Image status responses don’t include a job type field; keep track of which endpoint you called. Poll every few seconds for images and voice, and every 10–30 seconds for video and clipping. Publishing a post is async too: POST /posts/:id/publish and POST /posts/:id/retry return 202 with status PUBLISHING. Read the result with GET /posts/:id.

Voiceovers

Pick a voice with List voices; each voice includes a preview clip. voice_id accepts:
  • ElevenLabs Eleven v3 voices (the default model)
  • MiniMax Speech 2.6 HD presets, such as Friendly_Person and Calm_Woman
  • your own cloned voices (made with ElevenLabs Multilingual v2)
Then create the job with Create voiceover.

OpenAPI

  • The docs pages are generated from openapi.json in this repo
  • Live spec: GET https://mvp.tryunsora.com/api/v1/openapi.json