# BeefAPI Full Agent Briefing

Generated from build/src/data/onboarding-md on 2026-07-08.

## What BeefAPI is

BeefAPI is an AI API gateway and billing platform for users who want one account and one token surface for multiple AI model providers and client workflows. It is especially useful for users configuring AI agents, coding tools, OpenAI-compatible clients, Claude-related workflows, and model playground or console usage.

## What agents should cite

- Short agent file: https://beefapi.com/llms.txt
- This full briefing: https://beefapi.com/llms-full.txt
- Latest public pricing snapshot: https://beefapi.com/pricing.json
- API alias for pricing: https://beefapi.com/api/public/pricing
- Public API contract: https://beefapi.com/openapi.json and https://beefapi.com/openapi.yaml
- AI plugin manifest: https://beefapi.com/.well-known/ai-plugin.json
- Agent answer recipes: https://beefapi.com/agent-answers.md
- Public pricing explanation: https://beefapi.com/pricing.md
- Public model facts: https://beefapi.com/models.md
- Public group facts: https://beefapi.com/groups.md
- Human docs: https://beefapi.com/docs/onboarding

## Pricing and availability

Always fetch https://beefapi.com/pricing.json before answering questions about current models, groups, endpoint support, or price configuration. BeefAPI public prices are CNY-first and include USD equivalents for comparison. The public snapshot is intentionally non-personalized: it excludes private user discounts and private user-group overrides. Logged-in account permissions and final billing remain authoritative for a specific user.

## Answer recipes

Use https://beefapi.com/agent-answers.md when drafting concise answers about what BeefAPI is, how to check pricing, how to configure OpenAI-compatible or provider-compatible clients, why a model may be unavailable, and what is or is not live for future x402 utilities.

## Public docs content

# Quickstart

Canonical page: https://beefapi.com/docs/onboarding/quickstart
Markdown mirror: https://beefapi.com/docs/onboarding/00-quickstart.md

# 快速开始 · 6 步上手 BeefAPI

> 第一次用 AI API 中转? 跟着这 6 步走，10 分钟拿到你的 key + 跑通第一个工具。
> 老手可以直接跳第 4 步 (创建令牌) + 第 6 步 (CC Switch 一键导入)。

![BeefAPI 首页](/docs-onboarding/01-homepage-hero.png)

---

## 1. 注册账号

