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)
curl -s https://faceless.so/api/v1/credits \
-H "Authorization: Bearer $FACELESS_API_KEY"{
"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 for how to react to 429s and how Idempotency-Key makes retries safe without double-charging.