> 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 모델용 터미널 클라이언트입니다. 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 Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요.

## 1단계: Gemini CLI 설치

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

설치를 확인합니다.

```bash
gemini --version
```

명령을 찾을 수 없다면 터미널을 다시 시작하거나 npm 전역 `PATH`를 확인하세요.

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

키가 커밋되지 않도록 `.gitignore`에 `.env`를 추가하세요.

### 값이 적용되었는지 확인

```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/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": "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 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

잔액 부족: 잔액이 0이거나 요청 가격보다 적습니다. 대시보드에서 충전하세요.

### 429 rate_limit_exceeded

키의 요청 속도 한도를 넘었습니다. `Retry-After`를 따르세요. 분당 한도는 누적 충전액에 따라 올라가며 대시보드에 표시됩니다.

### 연결 실패

전반적인 네트워크 연결을 확인한 다음 `GEMINI_BASE_URL`에 오타가 없는지 다시 확인하세요. 회사 프록시를 사용한다면 `api.beatapi.io`를 허용하세요.

## 지원

[대시보드](https://beatapi.io/dashboard)에서 지원 티켓을 열고 실패한 응답의 `request_id`를 함께 보내 주세요.