打开 [https://beefapi.com](https://beefapi.com) → 右上 "**登录/注册**" → 填邮箱 + 验证码注册。

**支持登录方式**：

- **邮箱 + 密码**：最稳，验证邮件可能进垃圾箱，先检查再申请补发
- **WebAuthn / Passkeys**：推荐，免密码 + 防钓鱼，支持 iPhone Face ID / Mac Touch ID / 1Password / YubiKey 等

注册后先进入控制台。新用户可以先加入 QQ 群 **912022855**，加群后私信群主，领取5 元体验额度；到账后再按下面步骤完成充值、创建令牌和工具配置。

> **遇到验证码收不到？**
>
> 1. 检查邮箱垃圾箱 / 广告分类
> 2. 在 "登录" 页点 "重新发送验证码"
> 3. 仍然没有 → 联系在线客服处理

---

## 2. 登录后到控制台

登录后默认进 `/console` 控制台。左侧菜单：

| 菜单                | 用途                                                 |
| ------------------- | ---------------------------------------------------- |
| **概览**            | 余额 + 今日消费 + 模型调用统计                       |
| **聊天 · 在线体验** | 网页聊天入口，可先在浏览器里测试模型是否可用         |
| **个人设置**        | 改密码 / 绑 OAuth (Google/GitHub) / WebAuthn passkey |
| **令牌**            | 创建 API key（第 4 步）                              |
| **充值**            | 钱包充值入口（第 3 步）                              |
| **日志**            | 查每次请求的 model / token / 扣费明细                |

> **提示**：左下角头像点开是 **主题切换 / 退出登录**。深色主题更适合长时间盯着代码看。

---

## 3. 充值钱包

**侧栏 → 充值** → 选金额 → 选支付方式（支付宝）。

充值是**钱包额度**，不绑定具体模型，所有 group 共用同一个钱包余额扣费。
充值到账后，可以在 **概览** 看余额，在 **日志** 看每次请求的扣费明细。

---

## 4. 创建 API 令牌

**侧栏 → 令牌 → 新建令牌**：

| 字段         | 说明                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------ |
| **名称**     | 自己识别用，比如 `claude-code-mac` / `codex-laptop` / `cherry-studio`                      |
| **分组**     | **关键！** 决定能用哪些模型和走哪套价格配置，见 [分组说明](/docs/onboarding/groups-models) |
| **额度**     | 单 key 限额。设 `0` = 不限（= 用完钱包余额）                                               |
| **过期时间** | 默认永不过期                                                                               |
| **数量**     | 一般 1 个，要批量给团队就调高                                                              |

### 防坑：选错 group 会怎样？

最常见错误：令牌选了 `claude-vip` 分组，但你工具填的模型是 `gpt-5.5` → **直接 404 `model_not_found`**。

**对应关系（粗略）**：

| 你要用                                                         | 选哪个 group                                  |
| -------------------------------------------------------------- | --------------------------------------------- |
| Claude Code / Claude 系（claude-sonnet-4-6 / claude-opus-4-7） | `claude-vip` 或 `claude 特惠`                 |
| Codex / ChatGPT 类（gpt-5.4 / gpt-5.5 / gpt-5.4-mini）         | `gpt-plus` 或 `gpt-pro`                       |
| 老 `gpt-vip` 分组                                              | 老分组不建议新建，切到 `gpt-plus` / `gpt-pro` |
| 画图 `gpt-image-2`                                             | 任意 `gpt-*` 分组                             |

完整 group → model 映射说明见 [分组 / 模型](/docs/onboarding/groups-models)，实时价格配置以模型广场为准。

### 立即复制 sk-xxx

创建后**马上复制完整 `sk-xxx` 字符串保存**，关闭页面再回来就只显示前后几位掩码了。

> 复制不到？点令牌行最右边的 "复制" icon，或者**删了重建一个新的**。

---

## 5. 检查 base URL

BeefAPI 的两个 endpoint：

| 用途                                                                         | URL                      |
| ---------------------------------------------------------------------------- | ------------------------ |
| **OpenAI 兼容**（Codex / OpenAI SDK / Cherry Studio / NextChat / 自己 curl） | `https://beefapi.com/v1` |
| **Anthropic 原生**（Claude Code / Claude SDK）                               | `https://beefapi.com`    |

> **⚠️ 注意 `/v1` 后缀**
>
> - OpenAI 兼容 CLI **必须**加 `/v1`
> - Claude Code / Anthropic SDK **不要**加 `/v1`，直接用根域名
>
> 装错 `/v1` 是 404 错误最常见的原因之一。

---

## 6. 配置工具

### 推荐：CC Switch 一键导入

**控制台 → API Key → 令牌行 → 一键接入** → 默认打开 **CC Switch** → 选择导入到 Codex / Claude Code / Claude Desktop / Hermes → 选模型 → 打开 CC Switch 确认导入。

Claude Desktop 用户注意：CC Switch 深链会先导入 Claude 供应商；导入后到 CC Switch 左侧 **Claude Desktop** 面板，点击 **将 Claude Code 中已有的供应商导入** 或手动启用该供应商，然后重启 Claude Desktop。

![一键接入向导 modal](/docs-onboarding/03-onboarding-modal.png)

<video class="bf-onboarding-video" controls playsinline preload="metadata">
  <source src="https://pub-e540a6ea6d6e4af19d7f5fc4d1f07c47.r2.dev/docs/onboarding/beefapi-codex-onboarding-20260622-1080p.mp4" type="video/mp4" />
  你的浏览器暂不支持视频播放。
</video>

向导会自动：

- 拉取你的真实 API Key
- 构造 CC Switch 导入链接
- 按你选择的应用写入 Claude Code / Codex / Hermes 所需配置；Claude Desktop 需要在 CC Switch 的 Claude Desktop 面板导入/启用
- 自动带入 Key、接口地址和模型配置

### 🧑‍💻 手动配置

Image2、自己写 SDK、以及其他 OpenAI Compatible 客户端看 [客户端配置](/docs/onboarding/clients)。

---

## 验证跑通

任意工具配完后第一句话先打：

```
你好，请告诉我你是什么模型，今天日期
```

模型回答出 "我是 Claude Sonnet 4 / GPT-5.5" 且日期合理 = 通了。

回答不出来 / 报错 → 看 [错误码排查](/docs/onboarding/errors)。

---

## 下一步

- [分组 / 模型 / 价格](/docs/onboarding/groups-models) - 选对 group 防 404
- [客户端配置](/docs/onboarding/clients) - 手动 + 自动两种路线
- [API接口](/docs/onboarding/api) - 自己写 SDK / 单独查用量
- [错误码排查](/docs/onboarding/errors) - 401 / 429 / 524 / model_not_found
- [常见问题](/docs/onboarding/faq) - 账号 / 充值 / 令牌 / 工具配置


---

# Groups, Models, Pricing

Canonical page: https://beefapi.com/docs/onboarding/groups-models
Markdown mirror: https://beefapi.com/docs/onboarding/10-groups-models.md

# 分组与模型 · 选对 group 是接入第一步

> **令牌选什么 group, 就决定能用哪些模型和走哪套价格配置**。选错最常见后果：`model_not_found` 404。
>
> 分组价格、可用模型和模型描述会随运营配置调整，文档不写固定价格数字；实际以 **模型广场** 和控制台日志为准。

---

## 一句话总览

| group         | 适合谁                    | 模型范围 / 特点                                   |
| ------------- | ------------------------- | ------------------------------------------------- |
| `gpt-plus`    | **大多数 GPT 用户**       | 覆盖常用 GPT / Codex / 图片模型，适合日常主力使用 |
| `gpt-pro`     | 重度 Codex / 高强度推理   | GPT 高阶资源池，适合长上下文、记忆和重度任务      |
| `gpt-vip`     | **⚠️ 老分组，不建议新建** | 老分组可能不可用或不稳定                          |
| `claude-vip`  | **大多数 Claude 用户**    | Claude 全量资源池，包含 Opus / Sonnet / Haiku     |
| `claude 特惠` | 想用 Claude 但不用 Opus   | Claude 常用资源池，通常覆盖 Sonnet / Haiku        |

实时模型和价格配置以 **模型广场** 展示为准。

---

## 价格怎么看

不要按文档里的历史数字估价。实际扣费由 **模型价格、分组价格配置、输入/输出用量** 共同决定，可能随运营配置调整。

你应该看两个地方：

1. **模型广场**：看当前 group 下可用模型和实时价格配置。
2. **控制台 → 日志**：看每次请求的实际扣费明细。

日常只用 Sonnet / Haiku 可优先看 `claude 特惠`；需要 Opus 再看 `claude-vip`。最终仍以模型广场当前展示为准。

---

## 常见模型类型

### OpenAI 系列（gpt-plus / gpt-pro）

| model 示例      | 用途                       |
| --------------- | -------------------------- |
| `gpt-5.5`       | 主力模型，对标 ChatGPT Pro |
| `gpt-5.4`       | 上代主力                   |
| `gpt-5.4-mini`  | 轻量任务 / 客服            |
| `gpt-5.3-codex` | Codex 专用编码版本         |
| `gpt-image-2`   | 画图                       |

### Anthropic Claude（claude-vip / claude 特惠）

| model 示例          | 用途                          |
| ------------------- | ----------------------------- |
| `claude-opus-4-7`   | 复杂推理 / 高质量输出         |
| `claude-opus-4-6`   | Opus 系模型                   |
| `claude-sonnet-4-6` | **主力推荐**，速度 + 质量平衡 |
| `claude-haiku-4-5`  | 轻量快速任务                  |

> 这里只列常见模型类型，完整可用模型和价格配置以 **模型广场** 为准。

---

## 我应该选哪个 group？

### 决策树

**只用 Claude？** → 不用 Opus 选 `claude 特惠`，要 Opus 选 `claude-vip`

**只用 GPT / Codex？** → 普通选 `gpt-plus`，重度长上下文选 `gpt-pro`

**两个都要？** → **建两个令牌**，分别选不同 group，分工具用：

- `claude-code-mac` 令牌 → `claude-vip` group
- `codex-mac` 令牌 → `gpt-plus` group

### 不要为了"全能"勉强用 gpt-vip

`gpt-vip` 是老分组，新建令牌不要再选。已有 `gpt-vip` 令牌建议重建令牌，改选 `gpt-plus` / `gpt-pro`。

---

## 模型广场看实时清单

顶部 nav "**模型广场**" → 左侧选 group → 右侧看该 group 包含的全部 model、实时价格配置和描述：

![模型广场](/docs-onboarding/02-pricing-square.png)

---

## 防 `model_not_found` 4 步排查

1. **检查令牌 group**：控制台 → 令牌 → 看你这个 key 用的 group
2. **对照本页表格**：你要的 model 是不是在这个 group 的清单里
3. **改正其一**：
   - 改令牌 group（删了重建，旧 key 同时失效）
   - 改工具配置 model 名拼到正确 group 包含的模型
4. **仍然 404**：去 https://beefapi.com 看 "**模型广场**" 实时清单（有可能新模型刚上 / 旧模型刚下）

---

## 下一步

- [客户端配置](/docs/onboarding/clients) - 拿 key + group 配工具
- [错误码排查](/docs/onboarding/errors) - 401 / 429 / 524 / model_not_found


---

# API

Canonical page: https://beefapi.com/docs/onboarding/api
Markdown mirror: https://beefapi.com/docs/onboarding/30-api.md

# 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 自己的额度上限；最终仍然会扣账户钱包余额。钱包没余额时仍然会失败。


---

# Clients

Canonical page: https://beefapi.com/docs/onboarding/clients
Markdown mirror: https://beefapi.com/docs/onboarding/40-clients.md

# 客户端接入 · 优先用 CC Switch

> **推荐路径**：控制台 → 令牌 → 令牌行点 **一键接入** → 选 **CC Switch**。Claude Code / Codex / Hermes / OpenClaw 可直接导入；Claude Desktop 走 CC Switch 的 Claude Desktop 面板完成导入/启用。

![一键接入向导](/docs-onboarding/03-onboarding-modal.png)

---

## CC Switch 一键导入

CC Switch 是图形界面工具，会把 BeefAPI 的接口地址、API Key 和模型写入 Claude Code、Codex、Hermes 或 OpenClaw；Claude Desktop 需要在 CC Switch 的 Claude Desktop 面板中导入/启用该供应商。确认导入后，重新打开目标客户端即可使用。

### 1. 先安装目标客户端

| 你要用         | 先装什么                                   | 令牌 group                    |
| -------------- | ------------------------------------------ | ----------------------------- |
| Claude Code    | `npm install -g @anthropic-ai/claude-code` | `claude-vip` 或 `claude 特惠` |
| Claude Desktop | Claude Desktop + CC Switch                 | `claude-vip` 或 `claude 特惠` |
| Codex          | OpenAI Codex CLI / App                     | `gpt-plus` 或 `gpt-pro`       |
| Hermes         | Hermes Desktop / CLI                       | 包含所选模型的分组            |
| OpenClaw       | `npm install -g openclaw`                  | 包含所选模型的分组            |

### 2. 创建 API Key

控制台 → **令牌** → **新建令牌**。Claude Code / Claude Desktop 用 Claude 分组；Codex / GPT / Image2 用 GPT 分组；Hermes / OpenClaw 按你选择的模型所在分组来选。

### 3. 打开一键接入

令牌行点 **一键接入**：

1. 默认打开 **CC Switch**。
2. 如未安装 CC Switch，先点对应平台下载。Intel / AMD 64 位 Windows 请选择 **Windows x64**；只有 Windows on ARM 设备才选 **Windows ARM**。
3. `导入到` 选择 **Codex**、**Claude Code**、**Claude Desktop**、**Hermes** 或 **OpenClaw**。
4. 选主模型，点击 **打开 CC Switch**。
5. CC Switch 弹出确认后点导入 / 启用。

### Claude Desktop 注意点

- CC Switch 深链公开协议不接受 `app=claude-desktop`，所以 BeefAPI 会先用 `app=claude` 导入 Claude 供应商，避免出现 “Invalid app type ... got 'claude-desktop'”。
- 导入后打开 CC Switch 左侧 **Claude Desktop** 面板，点击 **将 Claude Code 中已有的供应商导入**，或在 Claude Desktop 面板手动启用对应供应商。
- 切换成功后需要完全退出并重启 Claude Desktop。
- Claude Desktop 建议选择 `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` 这类模型名；如果要在 Desktop 里使用非 Claude 模型，可在 CC Switch 的 Claude Desktop 面板配置模型映射。

### Hermes 注意点

- 当前 CC Switch Hermes 导入会写成 **Chat Completions**；BeefAPI 已兼容这个 chat 端点，正常对话可直接使用。
- 如果某个模型或 Hermes 功能在 Chat Completions 下失败，再打开左侧 **Hermes** 面板切换 API Mode：GPT / Codex / OpenAI 系模型用 **Codex Responses**，Claude / Anthropic 系模型用 **Anthropic Messages**。
- Hermes 原生 `config.yaml` 配置应使用 `custom_providers` 并把主模型指向 `custom:beefapi`。
- 手动改配置时请保留 provider `name: beefapi`，一键脚本会用这个名字幂等替换旧的 BeefAPI 条目。
- Hermes Desktop 和 CLI 共用同一份配置、key、会话与 skills；`HERMES_HOME` 会覆盖默认目录。macOS / Linux 默认读 `~/.hermes/config.yaml`；Windows 新版 Desktop 默认读 `%LOCALAPPDATA%\hermes\config.yaml`，仅当新版目录不存在但已有旧 `~\.hermes` 目录时才会兼容沿用旧目录。

### 4. 验证

重新打开对应客户端，问：

```text
你好，请告诉我你是什么模型
```

能正常回答就是接入成功。

---

## Image2 / gpt-image-2

`gpt-image-2` 按 OpenAI Images API 配置。Base URL 使用 `/v1`，模型固定填 `gpt-image-2`。

### 令牌要求

- 令牌 group 选 `gpt-plus` 或 `gpt-pro`。
- 模型固定填 `gpt-image-2`。
- 当前 Image2 通道一次只支持 1 张图：`n` 不填或填 `1`。

### 接口

| 字段     | 值                            |
| -------- | ----------------------------- |
| Base URL | `https://beefapi.com/v1`      |
| Endpoint | `POST /v1/images/generations` |
| Model    | `gpt-image-2`                 |

### curl 示例

```bash
curl https://beefapi.com/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只透明玻璃质感的机械小龙虾，产品摄影，白底",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json"
  }'
```

### Python OpenAI SDK

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://beefapi.com/v1",
)

