<!-- Generated by web/scripts/generate-public-discovery.mjs from web/src/data/onboarding-md. Do not edit by hand. -->

# API接口

> 这一页给想自己写脚本、自己接 SDK、或单独做用量查询的用户看。只用客户端一键接入的用户，直接看 [客户端配置](/docs/onboarding/clients) 即可。

## 先分清两种令牌

BeefAPI 里有两种常见令牌，别混用：

| 名称         | 长相                          | 用途                                       | 从哪里生成                                     |
| ------------ | ----------------------------- | ------------------------------------------ | ---------------------------------------------- |
| API Key      | `sk-...`                      | 调模型、查这个 key 自己的额度和日志        | 控制台 -> API Key -> 添加令牌                  |
| 系统访问令牌 | 一串随机字符，不是 `sk-` 开头 | 查账户余额、账户用量、个人模型等用户级接口 | 右上角头像 -> 个人设置 -> 安全设置 -> 生成令牌 |

![API Key 操作入口](/docs-onboarding/04-api-key-actions.png)

![系统访问令牌入口](/docs-onboarding/05-system-access-token.png)

## 基础地址

| 场景                                            | Base URL                     |
| ----------------------------------------------- | ---------------------------- |
| OpenAI Compatible / Codex / Cherry Studio / SDK | `https://beefapi.com/v1`     |
| Claude Code / Anthropic SDK                     | `https://beefapi.com`        |
| Gemini API 兼容                                 | `https://beefapi.com/v1beta` |
| BeefAPI 用户级接口                              | `https://beefapi.com/api`    |

## 生成 API Key

适用于调模型、查询某个 key 的额度、查询某个 key 的日志。

步骤：

