Gemini CLI에서 BeatAPI 사용하기

Gemini CLI는 Gemini 모델용 터미널 클라이언트입니다. BeatAPI가 직접 제공하는 네이티브 Gemini 프로토콜(POST /v1beta/models/{model}:generateContent)을 사용하므로, 변환 계층 없이 기본 URL만 바꾸면 됩니다.

기본 URL은 네이티브 Gemini 프로토콜을 지원해야 합니다. CLI는 모델을 /chat/completions가 아니라 {base}/v1beta/models/{model}:{action} 형식으로 호출하므로 OpenAI 호환 엔드포인트로는 동작하지 않습니다. https://api.beatapi.io가 네이티브 주소이며, 경로 접미사 없이 그대로 사용하세요.

사전 준비

Node.js와 npm — v16 이상.
BeatAPI API 키 — 대시보드 → API Keys에서 만드세요.

1단계: Gemini CLI 설치

npm install -g @google/gemini-cli

설치를 확인합니다.

gemini --version

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

2단계: BeatAPI로 연결

변수 두 개면 충분합니다.

영구 설정(권장)

macOS (zsh)

Linux (bash)

Windows (PowerShell)

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

현재 터미널에서만

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

.env 파일에서

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

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

값이 적용되었는지 확인

echo $GEMINI_API_KEY
echo $GEMINI_BASE_URL

3단계: 사용하기

대화형 세션:

gemini

단발형 프롬프트:

gemini "Summarise the architecture of this repository"

모델을 직접 지정:

gemini --model gemini-3.1-pro-preview

CLI에 기본으로 들어 있는 값에 의존하지 말고 모델을 직접 지정하세요. 계정에 없는 기본 모델은 not_found를 일으키며, 모델을 고정해 두면 CLI 업그레이드로 요금이 다른 모델로 조용히 바뀌는 일도 막을 수 있습니다.

모델

모델 ID	추천 용도
`gemini-3.1-pro-preview`	가장 강력한 등급. 어려운 추론과 긴 분석
`gemini-3.7-flash`	일상 작업과 대량 처리를 위한 현재의 빠른 등급
`gemini-3.6-flash`	이전 세대의 빠른 등급. 버전을 고정한 연동을 위해 유지

요금은 가격 페이지에, 요청 형식은 Gemini API 페이지에 있습니다.

코드에서 같은 모델 호출하기

Gemini 호환 엔드포인트는 BeatAPI가 제공하는 네 가지 형식 중 하나이므로, CLI 밖에서는 네이티브 형식만 쓸 필요가 없습니다.

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)

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"}]
  }'

자주 묻는 질문

인증 오류

gemini를 실행한 터미널에 두 변수가 모두 설정되어 있는지 확인하세요.
```
echo $GEMINI_API_KEY
echo $GEMINI_BASE_URL
```
대시보드 → API Keys에서 키가 활성 상태인지 확인하세요.

모든 요청에서 404 발생

GEMINI_BASE_URL은 https://api.beatapi.io여야 합니다. /v1, /v1beta, 끝 슬래시를 붙이지 마세요. CLI가 나머지 경로를 직접 덧붙이므로, 직접 추가하면 존재하지 않는 /v1/v1beta/models/...가 됩니다.

모델 목록이 비어 있음

목록에서 고르지 말고 --model로 모델을 지정하세요. 계정의 모델은 GET /v1/models와 가격 페이지에서도 확인할 수 있습니다.

402 insufficient_credits

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

429 rate_limit_exceeded

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

연결 실패

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

지원

대시보드에서 지원 티켓을 열고 실패한 응답의 request_id를 함께 보내 주세요.