image = client.images.generate(
    model="gpt-image-2",
    prompt="一张赛博茶室海报，中文霓虹招牌，干净构图",
    size="1024x1024",
    n=1,
)

print(image.data[0].b64_json or image.data[0].url)
```

---

## OpenClaw 云服务器命令行配置

适合 VPS / SSH 环境。下面命令会备份并合并 `~/.openclaw/openclaw.json`，按模型把 BeefAPI 写成 Responses 或 Anthropic Messages provider。

```bash
npm install -g openclaw

export BEEFAPI_KEY="sk-xxx"
export BEEFAPI_MODEL="gpt-5.5"

mkdir -p ~/.openclaw
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%s) 2>/dev/null || true

node <<'NODE'
const fs = require('fs');
const path = `${process.env.HOME}/.openclaw/openclaw.json`;
const key = process.env.BEEFAPI_KEY;
const model = process.env.BEEFAPI_MODEL || 'gpt-5.5';
const modelLower = model.trim().toLowerCase();
const isClaude =
  modelLower.startsWith('claude') ||
  modelLower.startsWith('anthropic/') ||
  modelLower.includes('/claude');
const isOpenAIResponses =
  modelLower.startsWith('gpt') ||
  modelLower.startsWith('chatgpt') ||
  modelLower.startsWith('codex') ||
  modelLower.startsWith('openai/') ||
  /^o[0-9]/.test(modelLower) ||
  modelLower.includes('/gpt') ||
  modelLower.includes('/chatgpt');

