Base URL
Authentication
Send either:- an Unsora API key (
uns_*), or - a Clerk session token (signed-in dashboard user)
/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 returns429 with this body:
Idempotency
ForPOST 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
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 /cataloglists every video, image and motion-control model with the inputs it acceptsPOST /catalog/quotereturns the exact credit cost of a job before you run itPOST /catalog/generateruns any catalog model
Async jobs (polling)
All generation jobs and publishes complete asynchronously. Use polling — the public API doesn’t accept callback or webhook URLs.POST .../createreturns the job id(s) with statusQUEUED- Poll the matching status endpoint until
COMPLETEDorFAILED:
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_PersonandCalm_Woman - your own cloned voices (made with ElevenLabs Multilingual v2)
OpenAPI
- The docs pages are generated from
openapi.jsonin this repo - Live spec:
GET https://mvp.tryunsora.com/api/v1/openapi.json

