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

# 账户余额与用量

> 查询 API Key 维度的剩余额度，以及 OpenAI 兼容的订阅和用量信息。

# 账户余额与用量

这部分接口同时提供平台自定义包装和 OpenAI 兼容结构。

## API Key 用量

```http theme={null}
GET /api/usage/token/
```

<CodeGroup>
  ```bash theme={null}
  curl https://www.geeknow.top/api/usage/token/ \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python theme={null}
  import requests

  resp = requests.get(
      "https://www.geeknow.top/api/usage/token/",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      timeout=30,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://www.geeknow.top/api/usage/token/", {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  });

  console.log(await response.json());
  ```
</CodeGroup>

成功响应：

```json theme={null}
{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "default-token",
    "total_granted": 1000000,
    "total_used": 250000,
    "total_available": 750000,
    "unlimited_quota": false,
    "model_limits": {
      "gpt-4o": 10000
    },
    "model_limits_enabled": true,
    "expires_at": 1767225600
  }
}
```

## OpenAI 兼容订阅信息

两个路径等价：

* `GET /dashboard/billing/subscription`
* `GET /v1/dashboard/billing/subscription`

响应示例：

```json theme={null}
{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 100.0,
  "hard_limit_usd": 100.0,
  "system_hard_limit_usd": 100.0,
  "access_until": 1767225600
}
```

## OpenAI 兼容用量

两个路径等价：

* `GET /dashboard/billing/usage`
* `GET /v1/dashboard/billing/usage`

响应示例：

```json theme={null}
{
  "object": "list",
  "total_usage": 2500
}
```

<Info>
  `soft_limit_usd`、`hard_limit_usd` 和 `total_usage` 最终显示单位受站点配额展示配置影响，不一定始终是美元。
</Info>

## 常见错误

### `/api/usage/token/` 缺少 Authorization

```json theme={null}
{
  "success": false,
  "message": "No Authorization header"
}
```

### `/api/usage/token/` Bearer 格式错误

```json theme={null}
{
  "success": false,
  "message": "Invalid Bearer token"
}
```

### OpenAI 兼容余额接口错误

```json theme={null}
{
  "error": {
    "message": "query quota failed",
    "type": "upstream_error",
    "param": "",
    "code": null
  }
}
```

## 相关页面

* [认证方式](./authentication)
* [任务管理概览](../tasks/overview)