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

# 计费

> 查看你的美元余额、通过 Stripe 充值，并查看交易历史。

VibeToken 的计费以**美元**计价。每次调用的模型费用会在提交时预留，并在成功后扣除；失败的生成任务会释放预留额度。Stripe 充值则会增加余额。

## 余额生命周期

```
submit gen     reserve  (held += cost,  available -= cost,  credits unchanged)
   │
   ├── success → charge   (credits -= cost, held -= cost,  transactions row written)
   │
   └── failure → release  (held -= cost,  credits unchanged, no transactions row)
```

## 获取余额

```
GET https://vibetoken.cn/api/v1/billing/balance
```

```json theme={null}
{
  "credits": 42.50,
  "held": 1.20,
  "available": 41.30,
  "currency": "USD"
}
```

| 字段          | 含义                                |
| ----------- | --------------------------------- |
| `credits`   | 原始账户余额。只有充值和已完成的扣费才会改变它。          |
| `held`      | 待处理生成任务预留额度的总和。尚未从 `credits` 中扣除。 |
| `available` | `credits − held`。你可用于新请求的金额。      |
| `currency`  | 始终为 `USD`。                        |

<Info>
  请以 `available` 作为可消费余额。当请求费用超过 `available` 时，提交会被拒绝并返回 `402 Insufficient Credits`，即便仅 `credits` 足以覆盖该费用也是如此。
</Info>

## 充值

```
POST https://vibetoken.cn/api/v1/billing/topup
```

通过 Stripe 发起一笔美元购买。一旦 Stripe 确认付款，该金额将被加入 `credits`。

<ParamField body="amount" type="number" required>
  要添加到余额中的美元金额。
</ParamField>

## 交易历史

```
GET https://vibetoken.cn/api/v1/billing/transactions
```

返回所有充值和**已完成**用量扣费的分页列表。进行中的预留（`held`）不会列在此处——在生成任务完成之前，它们还不算交易。

### 查询参数

<ParamField query="page" type="number">
  页码。默认值：`1`。
</ParamField>

<ParamField query="per_page" type="number">
  每页结果数。默认值：`20`。
</ParamField>

### 响应

```json theme={null}
{
  "data": [
    {
      "id": "txn_01HXYZ",
      "credits": -0.05,
      "amount": 0.05,
      "payment_method": "usage",
      "status": "completed",
      "created_at": "2025-01-15T11:00:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 20
}
```

| `payment_method` | 代表的含义                      |
| ---------------- | -------------------------- |
| `usage`          | 一次生成已完成并被扣费。`credits` 为负值。 |
| `stripe`（或类似值）   | 一笔充值已到账。`credits` 为正值。     |

## 余额提醒

### 创建提醒

```
POST https://vibetoken.cn/api/v1/billing/alerts
```

<ParamField body="threshold" type="number" required>
  当 `credits` 低于此金额时接收一封邮件。
</ParamField>

### 删除提醒

```
DELETE https://vibetoken.cn/api/v1/billing/alerts/{id}
```