# Pricing & billing

> Pay-as-you-go wallet billing in USD, pre-submission cost estimates, automatic failure refunds, and token-billed video pricing.

## How wallet billing works

Kerox bills in USD directly from your wallet — no subscriptions or opaque credit conversions. Every task follows three ledger states:

1. **Hold (`cost.status: "held"`)**: When you submit `POST /v1/tasks`, Kerox calculates the estimated cost and places a hold on your available balance.
2. **Settle (`cost.status: "settled"`)**: When the task succeeds, Kerox settles the actual cost and releases any excess hold back to your balance.
3. **Refund (`cost.status: "refunded"`)**: If the task fails, times out, or is canceled while `queued`, the entire hold is refunded automatically (`cost.amount: "0.0000"`).

## Current model rates

All numbers below are calculated directly from the live model catalog configuration. Sign in or call `GET /v1/models` with your API key to see any account-level or per-model discounts.

| Model | ID | Billing | Kerox rate | Notes |
| --- | --- | --- | --- | --- |
| Seedream 5.5 | `bytedance/seedream-5.5` | Per image | 1K/1.5K: $0.0160, 2K: $0.0280 | Save 20% vs official |
| Seedream 5.0 Pro | `bytedance/seedream-5.0-pro` | Per image | 1K/1.5K: $0.0360, 2K: $0.0720 | Save 20% vs official |
| Seedream 4.5 | `bytedance/seedream-4.5` | Per image | $0.0320 | Save 20% vs official |
| Seedream 4.0 | `bytedance/seedream-4.0` | Per image | $0.0270 | Save 10% vs official |
| Seedream 5.0 Lite | `bytedance/seedream-5.0-lite` | Per image | $0.0315 | Save 10% vs official |
| Seedance 2.5 | `bytedance/seedance-2.5` | Billed by tokens | Approx. $0.2196 / s (720p) | 16:9 without reference video; lower rate with reference video |
| Seedance 2.0 | `bytedance/seedance-2.0` | Billed by tokens | Approx. $0.1436 / s (720p) | 16:9 without reference video; lower rate with reference video |
| Seedance 2.0 Fast | `bytedance/seedance-2.0-fast` | Billed by tokens | Approx. $0.0968 / s (720p) | 16:9 without reference video; lower rate with reference video |
| Seedance 2.0 Mini | `bytedance/seedance-2.0-mini` | Billed by tokens | Approx. $0.0605 / s (720p) | 16:9 without reference video; lower rate with reference video |

## Seedance video pricing (billed by tokens)

Seedance video models are shown as **Approx. $/s** so you can compare durations at a glance, while actual settlement is **billed by tokens**:

- **Two rate tiers**:
  - **Without reference video**: standard per-second estimate applied to the output duration.
  - **With reference video**: lower unit rate applied to the combined duration (`output seconds + reference video seconds`).
- **Token formula**:
  `tokens = (output seconds + reference video seconds) × width × height × frame rate / 1024`, with width and height from the requested resolution and aspect ratio. Each model's page, and `pricing.token_formula` in `GET /v1/models`, give the formula with that model's frame rate.
- **Aspect ratio & audio**: Per-second estimates are converted at `16:9` without reference video. At the same resolution, other aspect ratios differ by less than 5%. Turning audio on or off does not change the price.
- **Estimate before submitting**: Studio shows the estimated cost before you click Generate, and API callers can send the same request body to `POST /v1/estimate`. The final charge follows the tokens of the finished video.

## Estimating cost before submission

`POST /v1/estimate` accepts the same payload as `POST /v1/tasks`, never creates a task, never holds balance, and does not count against per-minute submission rate limits. The `amount` it returns is what submitting the request would hold. `exact` is `false` when the final charge depends on the result, as it does for token-billed models.

```bash
curl -X POST https://api.kerox.ai/v1/estimate \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.5",
    "input": {
      "content": [
        { "type": "text", "text": "a red fox running through fresh snow" }
      ],
      "resolution": "720p",
      "duration": 5
    }
  }'
```
```python
import os
import requests

resp = requests.post(
    "https://api.kerox.ai/v1/estimate",
    headers={
        "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "bytedance/seedance-2.5",
        "input": {
            "content": [
                {"type": "text", "text": "a red fox running through fresh snow"}
            ],
            "resolution": "720p",
            "duration": 5,
        },
    },
    timeout=30,
)
print(resp.json())
```
```javascript
const res = await fetch('https://api.kerox.ai/v1/estimate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEROX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bytedance/seedance-2.5',
    input: {
      content: [
        { type: 'text', text: 'a red fox running through fresh snow' },
      ],
      resolution: '720p',
      duration: 5,
    },
  }),
});
console.log(await res.json());
```

## Top-ups & balance alerts

Request a top-up from [Console → Wallet](/console/wallet) (minimum $5). We reply in Support with payment details, and your balance updates as soon as the payment is confirmed. Low-balance emails are off by default: turn them on and set the amount in [Console → Settings](/console/settings). You can also read your balance at any time with `GET /v1/account`.