1. 打开 [https://beefapi.com/console/token](https://beefapi.com/console/token)
2. 点 **添加令牌**
3. 名称随便填，例如 `my-script`
4. 选择分组：GPT/Codex 用 `gpt-plus` 或 `gpt-pro`，Claude 用 `claude-vip`
5. 提交后立刻复制完整 `sk-...`

## 生成系统访问令牌

适用于查账户余额和用户级用量，例如 `GET /api/user/self`。

步骤：

1. 在控制台右上角点头像/用户名，在下拉菜单里点 **个人设置**；也可以直接打开 [https://beefapi.com/console/personal](https://beefapi.com/console/personal)
2. 进入 **账户管理 -> 安全设置**
3. 在 **系统访问令牌** 里点 **生成令牌**
4. 生成后会自动复制到剪贴板，请立即保存

![个人设置入口](/docs-onboarding/07-user-settings-entry.png)

注意：重新生成会重置旧的系统访问令牌，旧令牌会失效。

用户 ID 在个人设置顶部信息卡里显示，例如 `ID: 123`。调用用户级接口时需要把它填到 `New-Api-User` 请求头。

![用户 ID 位置](/docs-onboarding/06-user-id-location.png)

## 认证方式

### API Key 认证

模型接口、token 用量接口、token 日志接口都用 `sk-...`：

```bash
Authorization: Bearer sk-你的APIKey
```

Anthropic / Gemini 客户端也可以用它们习惯的 header：

```bash
x-api-key: sk-你的APIKey
x-goog-api-key: sk-你的APIKey
```

### 系统访问令牌认证

用户级接口用系统访问令牌 + 用户 ID：

```bash
Authorization: Bearer 你的系统访问令牌
New-Api-User: 你的用户ID
```

## 查询账户余额和账户用量

这个接口查的是整个账户的钱包余额和历史消耗，不是单个 `sk-...` API Key 的限额。

```bash
curl https://beefapi.com/api/user/self \
  -H "Authorization: Bearer 你的系统访问令牌" \
  -H "New-Api-User: 你的用户ID"
```

常用字段：

| 字段                 | 含义                          |
| -------------------- | ----------------------------- |
| `data.id`            | 用户 ID                       |
| `data.group`         | 用户默认分组                  |
| `data.quota`         | 账户剩余额度，内部 quota 单位 |
| `data.used_quota`    | 账户历史消耗，内部 quota 单位 |
| `data.request_count` | 请求次数                      |

如果要展示美元或人民币金额，不要在客户端写死换算常量；优先使用接口返回的金额字段或以控制台当前展示规则为准。

## 查询某个 API Key 的额度

这个接口查的是某个 `sk-...` 自己的额度限制和已用额度。

```bash
curl https://beefapi.com/api/usage/token/ \
  -H "Authorization: Bearer sk-你的APIKey"
```

返回字段：

| 字段                   | 含义                    |
| ---------------------- | ----------------------- |
| `data.name`            | 令牌名称                |
| `data.total_granted`   | 这个 key 的总额度       |
| `data.total_used`      | 这个 key 已用额度       |
| `data.total_available` | 这个 key 剩余额度       |
| `data.unlimited_quota` | 是否不限制 key 自身额度 |
| `data.model_limits`    | 模型限制                |
| `data.expires_at`      | 过期时间                |

注意：`unlimited_quota=true` 只表示这个 key 自身不限额，真实可用额度仍然受账户钱包余额限制。

## 查询某个 API Key 的日志

```bash
curl https://beefapi.com/api/log/token \
  -H "Authorization: Bearer sk-你的APIKey"
```

适合第三方工具自己做“最近请求记录 / 扣费记录”展示。

## OpenAI 兼容接口

Base URL：`https://beefapi.com/v1`

认证：

```bash
Authorization: Bearer sk-你的APIKey
```

常用接口：

| 接口                                  | 用途                                       |
| ------------------------------------- | ------------------------------------------ |
| `GET /v1/models`                      | 模型列表                                   |
| `GET /v1/models/{model}`              | 模型详情                                   |
| `POST /v1/responses`                  | Responses API（推荐）                      |
| `POST /v1/responses/compact`          | Responses 压缩                             |
| `POST /v1/chat/completions`           | Chat Completions（兼容保留，不推荐新接入） |
| `POST /v1/completions`                | Completions 兼容                           |
| `POST /v1/embeddings`                 | Embeddings                                 |
| `POST /v1/rerank`                     | Rerank                                     |
| `POST /v1/moderations`                | Moderations                                |
| `POST /v1/images/generations`         | 图片生成                                   |
| `POST /v1/images/edits`               | 图片编辑                                   |
| `POST /v1/images/generations/jobs`    | 异步图片生成任务                           |
| `POST /v1/images/edits/jobs`          | 异步图片编辑任务                           |
| `GET /v1/images/jobs/{job_id}`        | 查询异步图片任务                           |
| `GET /v1/images/jobs/{job_id}/result` | 获取异步图片结果                           |
| `POST /v1/audio/transcriptions`       | 音频转文字                                 |
| `POST /v1/audio/translations`         | 音频翻译                                   |
| `POST /v1/audio/speech`               | 文本转语音                                 |
| `GET /v1/realtime`                    | Realtime WebSocket                         |

推荐示例：

```bash
curl https://beefapi.com/v1/responses \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "你好，用一句话介绍 BeefAPI",
    "stream": false
  }'
```

Chat Completions 只作为兼容接口保留，新写脚本、SDK 或 Agent 接入时优先用 `/v1/responses`；当前网关下 Chat 端点不作为推荐路径。

## Claude / Anthropic 原生接口

Claude Code 和 Anthropic SDK 的 base URL 填 `https://beefapi.com`，SDK 会自己拼 `/v1/messages`。

直接 curl 时完整地址是：

```bash
curl https://beefapi.com/v1/messages \
  -H "x-api-key: sk-你的APIKey" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'
```

支持：

| 接口                             | 用途              |
| -------------------------------- | ----------------- |
| `POST /v1/messages`              | Claude Messages   |
| `POST /v1/messages/count_tokens` | Claude token 计数 |

Claude 系模型的 API Key 分组通常要选 `claude-vip` 或 Claude 特惠分组。

## Gemini 兼容接口

Base URL：`https://beefapi.com/v1beta`

认证可用 `x-goog-api-key` 或 `?key=`：

```bash
curl "https://beefapi.com/v1beta/models" \
  -H "x-goog-api-key: sk-你的APIKey"
```

模型调用路径兼容 Gemini API：

```bash
curl "https://beefapi.com/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"parts": [{"text": "你好"}]}
    ]
  }'
```

## 价格、模型和分组

### 服务状态

```bash
curl https://beefapi.com/api/status
```

这个接口适合先检查 BeefAPI 域名是否能连通。

### 公开价格接口

```bash
curl https://beefapi.com/api/pricing
```

返回内容包含：

| 字段                 | 含义                                     |
| -------------------- | ---------------------------------------- |
| `data`               | 模型价格和模型信息                       |
| `vendors`            | 供应商列表                               |
| `group_ratio`        | 接口实时返回的分组价格配置               |
| `usable_group`       | 当前用户可用分组；未登录时按公开范围返回 |
| `supported_endpoint` | 模型支持的 endpoint 类型                 |
| `auto_groups`        | auto 分组的候选分组                      |

### 当前用户可用模型

```bash
curl "https://beefapi.com/api/user/models?group=gpt-plus" \
  -H "Authorization: Bearer 你的系统访问令牌" \
  -H "New-Api-User: 你的用户ID"
```

不传 `group` 时返回当前用户所有可用模型。

## OpenAI billing 兼容接口

部分旧客户端会调用 OpenAI billing 风格接口，BeefAPI 做了兼容：

```bash
curl https://beefapi.com/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer sk-你的APIKey"

curl "https://beefapi.com/v1/dashboard/billing/usage?start_date=2026-06-01&end_date=2026-06-27" \
  -H "Authorization: Bearer sk-你的APIKey"
```

也兼容不带 `/v1` 的旧路径：

```text
https://beefapi.com/dashboard/billing/subscription
https://beefapi.com/dashboard/billing/usage
```

## 用户级日志和数据

这些接口需要系统访问令牌。

```bash
curl "https://beefapi.com/api/log/self?p=1&size=20" \
  -H "Authorization: Bearer 你的系统访问令牌" \
  -H "New-Api-User: 你的用户ID"
```

支持的常用筛选参数：

| 参数              | 含义           |
| ----------------- | -------------- |
| `p`               | 页码           |
| `size`            | 每页数量       |
| `type`            | 日志类型       |
| `start_timestamp` | 开始时间戳，秒 |
| `end_timestamp`   | 结束时间戳，秒 |
| `model_name`      | 模型名         |
| `token_name`      | API Key 名称   |
| `group`           | 分组           |
| `request_id`      | 请求 ID        |

按天查询自己的额度消耗：

```bash
curl "https://beefapi.com/api/data/self?start_timestamp=1719763200&end_timestamp=1722441600" \
  -H "Authorization: Bearer 你的系统访问令牌" \
  -H "New-Api-User: 你的用户ID"
```

## Midjourney 和 Suno 兼容接口

BeefAPI 也保留任务类兼容接口：

| 前缀                              | 用途                           |
| --------------------------------- | ------------------------------ |
| `/mj/...`                         | Midjourney 兼容任务            |
| `/{mode}/mj/...`                  | 指定模式的 Midjourney 兼容任务 |
| `/suno/submit/{action}`           | Suno 提交任务                  |
| `/suno/fetch`、`/suno/fetch/{id}` | Suno 查询任务                  |

这类接口一般给专用客户端使用；普通 OpenAI / Claude / Gemini SDK 不需要配它。

## 暂不支持的 OpenAI 老接口

以下 OpenAI 老接口当前不是 BeefAPI 的可用能力，客户端如果自动探测到这些路径，属于兼容探测，不代表可以实际使用：

| 接口                        | 状态     |
| --------------------------- | -------- |
| `/v1/images/variations`     | 暂不支持 |
| `/v1/files`                 | 暂不支持 |
| `/v1/fine-tunes`            | 暂不支持 |
| `DELETE /v1/models/{model}` | 暂不支持 |

## 常见问题

### 我只是想给第三方工具单独查余额，应该用哪个？

如果要查账户总余额：用系统访问令牌调用 `GET https://beefapi.com/api/user/self`。

如果要查某个 `sk-...` key 自己的限额：用 API Key 调 `GET https://beefapi.com/api/usage/token/`。

### 为什么 `/api/user/self` 还要 `New-Api-User`？

这是 BeefAPI 的用户级鉴权要求。系统访问令牌要和 `New-Api-User` 指定的用户 ID 对上，才能读取对应账户信息。

### 系统访问令牌能不能用来调模型？

不建议，也不是给模型接口用的。调模型请使用 `sk-...` API Key。

### API Key 已经不限额，为什么账户还是显示没余额？

API Key 不限额只是不限制这个 key 自己的额度上限；最终仍然会扣账户钱包余额。钱包没余额时仍然会失败。