# Credits and limits

Credits are the currency for video generation. Everything else in the API (rendering, publishing, scheduling, captioning existing footage, registering assets, all reads) is free.

## What costs credits

Credits are charged once, at video creation, based on the model:

| Operation | Cost |
| --- | --- |
| `POST /videos` with `model: "storyboard"` | 20 credits |
| `POST /videos` with `model: "motion_lite"` | 50 credits |
| `POST /videos` with `model: "motion_pro"` | 100 credits |
| Each series episode (automatic or `POST /series/{id}/generate`) | the series' model cost, 20 to 100 |

Rendering the MP4 and publishing it are free, and re-rendering does not charge again: once a video is created, you can render and publish it without spending more. Deleting a video does not refund its credits.

`GET /options?kind=models` returns the model catalog with live costs, so agents can pick a model by budget.

## Check the balance (GET /credits, scope credits:read)

```bash
curl -s https://faceless.so/api/v1/credits \
  -H "Authorization: Bearer $FACELESS_API_KEY"
```

```json
{
  "success": true,
  "data": {
    "balance": 340,
    "history": [{ "id": "665f1b2a9c31a2b3c4d5e701", "credits": -50, "type": "spending", "description": "Faceless video (motion_lite)", "createdAt": "2026-07-30T10:00:00.000Z" }]
  },
  "pagination": { "page": 1, "limit": 20, "total": 1 }
}
```

The ledger lists purchases, subscription grants, spends and refunds. `GET /me` also returns the balance if you only need the number. A well-behaved agent checks the balance before a batch of creations and reports spend after.

## Running out: 402 insufficient_credits

A creation the team cannot pay for fails with `402` and error type `insufficient_credits`. Nothing is charged and nothing is created. Do not retry until the balance changes; top up or upgrade in the dashboard at https://faceless.so/billing.

## Plan limits: 403 usage_limit_reached

Plans also cap how many video projects a team can have. Creating a video past the cap fails with `403` and error type `usage_limit_reached` even when the credit balance is fine. This is not a scope problem (that is `forbidden_scope`); the fix is upgrading the plan or deleting old projects, not changing the key.

## Rate limits

Limits are per API key. Exceeding one returns `429 rate_limited` with a `Retry-After` header in seconds.

| Operation | Limit |
| --- | --- |
| Default (all operations) | 300 per 60s |
| `POST /videos` | 10 per 60s |
| `POST /videos/captions` | 10 per 300s |
| `POST /videos/{id}/render` | 10 per 300s |
| `POST /series` | 5 per 300s |
| `POST /series/{id}/generate` | 5 per 300s |
| `POST /posts` | 10 per 300s |
| `POST /posts/schedule` | 20 per 300s |

Polling `GET /videos/{id}/status` every 10 to 30 seconds and `GET /renders/{id}` every 5 to 15 seconds sits comfortably inside the default limit. See [errors and rate limits](/developers/docs/errors-and-rate-limits) for how to react to `429`s and how `Idempotency-Key` makes retries safe without double-charging.