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 for how to react to 429s and how Idempotency-Key makes retries safe without double-charging.