在 Gemini CLI 中使用 BeatAPI

Gemini CLI 是 Gemini 系列模型的终端客户端。它说的是原生 Gemini 协议 —— POST /v1beta/models/{model}:generateContent —— BeatAPI 直接提供该协议，所以改向它只需换个地址，中间没有任何转换层。

这里的地址必须支持原生 Gemini 协议，OpenAI 兼容端点在这里用不了：CLI 访问模型的路径是 {地址}/v1beta/models/{模型}:{动作}，而不是 /chat/completions。原生地址就是 https://api.beatapi.io，照抄即可，后面不要加任何路径。

准备工作

已安装 Node.js 与 npm —— v16 及以上。
一把 BeatAPI 密钥 —— 在控制台 → API 密钥创建。

第一步：安装 Gemini CLI

$ npm install -g @google/gemini-cli

确认安装成功：

$ gemini --version

提示找不到命令时，重启终端或检查 npm 全局 PATH 配置。

第二步：指向 BeatAPI

两个变量就够了。

持久生效（推荐）

macOS (zsh)

Linux (bash)

Windows (PowerShell)

$ echo 'export GEMINI_API_KEY="<BEATAPI_API_KEY>"' >> ~/.zshrc
$ echo 'export GEMINI_BASE_URL="https://api.beatapi.io"' >> ~/.zshrc
$ source ~/.zshrc

仅当前终端

$ export GEMINI_API_KEY="<BEATAPI_API_KEY>"
$ export GEMINI_BASE_URL="https://api.beatapi.io"
$ gemini

用 .env 文件

$ # .env
$ GEMINI_API_KEY=<BEATAPI_API_KEY>
$ GEMINI_BASE_URL=https://api.beatapi.io

把 .env 加进 .gitignore，密钥就不会被提交。

确认变量已生效

$ echo $GEMINI_API_KEY
$ echo $GEMINI_BASE_URL

第三步：开始使用

交互会话：

$ gemini

单次提问：

$ gemini "概括这个仓库的架构"

明确指定模型：

$ gemini --model gemini-3.1-pro-preview

请显式指定模型，不要依赖 CLI 自带的默认值。默认模型若不在你的账户内会直接返回 not_found；固定写死也能避免 CLI 升级后悄悄换到另一个价格档位上。

模型

模型编号	适用场景
`gemini-3.1-pro-preview`	最强档，适合高难推理与长文分析
`gemini-3.7-flash`	当前快速档，适合日常与大批量任务
`gemini-3.6-flash`	上一代快速档，供已固定版本的集成继续使用

价格见价目页，请求结构见 Gemini API。

在代码里调用同样的模型

Gemini 兼容端点只是 BeatAPI 支持的四种格式之一，离开 CLI 后不必局限于原生结构。

1 from openai import OpenAI
2 
3 client = OpenAI(
4     api_key="<BEATAPI_API_KEY>",
5     base_url="https://api.beatapi.io/v1",
6 )
7 
8 response = client.chat.completions.create(
9     model="gemini-3.7-flash",
10     messages=[{"role": "user", "content": "解释这段错误堆栈"}],
11 )
12 
13 print(response.choices[0].message.content)

$ curl https://api.beatapi.io/v1/chat/completions \
>   -H "Authorization: Bearer <BEATAPI_API_KEY>" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gemini-3.7-flash",
>     "messages": [{"role": "user", "content": "解释这段错误堆栈"}]
>   }'

常见问题

鉴权失败

确认两个变量在你启动 gemini 的那个终端里都已设置：
```
$ echo $GEMINI_API_KEY
$ echo $GEMINI_BASE_URL
```
在控制台 → API 密钥确认密钥仍然可用。

每个请求都返回 404

GEMINI_BASE_URL 必须是 https://api.beatapi.io —— 不带 /v1，不带 /v1beta，结尾不加斜杠。CLI 会自己拼后面的路径；你自己加上会变成 /v1/v1beta/models/...，这个路径不存在。

模型列表是空的

用 --model 直接指定模型即可。账户可用的模型也可以从 GET /v1/models 或价目页获取。

402 insufficient_credits

余额已用尽，在控制台充值。

429 rate_limit_exceeded

该密钥超出请求频率上限。按 Retry-After 等待。每分钟额度随累计充值提升，当前值在控制台可见。

连不上

先检查网络，再复查 GEMINI_BASE_URL 有没有拼错。若走公司代理，需放行 api.beatapi.io。

获取支持

在控制台提交工单，并附上失败响应里的 request_id。