if (!key || key === 'sk-xxx') {
  console.error('请先把 BEEFAPI_KEY 改成你的 BeefAPI API Key');
  process.exit(1);
}

let cfg = {};
if (fs.existsSync(path)) {
  const raw = fs.readFileSync(path, 'utf8').trim();
  if (raw) cfg = JSON.parse(raw);
}

cfg.models = cfg.models || {};
cfg.models.mode = 'merge';
cfg.models.providers = cfg.models.providers || {};
cfg.models.providers.beefapi = {
  baseUrl: 'https://beefapi.com/v1',
  apiKey: key,
  api: isClaude
    ? 'anthropic-messages'
    : isOpenAIResponses
      ? 'openai-responses'
      : 'openai-completions',
  models: [{ id: model, name: model }],
};

cfg.agents = cfg.agents || {};
cfg.agents.defaults = cfg.agents.defaults || {};
cfg.agents.defaults.model = cfg.agents.defaults.model || {};
cfg.agents.defaults.model.primary = `beefapi/${model}`;

fs.writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`);
console.log(`[BeefAPI] wrote ${path}`);
NODE

openclaw gateway restart || true
openclaw start
```

令牌 group 要包含你选择的模型。这里使用 `https://beefapi.com/v1`：GPT / Codex / OpenAI 系模型实际请求走 `/v1/responses`；Claude / Anthropic 系模型走 `/v1/messages`。

