Credits

Generation spends credits. Reads are free.

Reserve and refund

When a generation job starts, its estimated cost is reserved — taken out of your available balance immediately, before any work happens. If the job fails, the reservation is refunded.

The practical consequence: a failed job does not cost you. You do not need to reconcile failures or claim anything back. What you do need to handle is that a job in flight has already reduced your spendable balance, so two jobs dispatched back to back both reserve, even if the first later fails.

Checking your balance

curl -s https://api.botlobby.ai/v1/users/credits \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"

{
  "subscription_credits": 480,
  "bonus_credits": 50,
  "total_credits": 530,
  "credits_refreshed_at": "2026-09-01T00:00:00+00:00"
}

Spend against total_credits — generation draws on both buckets, and the difference between them is only about when they expire:

Bucket	Behaviour
subscription_credits	Refreshed each billing period. Unused credits do not roll over.
bonus_credits	Referrals and one-off grants. Not tied to the billing period.

credits_refreshed_at is when the subscription bucket last reset, which tells you how far into the current period you are.

Running out

402, on the endpoint that tried to reserve:

{ "error": "Insufficient credits" }

Nothing is dispatched and nothing is charged.

What things cost

Cost depends on the operation and its settings — script generation, voiceover and render are priced separately, the voice model matters (a self-hosted voice is cheaper than an external one), and AI illustration scales with how many images the video needs.

Rather than print a table here that would go stale, see botlobby.ai/pricing.

Two things visible through the API help you predict cost per job:

• GET /personas returns text_is_internal, audio_model_class (self_hosted or external) and audio_model_name for each persona — the flags that drive its per-video cost.
• GET /subscription/current returns your plan's limits and your usage so far.

Practical advice

• Check before a batch, not during. Discovering 402 on job 40 of 100 leaves you reconciling which ones ran. One GET /users/credits up front avoids that.
• Watch seconds_per_image under video_id: generate. Fewer seconds per image means more images, and AI illustration is the setting that most changes cost. It has no cost effect on other visual sources.
• A 429 is not a 402. Rate limits and credits are separate ceilings — see Rate limits.