> 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.

# 在沉浸式翻译中使用 BeatAPI

> 在沉浸式翻译浏览器插件中把 BeatAPI 添加为自定义翻译服务，用于双语网页、PDF 与视频字幕。

# 在沉浸式翻译中使用 BeatAPI

沉浸式翻译可以把网页、PDF 与视频字幕渲染成双语对照。它支持任意 OpenAI 兼容端点作为自定义翻译服务，所以 BeatAPI 可以直接驱动它。

## 准备工作

1. **已安装插件** —— 从 Chrome 应用商店、Edge 扩展、Firefox 附加组件或官网安装。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：打开设置

点浏览器工具栏中的沉浸式翻译图标，再点弹窗左下角的**设置**，然后在左侧菜单选择**翻译服务**。

## 第二步：添加为自定义服务

点列表顶部的 **+ 添加自定义翻译服务**，填写：

| 字段           | 值                                            |
| ------------ | -------------------------------------------- |
| 自定义翻译服务名称    | `BeatAPI`                                    |
| APIKEY       | 你的 BeatAPI 密钥                                |
| 模型           | 模型编号，例如 `glm-5.3-flash`                      |
| 自定义 API 接口地址 | `https://api.beatapi.io/v1/chat/completions` |
| 每秒最大请求数      | `3`–`5`                                      |

> **Note**
>
> 这个字段要填**完整的接口地址**，不是基础地址 —— 必须是 `https://api.beatapi.io/v1/chat/completions`，带上完整路径。本站所有集成教程里，只有这一处填 `https://api.beatapi.io/v1` 是错的。

保存后回到插件弹窗，在翻译服务下拉里选择 **BeatAPI**。

## 第三步：开始翻译

* **整页翻译** —— 点插件图标选择翻译，或按 `Alt+A`。
* **PDF 翻译** —— 在浏览器中打开在线 PDF 后按 `Alt+A`。本地文件需要先在网页阅读器中打开。
* **视频字幕** —— 在支持的平台播放视频，双语字幕会自动出现。
* **划词翻译** —— 选中文本后使用划词面板，默认快捷键 `Alt+W`。

## 怎么选模型

翻译是大多数人会跑的**量最大、最重复**的任务。整页翻译会拆成很多小请求，所以在这里选模型对账单的影响比在别处都大。

| 模型编号                     | 适用场景                 |
| ------------------------ | -------------------- |
| `glm-5.3-flash`          | 日常浏览 —— 翻译质量够用的最便宜档位 |
| `gemini-3.7-flash`       | 快，多语种表现好             |
| `qwen3.8-flash`          | 中文页面                 |
| `deepseek-v4-flash-0731` | 便宜且能力不弱，适合大批量        |
| `claude-sonnet-5`        | 文学与创意文本，注重语感         |
| `gpt-5.6-terra`          | 技术与学术文档              |

完整目录见[文本 API](/text-api) 各页与[价目页](https://beatapi.io/pricing)。

> **Note**
>
> 常规付费 DeepSeek 模型（包括 `deepseek-v4-flash-0731`）全天同一价。只有 DeepSeek 的两个高缓存版（HC）模型在工作日北京时间 09:00–12:00、14:00–18:00 翻倍；如果你常在工作日白天大量浏览，用它们之前先确认价格。具体时段见[价目页](https://beatapi.io/pricing)脚注。

## 常见问题

### 配置完不翻译

1. 确认插件弹窗的翻译服务下拉里**选中的是 BeatAPI**，光在设置里保存不算。
2. 接口地址必须是完整路径 `https://api.beatapi.io/v1/chat/completions`。
3. 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认密钥仍然可用。
4. 模型编号区分大小写。

### 翻译很慢或超时

先把**每秒最大请求数**降到 `3`。一个页面会扇出很多并发请求，卡住的通常是请求频率而不是模型。然后再换成更快的档位，例如 `glm-5.3-flash` 或 `gemini-3.7-flash`。

### 429 rate_limit_exceeded

和上一条同源，只是更进一步。先降每秒请求数；账户的每分钟额度随累计充值提升，当前值在控制台可见。

### 翻译质量不理想

换到更高档位 —— 散文用 `claude-sonnet-5`，技术文档用 `gpt-5.6-terra` —— 并把「AI 专家」风格调成与内容匹配。对反复出现的专业术语，请配置插件的术语表，这能解决换更大模型也解决不了的一致性问题。

### 402 insufficient_credits

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

### 怎么看它花了多少

给插件单独发一把 BeatAPI 密钥。浏览会产生大量零碎小请求，用独立密钥就能在 [`GET /v1/usage`](/quick-guide) 的 `by_api_key` 和控制台里，把它和应用流量分开看。

## 获取支持

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