---

## 自己写 / OpenAI SDK

### Responses API（GPT / Codex / OpenAI 系模型）

```bash
curl https://beefapi.com/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "你好",
    "stream": false
  }'
```

Chat Completions 只作为未知模型或兼容接口保留；GPT / Codex / OpenAI 系模型优先用 `/v1/responses`，Claude / Anthropic 系模型用 `/v1/messages`。

### Anthropic Messages API（Claude / Anthropic 系模型）

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

### Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://beefapi.com/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input="你好",
)
print(response.output_text)
```

### Node.js

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-xxx',
  baseURL: 'https://beefapi.com/v1',
});

const r = await client.responses.create({
  model: 'gpt-5.5',
  input: '你好',
});
console.log(r.output_text);
```

---

## 常见坑

| 现象                      | 先查什么                                            |
| ------------------------- | --------------------------------------------------- |
| 401                       | API Key 是否完整复制了 `sk-xxx`                     |
| 404 / `model_not_found`   | 令牌 group 是否包含这个模型                         |
| Claude Code 连不上        | Base URL 是否是 `https://beefapi.com`，不要加 `/v1` |
| Codex / OpenAI SDK 连不上 | Base URL 是否是 `https://beefapi.com/v1`            |
| Image2 多图失败           | `n` 是否大于 1，先改成 1 或不填                     |

详细错误处理见 [错误码排查](/docs/onboarding/errors)。


---

# Errors

Canonical page: https://beefapi.com/docs/onboarding/errors
Markdown mirror: https://beefapi.com/docs/onboarding/50-errors.md

# 常见错误 · 看 HTTP code + 错误 message 对号入座

> 客服 / agent 解决问题第一步：**告诉我你的完整 error JSON + HTTP code + 用什么工具/模型/group**。光说 "我报错了" 没人能猜。

---

## 报错时先抓的信息

```
{
  "工具": "Claude Code / Codex / Cherry Studio / curl",
  "base_url": "https://beefapi.com 或 https://beefapi.com/v1",
  "model": "比如 claude-sonnet-4-6 / gpt-5.5",
  "group": "claude-vip / gpt-plus / ...",
  "HTTP code": "401 / 429 / 524 / 500 / ...",
  "完整 error body JSON": "把上游返的 error 整段贴过来",
  "request_id": "如果有，response header X-Request-Id 也贴上"
}
```

把这 7 项发给客服，可以更快定位问题。

---

## 401 Unauthorized

### 现象

```
{"error": {"code": "invalid_api_key", "message": "Incorrect API key provided"}}
```

或 Claude Code 提示：

```
exceeded retry limit, last status: 401 Unauthorized
```

### 排查清单

1. **key 拼写**：从 BeefAPI 控制台 → 令牌 → 点 "复制"，**不要手打**。`sk-` 开头，长度 ~50 字符
2. **key 过期**：BeefAPI 控制台 → 令牌 → 看 "过期时间"
3. **key 被删了**：可能你不小心删掉了，控制台对照令牌列表
4. **shell 残留旧 env**：
   - 查：`env | grep -i ANTHROPIC` 或 `env | grep -i OPENAI`
   - 看到旧 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` 残留 → 改/删，重启终端
   - **Codex 用户特别坑**：装过别的中转可能在 `~/.zshrc` 留 `OPENAI_BASE_URL` 指别处
5. **header 错填**：
   - Claude Code 用 `ANTHROPIC_AUTH_TOKEN`，**不是** `ANTHROPIC_API_KEY`
   - OpenAI 兼容用 `Authorization: Bearer sk-xxx`，**不是** `OpenAI-Api-Key`
6. **base URL 不对**：
   - Claude Code 用 `https://beefapi.com`（**不加** `/v1`）
   - OpenAI 兼容必须 `https://beefapi.com/v1`（**必须加** `/v1`）

### 终极排查（Windows）

