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

# Billing

> How the estimate is held from your balance at submission, how the final cost is settled, why failed generations are free, what the cost fields mean, and what happens when the balance falls below zero.

Codzen is prepaid. You top up your **balance** in US dollars in the console, and each generation is charged against it at the model's listed price. For current prices, see [pricing](https://codzen.ai/pricing) or each model's page.

## How a generation is charged

1. **Submit: the estimate is held.** When you create a generation, Codzen computes its **estimate** from the model's prices and your `input`, and holds that amount from your balance. If the balance does not cover the estimate, the request fails with `402 insufficient_balance` and nothing is held.
2. **Finish: the final cost is settled.** When the generation succeeds, its final cost is computed from what it actually delivered. The difference from the estimate is settled: if the final cost is lower, the rest is returned to your balance; if it is higher, the difference is charged.
3. **Fail: nothing is charged.** When the generation fails, for any reason, the whole estimate returns to your balance and the final cost is `"0.00"`.

The final cost can be higher than the estimate, for example when the model produces a longer output than the estimate assumed. Plan for small differences either way.

## The `cost` object

Every generation carries a `cost` object:

```json theme={null}
{
  "currency": "USD",
  "estimated": "0.50",
  "amount": "0.40",
  "usage": [
    { "unit": "output_second", "quantity": 4, "unit_price": "0.10" }
  ]
}
```

| Field | Description |
| - | - |
| `currency` | Always `USD`. |
| `estimated` | The estimate held from your balance at submission. |
| `amount` | The final cost: `null` while the generation is in progress, the actual cost once it succeeds, `"0.00"` when it fails. |
| `usage` | What the final cost was computed from: one item per price row the generation was billed by. Empty until the cost is known. |
| `usage[].unit` | The billing unit, as the model is priced, such as `output_second` or `million_tokens`. |
| `usage[].quantity` | How many units were billed. |
| `usage[].unit_price` | The price of one unit, in USD. |

A generation can be billed by more than one price row, for example per second of output plus per second of input video, so `usage` is always an array, even with one item.

Amounts are decimal strings, such as `"0.40"`, so that they keep their exact value. Parse them with a decimal type rather than a floating-point number. The sum of `amount` over your generations is what you have spent; [list your generations](https://docs.codzen.ai/guides/generation-lifecycle.md#list-your-generations) to reconcile it with your records.

## Check your balance

```bash theme={null}
curl https://codzen.ai/api/v1/balance \
  -H "Authorization: Bearer $CODZEN_API_KEY"
```

```json theme={null}
{ "amount": "42.50", "currency": "USD" }
```

The balance already excludes the estimates held for generations in progress.

## Low and negative balance

Because a final cost can exceed its estimate, settling a generation can take your balance below zero. A negative balance is still your balance, shown as a negative `amount`:

```json theme={null}
{ "amount": "-0.20", "currency": "USD" }
```

While the balance is below zero, or too low to cover a new generation's estimate, `POST /generations` fails with `402 insufficient_balance`. Generations already in progress still finish. Top up in the console: the top-up first brings the balance back up from below zero, and new generations are accepted again as soon as the balance covers their estimate.

> [!TIP]
>
> Check `GET /balance` from your backend and top up before it runs low, so that your users never see `insufficient_balance`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.