> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pricing & metering

> How PyAI meters Hear, Speak, and Reason usage: the x-pyai-units response header, prepaid credits, spend caps, and 402 Payment Required semantics.

Usage is metered on the audio your calls process, billed against your plan and
prepaid credits. This page explains **what** each product meters; for current
rates, always see the live [pricing page](https://pyai.com/pricing), it is the
single source of truth and avoids stale numbers.

| Product                           | What's metered                                                                                                                                                                                                |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hear (speech-to-text)             | Audio transcribed (batch is discounted vs. realtime)                                                                                                                                                          |
| Speak (text-to-speech)            | Audio synthesized (streaming and async)                                                                                                                                                                       |
| Cue (turn detection + KB context) | Session usage                                                                                                                                                                                                 |
| Omni (speech-to-speech agent)     | Realtime session usage. Same rate in every supported language; Hindi's **Natural** voice tier (telephony premium) meters a per-minute add-on on top of the session minutes, the **Standard** tier is included |
| AMD (answering machine detection) | Per **answered** call (no-answers/busies/failed are free; first 5,000/month free; free bundled with PyAI telephony/Omni)                                                                                      |
| PyAI Agents (managed)             | Realtime session usage, **Beta**. Available now; features, limits, and production behavior may change during beta                                                                                             |
| Telephony (managed numbers)       | Carrier/PSTN usage                                                                                                                                                                                            |

<Note>
  Rates change as we improve the platform. We intentionally keep figures out of the
  docs so you never act on a stale number, the [pricing page](https://pyai.com/pricing)
  and your console usage are always current.
</Note>

## The units header

Billed responses carry an `x-pyai-units` header reporting exactly what was
metered for that request (e.g. the amount of audio synthesized or transcribed).
Read it to reconcile your own usage accounting against ours.

## Credits and spend caps

* Account signup creates a sandbox key. It does not guarantee promotional credit.
* Live keys consume prepaid credit. Phone verification may unlock promotional credit under the current graduated-signup rules.
* **Per-key budgets**, set a monthly spend cap on any key in the console.
* **Org credit gate**, when prepaid credit is exhausted, billed calls return
  `402` until you top up.

## Sandbox tier (no billing)

A `pyai_test_` key works instantly against production models with hard daily caps
(requests/day, concurrent sessions, audio minutes/day) and **never** touches
billing. Use it for evals and CI so a first call never hits the credit gate.

## 402 semantics

A `402` means a billing limit was reached, it is **not** a broken key:

| Code                  | Meaning                     | What to do                            |
| --------------------- | --------------------------- | ------------------------------------- |
| `credit_exhausted`    | Org out of prepaid credit   | Add credit, or use a `pyai_test_` key |
| `key_budget_exceeded` | Per-key monthly cap reached | Raise the key's budget                |
| `insufficient_quota`  | Plan quota exhausted        | Upgrade the plan                      |

Do not retry a `402`, the call will keep failing until the underlying limit
changes. See [Errors & limits](/errors-and-limits) for the full catalog.