```cmd
cmd /c "echo OPENAI ENV CHECK & ^
if defined OPENAI_API_KEY (echo OPENAI_API_KEY = SET) else (echo OPENAI_API_KEY = MISSING) & ^
if defined OPENAI_BASE_URL (echo OPENAI_BASE_URL = SET) else (echo OPENAI_BASE_URL = MISSING) & ^
if defined ANTHROPIC_AUTH_TOKEN (echo ANTHROPIC_AUTH_TOKEN = SET) else (echo ANTHROPIC_AUTH_TOKEN = MISSING)"
```

### 终极排查（macOS / Linux）

```bash
env | grep -iE "openai|anthropic|claude"
```

看到不该有的旧 var → 找对应 `~/.zshrc` / `~/.bashrc` 删掉相关 `export` 行 → 重启终端。

---

## 404 Not Found / `model_not_found`

### 现象

```
{"error": {"code": "model_not_found", "message": "The model 'gpt-5.5' does not exist"}}
```

### 99% 是 group / model 不匹配

你的令牌 group **不包含**你请求的 model。例：

- 令牌 group = `claude-vip` → 只能用 claude 系，请求 `gpt-5.5` → 404
- 令牌 group = `gpt-plus` → 只能用 gpt 系，请求 `claude-sonnet-4-6` → 404

**修复**：

1. **改令牌 group** —— 控制台 → 令牌 → 新建一个对的 group 的令牌（旧的可以删）
2. **或改工具配置 model 名** —— 改成当前 group 包含的 model

完整 group → model 映射见 [分组与模型](/docs/onboarding/groups-models)。

### 1% 是 model 拼写错

`gpt-5.5` 写成 `gpt-5-5` 或 `gpt5.5` → 也 404。

去 https://beefapi.com **模型广场** 复制官方名。

---

## 429 Too Many Requests / 速率限制

### 现象

```
{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached"}}
```

或：

```
codex account rate-limited (429)
```

### 原因

- 单 key 同时并发请求太多
- 上游账号被限速（你这条线路繁忙）

### 修复

1. **降低并发**：如果你脚本里多线程同时打，先 1 线程跑测试
2. **等 30-60 秒重试**：单纯偶发限速，一会儿就好
3. **持续 429**：可能上游线路繁忙，联系在线客服处理
4. **gpt-vip 老分组**：直接停了用，建新令牌选 `gpt-plus` / `gpt-pro`

---

## 524 / Gateway Timeout

### 现象

Cloudflare 524（100s 超时）或 504 Gateway Timeout。

### 原因

- 上游模型推理超时（复杂任务 / opus 长推理 / 大 PDF / Codex 深推理 effort=high+long task）
- 上游 down

### 修复

1. **减小请求体**：长 PDF / 大上下文先 chunk
2. **切轻量模型**：opus → sonnet → haiku，gpt-5.5 → gpt-5.4-mini
3. **降 reasoning_effort**：Codex 把 `model_reasoning_effort = "high"` 改 `"medium"` / `"low"`
4. **重试 3 次**：偶发超时，重试通常 OK
5. **持续 524**：联系在线客服，可能是上游全局问题

---

## "Unable to connect to Anthropic services"

### 现象

```
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR BAD REQUEST
```

### 原因

Claude Code 配置没生效，还在连官方 `api.anthropic.com`（被墙）。

### 修复

确认 `~/.claude/settings.json` 内 `ANTHROPIC_BASE_URL` 是 `https://beefapi.com`（不是默认 `api.anthropic.com`）。

如果用 env 变量：

```bash
echo $ANTHROPIC_BASE_URL  # macOS / Linux
echo %ANTHROPIC_BASE_URL%  # Windows
```

应该输出 `https://beefapi.com`。没输出 → `.zshrc` / `.bashrc` 没生效，重启终端。

或者首次安装绕过 onboarding 检查：

**macOS / Linux**：

```bash
jq '. + {"hasCompletedOnboarding": true}' ~/.claude.json > /tmp/cc.json && mv /tmp/cc.json ~/.claude.json
```

**Windows (PowerShell)**：

```powershell
$f = "$env:USERPROFILE\.claude.json"
$j = Get-Content $f | ConvertFrom-Json
$j | Add-Member -NotePropertyName 'hasCompletedOnboarding' -NotePropertyValue $true -Force
$j | ConvertTo-Json -Depth 10 | Set-Content $f
```

重启 `claude` CLI。

---

## quota_not_enough / 余额不足

### 现象

```
{"error": "quota_not_enough", "message": "用户额度不足"}
```

### 原因

钱包没钱，或令牌设了额度上限且达到。

### 修复

1. **钱包没钱** → 控制台 → 充值
2. **令牌达上限** → 控制台 → 令牌 → 编辑这个 key → 提高 / 取消 "额度"
3. **预扣费失败**：可能上次请求扣费没补结算 → 等 1 分钟自动恢复，仍不行联系在线客服

---

## Codex 用着用着觉得"降智"

很多人用一段时间 Codex 后觉得"模型变笨"。其实**不是模型降级**，而是用法问题。

### 关键：拆任务 + 别压缩

1. **不要笼统任务**：❌ "帮我写一个管理系统" ✅ "实现 User 表的 CRUD endpoint"
2. **任务开始前评估**：你能预估这次会改哪几个文件 / 产生哪些变动吗？答不出来 → 拆得不够细
3. **60% 上下文还没完成 = 拆得太粗**：Codex 一次任务最好用 60% 以内上下文。优秀用户几乎不用 `/compact`
4. **指哪打哪原则**：Codex 模型严谨有序但需要明确指令，不会"猜"你想要什么

