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

# Using BeatAPI in Gemini CLI

> Point Gemini CLI at BeatAPI with two environment variables and run the Gemini models on your BeatAPI balance.

# Using BeatAPI in Gemini CLI

Gemini CLI is a terminal client for the Gemini models. It speaks the native Gemini protocol — `POST /v1beta/models/{model}:generateContent` — which BeatAPI serves directly, so redirecting it is a base-URL change with no translation layer in between.

> **Note**
>
> The base URL has to speak the **native** Gemini protocol. An OpenAI-compatible endpoint will not work here, because the CLI addresses models as `{base}/v1beta/models/{model}:{action}` rather than `/chat/completions`. `https://api.beatapi.io` is the native address; use it exactly, with no path suffix.

## Prerequisites

1. **Node.js and npm** — v16 or newer.
2. **A BeatAPI API key** — create one in [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys).

## Step 1: Install Gemini CLI

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

Confirm the install:

```bash
gemini --version
```

If the command is not found, restart the terminal or check your npm global `PATH`.

## Step 2: Point it at BeatAPI

Two variables do the whole job.

### Persistent (recommended)

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

Restart PowerShell afterwards.

### One terminal only

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

### From a .env file

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

Add `.env` to `.gitignore` so the key is never committed.

### Verify the values landed

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

## Step 3: Use it

Interactive session:

```bash
gemini
```

One-shot prompt:

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

Pick a model explicitly:

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

> **Note**
>
> Name the model explicitly rather than relying on whatever default the CLI ships with. A default that is not on your account produces a `not_found`, and pinning it also stops a CLI upgrade from silently moving you onto a different rate.

## Models

| Model ID                 | Choose it for                                              |
| ------------------------ | ---------------------------------------------------------- |
| `gemini-3.1-pro-preview` | The strongest tier — hard reasoning and long analysis      |
| `gemini-3.7-flash`       | The current fast tier for everyday work and high volume    |
| `gemini-3.6-flash`       | The previous fast generation, kept for pinned integrations |

Rates are on the [pricing page](https://beatapi.io/pricing); the [Gemini API](/text-api/gemini/native) page documents the request shape.

## Calling the same models from code

The Gemini-compatible endpoint is one of four formats BeatAPI serves, so you are not restricted to the native shape once you leave the 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"}]
  }'
```

## FAQ

### Authentication errors

1. Confirm both variables are set in the terminal you launched `gemini` from:

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

2. Confirm the key is active in [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys).

### 404 on every request

`GEMINI_BASE_URL` must be `https://api.beatapi.io` — no `/v1`, no `/v1beta`, no trailing slash. The CLI appends the rest of the path itself; adding it yourself produces `/v1/v1beta/models/...`, which does not exist.

### The model list is empty

Name the model with `--model` instead of picking from a list. The account's models are also available from [`GET /v1/models`](/text-api) and on the [pricing page](https://beatapi.io/pricing).

### 402 insufficient_credits

Insufficient balance: the balance is zero or below the price of the request. Top up from the dashboard.

### 429 rate_limit_exceeded

The key exceeded its request rate. Honour `Retry-After`. The per-minute allowance rises with lifetime top-ups and is shown on the dashboard.

### Connection failures

Check general connectivity, then re-check `GEMINI_BASE_URL` for a typo. Behind a corporate proxy, allow `api.beatapi.io`.

## Support

Open a support ticket from the [dashboard](https://beatapi.io/dashboard) and include the `request_id` from the failing response.