# Billing & usage
> Credits, prepaid generation and understanding, successful usage settlement, and refunds.

Credits are the independent quota and billing unit agents spend when they call
Beatra skills. There is no fixed credit-to-currency exchange rate. Top-up
offers define how many credits a payment buys in each market; public model
prices define how many credits an operation consumes.

## How charging works

Generation, speech synthesis, voice, music, and dedicated image/video
understanding tasks are prepaid. Beatra charges the price of the accepted task at submit; generation
whose final quantity varies settles against measured usage on success.
Understanding uses the full number of accepted images, or input-video
seconds rounded up, so the amount charged at submit is exact. Public social-data reads
(`beatra.social.execute`) are also prepaid: the credit price is 6, 12, 30, or
60, and it is confirmed before the task is created.

If the balance cannot cover the prepaid amount, the API returns
`402 insufficient_balance` and no task is created.

The AI Director (`beatra.speech.prepare_script`, `POST /v1/audio/speech/scripts`)
is postpaid: it is charged after it succeeds, from the input, output and
reasoning tokens it actually used. To start, the balance must cover its
estimate for the text: the capability catalog's estimate per 1,000 characters,
prorated to the length of the text (counting at least 1,000 characters), plus
the estimate of any other AI Director task in progress on the account.
Otherwise the API returns `402 insufficient_balance` with
`details.reason: director_estimate`, and no task is created. The charge is the
actual usage, usually below the estimate; if it is more than the balance at
that moment, the charge stops at the balance.

## How many at a time

| Plan | At a time |
| --- | ---: |
| No plan | 2 |
| Starter | 4 |
| Builder | 6 |
| Pro | 8 |
| Studio | 8 |

When this many creations are already in progress, a new request is not started
and nothing is charged. Wait for one to finish and retry the same request, or
pick a plan that allows more at a time. REST per-minute limits are documented
on the rate-limits page.

ElevenLabs speech has a separate cap: at most two ElevenLabs speech tasks in
progress per account, whatever the plan. Free clone previews count toward it;
MiniMax and Doubao tasks do not. A third request returns 429 `rate_limited`
with `details.reason: speech_inflight_limit` and nothing is charged.

The AI Director has its own cap as well: at most two AI Director tasks in
progress per account, whatever the plan, and a limited number across the
platform. A third request returns 429 `rate_limited` with
`details.reason: director_inflight_limit` (over MCP, the plan limit above can
answer first); while the AI Director is at capacity, a request returns 429
with `details.reason: director_busy`. Neither starts a task or charges
anything. For `director_inflight_limit`, wait for one of the account's AI
Director tasks to finish, then submit again; for `director_busy`, retry after
`details.retry_after_seconds` (over REST, the `Retry-After` header carries the
same seconds).

## Prepaid understanding

- `POST /v1/images/responses` charges the accepted `image_count` at 5 credits
  per image, up to eight images.
- `POST /v1/videos/responses` charges the accepted `input_video_seconds` at 0.4
  credits per second; milliseconds are rounded up to a whole second.
- `detail` and provider token usage do not change the price.
- Failed or confirmed-canceled understanding tasks automatically refund the
  amount charged at submit through the standard prepaid refund path.

## Successful prepaid usage settlement

For a task whose final billable quantity depends on accepted media or measured
output, the submission debit is an estimate. On success, Beatra settles against
authoritative measured usage using the price snapshot captured at submission:

- lower actual usage returns the unused estimate in `refunded_credits`;
- equal usage needs no wallet adjustment;
- higher valid actual usage within the accepted request contract adds a
  supplemental debit to `charged_credits`.

Measured usage that is inconsistent with its own input/output breakdown or
exceeds the accepted request and model limits is never applied as actual usage
or as a supplemental debit. The original submission debit remains unchanged
while the task stays pending settlement for operator review.

The final amount is returned directly as `billing.net_charged_credits` (and is
equal to `billing.charged_credits - billing.refunded_credits`). A successful overage can
leave the wallet below zero; the artifact remains valid, while new billable
work is rejected until the balance is topped up.

## Automatic refunds on failure

When a task is `failed` or cancellation is confirmed and the task becomes
`canceled`, the held credits are **automatically refunded to source** — no
request needed. A cancellation conflict means the task is still running and
does not trigger a refund:

```json
"billing": {
  "charged_credits": 48.0,
  "refunded_credits": 48.0,
  "net_charged_credits": 0.0
}
```

## Billing fields in responses

Every task response carries:

| Field | Description |
| --- | --- |
| `usage.credits` | Net credits consumed by the successful request |
| `usage.image_count` | Admitted image count for image understanding, or successful output count for image generation |
| `usage.video_seconds` | Authoritative billable **output** video seconds after settlement (equals `usage.output_video_seconds`; any billed input component is reported separately) |
| `usage.input_video_seconds` / `usage.output_video_seconds` | Authoritative input/output components when available; `null` means no authoritative component was returned, not zero |
| `billing.net_charged_credits` | Final net wallet charge after actual-usage settlement and refunds |
| `billing.charged_credits` / `billing.refunded_credits` | Cumulative wallet debits / cumulative refunds; subtract them for the final net charge |

## Balance and top-up

Credit purchases are one-time payments in CNY with WeChat Pay. View your balance and add credits at
[console.beatra.cn/wallet?intent=buy](https://console.beatra.cn/wallet?intent=buy).

Credits belong to the account you are signed in to when you add them, and an Agent
can only spend the credits of the account it is connected to. The top-up page names
that account ("Adding credits to: …"). If you have two accounts, see
[Accounts and merging](https://docs.beatra.cn/en/docs/accounts).