### 关闭 1M 上下文（更省更稳）

`config.toml` 加：

```toml
model_context_window = 200000  # 200K, 不要默认 1M
```

### 提示词指南（写进 `AGENTS.md`）

```markdown
# Codex 全局工作指南

## 拆任务

- 一次只做一个小模块
- 任务开始前在脑子里 / 草稿纸上预估改动文件
- 60% 上下文未解决 = 立即停, 拆细重做

## 回答风格

- 中文
- 表格、列表用 Markdown 美化
- 代码改动前用 `/diff` 看 full diff
```

---

## 网络代理（梯子）相关

如果你电脑开了梯子，部分请求可能被代理劫持失败。

**症状**：偶发 connection error / SSL cert error / 长时间 hang

**排查**：

1. 临时关梯子重试
2. 把 `beefapi.com` 加入代理白名单（不走代理直连）
3. Clash 用户：把 MTU 改 1500（默认有时太小）

---

## 仍然解决不了？

联系在线客服时，把上面 "报错时先抓的信息" 7 项一起发过去。

---

## 下一步

- [分组与模型](/docs/onboarding/groups-models) - 选对 group 防 404
- [常见问题](/docs/onboarding/faq) - 账号 / 充值 / 令牌 / 工具配置


---

# FAQ

Canonical page: https://beefapi.com/docs/onboarding/faq
Markdown mirror: https://beefapi.com/docs/onboarding/99-faq.md

# 常见问题 FAQ

---

## 注册 / 账号

### Q: 我是新用户应该怎么开始？

跟着 [快速开始](/docs/onboarding/quickstart) 6 步走，10 分钟拿 key + 跑通工具。

### Q: 收不到验证码？

1. 检查邮箱垃圾箱 / 广告分类
2. 登录页点 "重新发送验证码"
3. 仍然没有 → 联系在线客服处理

### Q: 想换登录邮箱？

控制台 → 个人设置 → 改邮箱（需要二次验证）。

### Q: 忘记密码？

登录页 → "忘记密码" → 邮箱重置链接。OAuth (Google/GitHub) / Passkeys 用户直接走原认证。

### Q: 我能不能用 Passkey 免密登录？

可以，控制台 → 个人设置 → "WebAuthn / Passkeys" → 添加。iPhone Face ID / Mac Touch ID / 1Password / YubiKey 都支持。强烈推荐，防钓鱼 + 免输密码。

---

## 充值 / 余额

### Q: 充值后多久到账？

支付宝一般 30 秒内到账。10 分钟没到 → 联系在线客服处理。

### Q: 可以退款吗？

可以，联系在线客服说明订单和账号即可。

### Q: 怎么看消费明细？

控制台 → 日志 → 每条记录：时间 / 模型 / 输入 token / 输出 token / 扣费金额。
也能按 token / 模型 / group 过滤。

### Q: 怎么导出消费记录？

控制台 → 日志 → 右上 "导出" → 选时间范围 → 下载 CSV。

### Q: 余额能不能转给别人？

不能，钱包绑定账号。共用同一钱包请共用账号（但生产建议团队各自注册，下面 Q 看怎么给团队建多 key）。

---

## 令牌 / API key

### Q: 怎么给团队不同人发 key 但共用余额？

注册 1 个账号 → 创建多个令牌（每个名字不同，比如 `alice-claude-code` / `bob-codex`）→ 发给团队。所有令牌共用钱包余额。
缺点：看不到谁花了多少。建议团队大就各自注册。

### Q: key 泄露了怎么办？

控制台 → 令牌 → 删掉那个 key → 新建一个。删除后立即失效，原 key 后续请求会 401。

### Q: 可以限制 IP 白名单吗？

可以。控制台 → 令牌 → 编辑 → "IP 白名单"。多个 IP 用逗号分隔。

### Q: 我能限制单 key 用多少额度吗？

可以。控制台 → 令牌 → "额度" 字段。设 `0` = 不限（用完钱包余额）。

### Q: 令牌过期了？

控制台 → 令牌 → 编辑 → 改 "过期时间"。默认永不过期。

---

## 模型 / 分组

### Q: gpt-vip 分组怎么不能用了？

`gpt-vip` 是老分组。新建令牌选 `gpt-plus` 或 `gpt-pro`：

- `gpt-plus`：覆盖日常 GPT / Codex 场景，**大多数人选这个**
- `gpt-pro`：高阶 GPT 资源池，适合长上下文、记忆和重度任务

具体价格配置以 **模型广场** 当前展示为准。

### Q: claude-vip 和 claude 特惠区别？

- `claude-vip`：Claude 全量资源池，通常包含 opus / sonnet / haiku
- `claude 特惠`：Claude 常用资源池，通常覆盖 sonnet / haiku，不含 opus

日常用 sonnet/haiku → 优先看 `claude 特惠`。要 opus → 看 `claude-vip`。具体可用模型和价格以 **模型广场** 当前展示为准。

### Q: 我能不能两个 group 都用？

