> 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 を使う

> 2 つの環境変数で Gemini CLI を BeatAPI に接続し、BeatAPI の残高で Gemini モデルを利用します。

# Gemini CLI で BeatAPI を使う

Gemini CLI は Gemini モデル向けのターミナルクライアントです。BeatAPI が直接提供するネイティブ Gemini プロトコル `POST /v1beta/models/{model}:generateContent` を使うため、変換層は不要で、ベース URL の変更だけで接続できます。

> **Note**
>
> ベース URL は**ネイティブ**の Gemini プロトコルに対応している必要があります。CLI は `/chat/completions` ではなく `{base}/v1beta/models/{model}:{action}` を呼ぶため、OpenAI 互換エンドポイントだけでは利用できません。ネイティブの接続先 `https://api.beatapi.io` を、パスを付けずにそのまま指定してください。

## 前提条件

1. **Node.js と npm。** v16 以降が必要です。
2. **BeatAPI API キー。** [ダッシュボード → API キー](https://beatapi.io/dashboard/apikeys)で作成します。

## ステップ 1：Gemini CLI をインストールする

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

インストールを確認します。

```bash
gemini --version
```

コマンドが見つからない場合は、ターミナルを再起動するか、npm のグローバル `PATH` を確認します。

## ステップ 2：BeatAPI を指定する

必要な設定は 2 つの変数だけです。

### 永続的な設定（推奨）

#### 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
```

## ステップ 3：利用する

対話セッションを開始します。

```bash
gemini
```

単発のプロンプトを送信します。

```bash
gemini "Summarise the architecture of this repository"
```

モデルを明示的に選びます。

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

> **Note**
>
> CLI の初期モデルに任せず、モデル名を明示してください。アカウントにないモデルが初期値だと `not_found` になります。モデルを固定すると、CLI の更新で気付かないうちに別の料金へ切り替わることも防げます。

## モデル

| モデル ID                   | 用途                      |
| ------------------------ | ----------------------- |
| `gemini-3.1-pro-preview` | 最も高性能。難しい推論と長い分析        |
| `gemini-3.7-flash`       | 現在の高速モデル。日常作業と大量処理      |
| `gemini-3.6-flash`       | 固定した連携向けに維持される前世代の高速モデル |

料金は[料金ページ](https://beatapi.io/pricing)、リクエスト形式は [Gemini API](/text-api/gemini) を参照してください。

## 同じモデルをコードから呼び出す

Gemini 互換エンドポイントは BeatAPI が提供する 4 つの形式の 1 つです。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": "Explain this stack trace"}],
)

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": "Explain this stack trace"}]
  }'
```

## よくある質問

### 認証エラー

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

残高が 0、またはリクエストの料金に不足しています。ダッシュボードからチャージしてください。

### 429 rate\_limit\_exceeded

キーのリクエスト数が上限を超えました。`Retry-After` に従ってください。毎分の上限はチャージ累計額に応じて増え、ダッシュボードに表示されます。

### 接続に失敗します

ネットワーク接続を確認し、`GEMINI_BASE_URL` の誤字を確認します。社内プロキシでは `api.beatapi.io` への通信を許可してください。

## サポート

[ダッシュボード](https://beatapi.io/dashboard)からチケットを作成し、失敗したレスポンスの `request_id` を添えてください。