# 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.

A subscription is not required to create videos: any team with enough credits can generate, whether the credits came from a plan's monthly grant or a one-time top-up. Credit packs are sold at https://faceless.so/billing?tab=credits ($10 for 100 credits, with bonus credits on larger packs). Automated series remain a plan feature: creating a series requires an active subscription, and each episode then spends credits like any other video.

## 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

Paid plans 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. Teams without a subscription have no project cap; they are metered purely by credits, so they only ever see `402 insufficient_credits`.

## 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.