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

# Billing

> How pricing and billing works

Lumenfall offers transparent, usage-based pricing with two billing modes.

## Billing modes

### Prepaid

Add funds to your account and pay as you go. Requests are charged against your balance in close to real-time.

* **Balance check:** If your balance becomes low, every request validates sufficient balance. This adds slight latency to the request. The threshold for this behavior varies based on your recent usage.
* **Auto top-up:** Optionally configure automatic refills when balance is low.

Manage your balance on the [Credits](/credits) page.

### Postpaid (invoice billing)

Generate now, pay later. You receive a monthly invoice for your usage.

* **Credit limit:** Based on your account history
* **Invoicing:** Monthly billing cycle

Contact [support@lumenfall.ai](mailto:support@lumenfall.ai) to request invoice billing.

## Pricing

Pricing varies by model and is calculated per request.
Check the [model catalog](https://lumenfall.ai/models) for current pricing details.

<Note>
  Pricing in the model catalog and from the cost estimation endpoint is approximate. Effective pricing is calculated after the request is run, because it depends on outputs.
</Note>

## Cost estimation

Use dry run mode to estimate costs before generating. Add `?dryRun=true` to any request to get a cost estimate without executing it. See the [Cost estimation](/api-reference/cost-estimation) API reference for details and response format.

## Effective cost on responses

Every response that delivers media includes a `metadata` object with the effective cost of the request. Because final pricing depends on outputs (resolution, duration, format), this is the authoritative cost — not an estimate.

### Images

The image generation response includes `metadata.cost` with the effective cost:

```json theme={null}
{
  "created": 1702345678,
  "data": [{ "url": "https://media.lumenfall.ai/abc123.png" }],
  "metadata": {
    "model": "gemini-3-pro-image",
    "executed_model": "vertex/gemini-3-pro-image",
    "cost": 0.04,
    "cost_currency": "USD"
  }
}
```

### Videos

Video generation is asynchronous. Cost fields on `metadata` change depending on the job status:

* **In progress:** `cost_estimate` — an estimated cost based on the request parameters.
* **Completed:** `cost` — the final effective cost.

```json theme={null}
{
  "id": "video_abc123",
  "status": "completed",
  "output": { "url": "https://media.lumenfall.ai/video_abc123.mp4" },
  "metadata": {
    "model": "sora-2",
    "executed_model": "openai/sora-2",
    "cost": 0.21,
    "cost_currency": "USD"
  }
}
```

<Note>
  The `metadata` field also includes provider routing details like `provider`, `provider_name`, `executed_model`, and `upstream_id`. See the API reference for the full schema.
</Note>

## Insufficient balance errors

If your prepaid balance is too low, requests return a `402` error:

```json theme={null}
{
  "error": {
    "message": "Insufficient balance",
    "type": "billing_error",
    "code": "INSUFFICIENT_BALANCE"
  }
}
```

To resolve:

1. [Add funds](/credits#add-funds) to your account
2. [Enable auto top-up](/credits#auto-top-up) to prevent future interruptions
3. Consider switching to postpaid billing for uninterrupted service