可以。建两个令牌：

- `claude-code-mac` 选 `claude-vip` → 给 Claude Code 用
- `codex-mac` 选 `gpt-plus` → 给 Codex 用

### Q: 怎么知道当前 group 有哪些模型？

https://beefapi.com → 顶部 nav "**模型广场**" → 左侧选 group → 右侧显示该 group 包含的所有模型、实时价格配置和描述。

### Q: model_not_found 404 怎么办？

99% 是 group 选错了。详见 [分组与模型](/docs/onboarding/groups-models) + [错误码排查](/docs/onboarding/errors)。

---

## 工具配置

### Q: Claude Code 配完报 401 / "Unable to connect to Anthropic services"

最常见原因：

1. `~/.claude/settings.json` 里 `ANTHROPIC_BASE_URL` 没设成 `https://beefapi.com`（默认是 `api.anthropic.com` 被墙）
2. 用了 `ANTHROPIC_API_KEY` 而不是 `ANTHROPIC_AUTH_TOKEN`
3. 加了 `/v1` 后缀（**不要加**）

详细修法见 [错误码排查 → "Unable to connect"](/docs/onboarding/errors)。

### Q: Codex 配完没反应 / 401

检查 `~/.codex/config.toml` 和 `~/.codex/auth.json` 两个文件都存在 + 配置对。`auth.json` 里 key 是 `OPENAI_API_KEY` 不是 `OPENAI_AUTH_TOKEN`。
base_url 必须是 `https://beefapi.com/v1`（**加 `/v1`**）。

### Q: 我能不能用其他 OpenAI Compatible 客户端？

可以，走 OpenAI Compatible 手动配置：

- Base URL：`https://beefapi.com/v1`
- API Key：你的 `sk-xxx`
- Model：`gpt-5.5` / `gpt-5.4` / 你的目标模型

Claude Code / Claude Desktop / Codex / Hermes 优先用 CC Switch；Hermes 会按 Chat Completions 导入，BeefAPI 已兼容正常对话。其他客户端直接填 Base URL 和 Key。

### Q: gpt-image-2 / Image2 怎么接？

Image2 按 OpenAI Images API 配：

- Base URL：`https://beefapi.com/v1`
- Endpoint：`POST /v1/images/generations`
- Model：`gpt-image-2`
- 令牌 group：`gpt-plus` 或 `gpt-pro`
- `n` 不填或填 `1`

详细示例见 [客户端配置 → Image2 / gpt-image-2](/docs/onboarding/clients)。

### Q: 1M context 和 200K 区别？

Claude Code 默认开 1M context，能塞超长上下文但偶尔抽风 / 慢。
要切回 200K（更稳）：`settings.json` env 加 `"CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"`。

### Q: Codex 越用越笨 / 降智？

不是模型降级，是用法问题。详见 [错误码排查 → Codex 降智](/docs/onboarding/errors)。

要点：拆任务 + 别压缩 + 60% 上下文上限 + 写好 `AGENTS.md` 全局指南。

## 网络 / 代理

### Q: 我开了梯子能用吗？

可以。但部分请求可能被代理劫持失败。建议：

- 把 `beefapi.com` 加入梯子白名单（不走代理直连）
- Clash 用户：把 MTU 改 1500（默认有时太小）

### Q: 报 "Connection failed" / SSL error

通常是本机网络 / 代理问题。先：

1. 关梯子重试
2. `curl https://beefapi.com/api/status` 测连通
3. 仍不行 → 联系在线客服并带上完整报错

---

## 计费 / 价格

### Q: 一个月大概花多少钱？

完全看用量、模型、上下文长度和输出 token，不建议按文档里的固定金额估算。

你可以这样判断：

1. 在 **模型广场** 看当前模型和 group 的实时价格配置。
2. 先小额使用几次。
3. 到 **控制台 → 日志** 看每次请求的实际扣费，再按自己的使用频率估算月用量。

### Q: 价格怎么算？

实际扣费由 **模型价格、分组价格配置、输入/输出用量** 共同决定。不要按文档里的历史数字估算，直接看 **模型广场** 当前价格配置；每次请求的实际扣费在 **控制台 → 日志** 里查看。

### Q: 我能不能预付费包月？

目前主要是按量充值。如需团队或企业方案，可以联系在线客服。

---

## 其他

### Q: BeefAPI 是谁做的？跑路风险？

独立团队长期运营。详细问题可以联系在线客服。

### Q: 数据安全？聊天会被存吗？

- BeefAPI 不存对话内容
- 仅存 metadata（模型 / token 数 / 时间 / 扣费）做账单 / 日志
- key 加密存数据库
- 部分上游可能存（OpenAI / Anthropic 自己），看具体上游 ToS

### Q: 能不能私有部署？

联系在线客服，说明具体需求和使用规模。

### Q: 联系方式

- QQ 群：**912022855**（加群后私信群主，领取5 元体验额度）
- 邮件反馈：进控制台 → 个人设置 → "联系客服"

---

## 没找到答案？

联系在线客服时，带上：

- 你用什么工具（Claude Code / Codex / Cherry Studio / ...）
- 你的 base URL + group + model
- 报错完整截图 / JSON
- 你已经尝试过的修复步骤

信息越完整，定位越快。