> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 在 Cursor 中使用 BeatAPI

> 在 Cursor 的模型设置里覆盖 OpenAI 地址，让对话与行内编辑都跑在 BeatAPI 上。

# 在 Cursor 中使用 BeatAPI

Cursor 是一个 AI 代码编辑器。它的模型设置接受 OpenAI 兼容端点，所以填入 BeatAPI 即可，不需要任何插件。

## 准备工作

1. **已安装 Cursor。**
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：打开模型设置

打开设置 —— 右上角齿轮图标，或 macOS 上按 `Cmd+Shift+J`、Windows 与 Linux 上按 `Ctrl+Shift+J` —— 然后在侧栏选择 **Models**。

## 第二步：指向 BeatAPI

找到 **OpenAI API Key** 区域，勾选 **Override OpenAI Base URL**，然后填写：

| 配置项      | 值                           |
| -------- | --------------------------- |
| API Key  | 你的 BeatAPI 密钥               |
| Base URL | `https://api.beatapi.io/v1` |

保存。Cursor 会先验证端点再接受配置。

> **Note**
>
> Base URL 必须带 `/v1`，且后面什么都不加。多一个斜杠或多一段路径会让每个请求都 404，而 Cursor 会把它显示成「连接失败」，不会告诉你是地址写错了。

## 第三步：添加你要用的模型

Cursor 自己维护一份模型列表，列表里有不代表你的账户能调。请按编号手工添加下表中的模型，并且**只启用这些** —— 账户不提供的模型会在第一次调用时返回 `not_found`。

| 模型编号                        | 适用场景             |
| --------------------------- | ---------------- |
| `claude-fable-5-1`          | 最新一代 —— 智能体式编辑最强 |
| `claude-sonnet-5`           | 日常工作，质量与速度均衡     |
| `gpt-5.6-sol`               | OpenAI 系最强编程档    |
| `gpt-5.6-luna`              | 快速便宜，适合大量补全      |
| `claude-haiku-4-5-20251001` | 延迟与成本都最低         |

Cursor 支持给不同功能配不同模型 —— 对话、行内编辑（`Cmd+K`）、代码补全。**给补全配便宜模型、给对话配强模型，是最能省钱的一招**，因为补全触发的次数远高于对话。

## 第四步：开始使用

* **对话** —— `Cmd+L` / `Ctrl+L`，提问或描述任务。
* **行内编辑** —— 选中代码，按 `Cmd+K` / `Ctrl+K`，描述要改成什么样。
* **代码补全** —— 正常输入，按 `Tab` 采纳建议。

用 `@文件名` 引用文件、`@目录名` 引用目录，让模型看到该看的上下文，而不是从当前缓冲区猜。

## 常见问题

### Cursor 连不上 BeatAPI

1. Base URL 必须恰好是 `https://api.beatapi.io/v1`。
2. 密钥必须处于可用状态 —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认。
3. 若走公司代理，需放行 `api.beatapi.io`。

### 列表里的某个模型用不了

那份列表是 Cursor 自己的。只有账户实际提供的编号才会响应，当前目录见[价目页](https://beatapi.io/pricing)。

### 402 insufficient_credits

余额不足：余额为零或低于本次请求的价格，在控制台充值。

### 429 rate_limit_exceeded

该密钥超出请求频率上限。通常是补全造成的 —— 它几乎每次停顿都会触发。把补全换成便宜模型，或提升额度；每分钟额度随累计充值提升，当前值在控制台可见。

### 响应很慢

补全和行内编辑用轻量模型，选区尽量小，并优先用 `@文件` 引用而不是粘贴大段代码。

## 获取支持

在[控制台](https://beatapi.io/dashboard)提交工单，并附上失败响应里的 `request_id`。