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

# 在 Gemini CLI 中使用 BeatAPI

> 两个环境变量把 Gemini CLI 指向 BeatAPI，用 BeatAPI 余额调用 Gemini 系列模型。

# 在 Gemini CLI 中使用 BeatAPI

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

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

## 准备工作

1. **已安装 Node.js 与 npm** —— v16 及以上。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：安装 Gemini CLI

```bash
npm install -g @google/gemini-cli
```

确认安装成功：

```bash
gemini --version
```

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

## 第二步：指向 BeatAPI

两个变量就够了。

### 持久生效（推荐）

#### macOS (zsh)

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

#### Linux (bash)

```bash
echo 'export GEMINI_API_KEY="<BEATAPI_API_KEY>"' >> ~/.bashrc
echo 'export GEMINI_BASE_URL="https://api.beatapi.io"' >> ~/.bashrc
source ~/.bashrc
```

#### Windows (PowerShell)

```powershell
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', '<BEATAPI_API_KEY>', 'User')
[System.Environment]::SetEnvironmentVariable('GEMINI_BASE_URL', 'https://api.beatapi.io', 'User')
```

之后重启 PowerShell。

### 仅当前终端

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

### 用 .env 文件

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

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

### 确认变量已生效

```bash
echo $GEMINI_API_KEY
echo $GEMINI_BASE_URL
```

## 第三步：开始使用

交互会话：

```bash
gemini
```

单次提问：

```bash
gemini "概括这个仓库的架构"
```

明确指定模型：

```bash
gemini --model gemini-3.1-pro-preview
```

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

## 模型

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

价格见[价目页](https://beatapi.io/pricing)，请求结构见 [Gemini API](/text-api/gemini/native)。

## 在代码里调用同样的模型

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

```python
from openai import OpenAI

client = OpenAI(
    api_key="<BEATAPI_API_KEY>",
    base_url="https://api.beatapi.io/v1",
)

response = client.chat.completions.create(
    model="gemini-3.7-flash",
    messages=[{"role": "user", "content": "解释这段错误堆栈"}],
)

print(response.choices[0].message.content)
```

```bash
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": "解释这段错误堆栈"}]
  }'
```

## 常见问题

### 鉴权失败

1. 确认两个变量在你启动 `gemini` 的那个终端里都已设置：

   ```bash
   echo $GEMINI_API_KEY
   echo $GEMINI_BASE_URL
   ```

2. 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认密钥仍然可用。

### 每个请求都返回 404

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

### 模型列表是空的

用 `--model` 直接指定模型即可。账户可用的模型也可以从 [`GET /v1/models`](/text-api) 或[价目页](https://beatapi.io/pricing)获取。

### 402 insufficient_credits

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

### 429 rate_limit_exceeded

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

### 连不上

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

## 获取支持

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