> 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 к Gemini CLI

> Подключите Gemini CLI к BeatAPI двумя переменными окружения и оплачивайте работу моделей Gemini с баланса BeatAPI.

# Подключение BeatAPI к Gemini CLI

Gemini CLI — терминальный клиент для моделей Gemini. Он использует нативный API Gemini — `POST /v1beta/models/{model}:generateContent`, который BeatAPI поддерживает напрямую. Для подключения достаточно изменить базовый адрес API; промежуточное преобразование не требуется.

> **Note**
>
> Адрес должен поддерживать **нативный API Gemini**. OpenAI-совместимый метод здесь не подойдёт: CLI обращается к `{base}/v1beta/models/{model}:{action}`, а не к `/chat/completions`. Используйте `https://api.beatapi.io` точно в таком виде, без дополнительного пути.

## Что понадобится

1. **Node.js и npm**: v16 или новее.
2. **API-ключ BeatAPI**: создайте его в [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys).

## Шаг 1. Установите Gemini CLI

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

Проверьте установку:

```bash
gemini --version
```

Если команда не найдена, перезапустите терминал или проверьте глобальный `PATH` npm.

## Шаг 2. Подключите 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
```

## Шаг 3. Начните работу

Интерактивная сессия:

```bash
gemini
```

Один запрос:

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

Явный выбор модели:

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

> **Note**
>
> Указывайте модель явно, не полагаясь на модель по умолчанию в CLI. Если она недоступна аккаунту, запрос вернёт `not_found`. Явный ID также не позволит обновлению CLI незаметно переключить вас на другой тариф.

## Модели

| ID модели                | Для каких задач подходит                                                    |
| ------------------------ | --------------------------------------------------------------------------- |
| `gemini-3.1-pro-preview` | Самый сильный вариант для сложных рассуждений и глубокого анализа           |
| `gemini-3.7-flash`       | Актуальная быстрая модель для повседневной работы и большого числа запросов |
| `gemini-3.6-flash`       | Предыдущее быстрое поколение для интеграций с закреплённой версией          |

Тарифы есть на [странице цен](https://beatapi.io/pricing), формат запроса — в разделе [Gemini API](/text-api/gemini/native).

## Вызов тех же моделей из кода

Gemini-совместимый API — один из четырёх форматов BeatAPI. За пределами CLI вы не ограничены исходным форматом Gemini.

```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. Убедитесь, что ключ активен, в [Dashboard → API Keys](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` из ответа с ошибкой.