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

# 計費

> 估價、預留、扣款、餘額與用量。

## 估價

`POST /estimate` 的 body 與 `POST /jobs` 相同，回傳此刻提交會預留的金額。估價不扣款、不建立工作。

```bash theme={null}
curl https://api.blon.ai/v1/estimate \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","input":{"prompt":"A ceramic teapot on a linen table, soft morning light"}}'
```

```json theme={null}
{
  "model": "gpt-image-2",
  "cost": {
    "currency": "CREDITS",
    "amount": "8"
  },
  "kind": "exact",
  "reason": null
}
```

能由輸入算出價格時 `kind` 為 `exact`；部分價格取決於產出時為 `upper_bound`，並由 `reason` 說明上限依據。`{url}` 輸入會先匯入，因為價格可能取決於它的長度。

## 預留與結算

1. **提交**：Blon 從餘額預留估價金額；不足時回 `402 insufficient_credits`。
2. **完成**：依實際量測的用量（工作的 `usage`）扣款，剩餘的預留會釋放。
3. **失敗或取消**：釋放預留，`charged` 為 `"0"`。

工作的 `cost` 反映這個過程：

| 欄位 | 說明 |
| - | - |
| `currency` | `blon_api_` 金鑰為 `USD`，其他為 `CREDITS` |
| `estimated` | 提交時預留的估價，不會改變 |
| `charged` | 實際扣款；工作未到終態前為 `null` |
| `refunded` | 扣款之後退回的金額 |

釋放未用的預留不是退款，不會出現在 `refunded`。工作一律以提交當下的價格結算。

## 餘額

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

```json theme={null}
{
  "currency": "USD",
  "available": "18.425",
  "held": "0.0042",
  "usage_this_month": "1.5708",
  "spend_limit": {
    "amount": "50.00",
    "spent": "1.5708",
    "window": "month",
    "resets_at": "2026-11-01T00:00:00.000Z"
  }
}
```

| 欄位 | 說明 |
| - | - |
| `available` | 目前可用金額 |
| `held` | 未結束工作的預留 |
| `usage_this_month` | 本月已花費 |
| `spend_limit` | 只在金鑰設有花費上限時出現：`amount`、`spent`、`window`（`day`、`week`、`month` 或 `lifetime`）與 `resets_at` |

超過花費上限時，提交回 `403 api_key_spend_limit_exceeded`。

## 用量

```bash theme={null}
curl "https://api.blon.ai/v1/usage?timeframe=day" \
  -H "Authorization: Bearer $BLON_API_KEY"
```

```json theme={null}
{
  "currency": "USD",
  "timeframe": "day",
  "start": "2026-10-24T00:00:00.000Z",
  "end": "2026-10-31T00:00:00.000Z",
  "data": [
    {
      "bucket_start": "2026-10-30T00:00:00Z",
      "model": "gpt-image-2",
      "api_key_id": "key_7d2f9a",
      "jobs": 12,
      "units": {
        "output_images": 12
      },
      "cost": "0.48"
    }
  ]
}
```

| 參數 | 說明 |
| - | - |
| `timeframe` | `hour`、`day`、`week` 或 `month`，預設 `day` |
| `start` | RFC 3339，預設為 `end` 前 7 天 |
| `end` | RFC 3339，預設為現在；與 `start` 最多相隔 31 天 |

只計已結算的工作，以結算時間分桶；`cost` 為扣除退款後的淨額。用量是報表，不是帳單。


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