> ## Documentation Index
> Fetch the complete documentation index at: https://tryunsora.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API guide

> How the Unsora API works — authentication, rate limits, idempotency, credits, polling async jobs, and error codes.

## Base URL

```
https://mvp.tryunsora.com/api/v1
```

## Authentication

Send **either**:

* an Unsora API key (`uns_*`), or
* a Clerk session token (signed-in dashboard user)

```bash theme={null}
Authorization: Bearer uns_...
```

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:

```json theme={null}
{ "success": false, "error": "API key rate limit exceeded", "code": "RATE_LIMIT_EXCEEDED" }
```

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`:

  ```json theme={null}
  { "success": false, "error": "An active paid plan is required to use the scheduler.", "code": "PLAN_REQUIRED" }
  ```

  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](https://tryunsora.com/docs/guides/plans-and-credits.md).
* 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`:

| Status endpoint | Returns jobs from |
| - | - |
| `GET /image/status/:id` | Image generations, AI influencer, thumbnails, image upscales, movie materials |
| `GET /video/status/:id` | Every video model, motion control, talking avatars, video upscales, subtitle (watermark) removal |
| `GET /music/status/:id` | Music (Mureka) |
| `GET /voiceovers/status/:id` | Voiceovers and voice changer conversions |
| `GET /clippings/status/:clippingId` | Clipping jobs |

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](https://tryunsora.com/docs/api-reference/voiceovers/voices.md); 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](https://tryunsora.com/docs/api-reference/voiceovers/create.md).

## OpenAPI

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.