Getting started
Credits & pricing
Everything is pay-per-use in prepaid credits. Quick calls charge instantly; video jobs reserve an estimate up front and settle to the measured actual on completion. Use the estimate endpoint to see a job's exact credit cost before you queue it.
Price list
Flat-rate operations:
| Operation | Credits |
|---|---|
POST /characters | 10 |
POST /voices — clone | 30 |
POST /voices — library pick by language | free |
POST /tts | 10 per 1,000 characters (min 10) |
POST /images/first-frame | 6 |
POST /videos/estimate | free |
| Dynamic captions add-on (talking-head) | 10 |
Video generation is billed per second of output:
| Video line item | Credits / second | ≈ credits for 30s |
|---|---|---|
| Talking-head render @ 480p | 8 | ~240 |
| Talking-head render @ 720p | 15 | ~450 |
| Studio lipsync (included in every talking-head) | ~13.4 | ~400 |
| Multi-scene standard — 1st scene | 31 | — |
| Multi-scene standard — later scenes | 19 | ~700 for a 30s video |
| Multi-scene fast — 1st scene / later scenes | 24 / 15 | ~540 for a 30s video |
A video job's total is the sum of its line items: the render, the always-on studio lipsync (talking-head), plus speech synthesis when you pass a script, plus a first-frame image when the job has to generate one, plus captions. The mode guides show worked examples — talking-head and multi-scene.
Know the price before you fire
POST /videos/estimate takes the exact same body as POST /videos and returns the credits that call would reserve — plus your live balance and a per-line breakdown. Free, no side effects, and the character/voice don't even need to exist yet. Quote → show your user the price → queue with the same body; the reserve will equal the quote.
Two billing styles
Sync endpoints charge once, immediately
/characters, /voices, /tts, and /images/first-frame do the work inside the request and return a credits_charged field. What you see is what you paid.
Async endpoints reserve, then settle
/videos responds instantly with credits_reserved — an estimate held from your balance while the job runs. When the job completes, you're charged the measured actual cost and any over-reserve is released back. If the job fails, the full reservation is refunded (minus any partial work that was recorded, which is rare).
POST /videos → 200 { "credits_reserved": 620 } # balance drops by 620
GET /jobs/…/status → { "status": "running", "credits_consumed": null }
GET /jobs/…/status → { "status": "completed", "credits_consumed": 561 }
# 59 credits released backcredits_consumed on a job is null while queued/running, the actual charge once completed, and 0 on failed (full refund) unless partial work was billed.
When you can't afford a call
Every paid endpoint checks your balance first and returns 402 without doing (or charging) anything:
{
"error": "INSUFFICIENT_CREDITS",
"credits_required": 620,
"credits_balance": 214
}credits_required is the estimate for this request — useful to surface directly in your own product's UI. Top up via the billing page and retry.
Watching your balance
GET /usage/summary is free and returns the live balance plus job counts for any date range — details in Usage & history.