Gemini API
Google Gemini의 네이티브 요청 형식을 그대로 받는 엔드포인트입니다. OpenAI 호환 형식으로 바꾸지 않고, Google SDK나 Gemini CLI가 보내는 본문을 그대로 보냅니다.
OpenAI 호환 경로(
/chat/completions/)로도 Gemini 모델을 쓸 수 있지만, 네이티브 경로에서만 되는 것이 있습니다. 검색 기반 응답(google_search), 안전 설정, 그리고 thoughtSignature 보존입니다. 마지막 항목은 도구를 연달아 호출하는 에이전트에서 특히 중요합니다 — 이 값이 유실되면 두 번째 도구 호출부터 실패합니다.엔드포인트
| Method | Path | 설명 |
|---|---|---|
| GET | /v1/gateway/gemini/v1beta/models | 사용 가능한 Gemini 모델 목록 |
| POST | /v1/gateway/gemini/v1beta/models/{model}:generateContent | 응답 생성 |
| POST | /v1/gateway/gemini/v1beta/models/{model}:streamGenerateContent | 스트리밍 응답 생성 |
| POST | /v1/gateway/gemini/v1beta/models/{model}:countTokens | 토큰 수 계산 (무료) |
인증
Gemini SDK와 CLI가 쓰는 헤더를 그대로 받습니다. 둘 다 동작합니다.
키는 베이즈 API 키입니다. Google AI Studio 키가 아닙니다.
요청
응답
thoughtsTokenCount는 모델이 내부적으로 생각하는 데 쓴 토큰입니다. 출력 토큰 단가로 과금됩니다. 위 예시에서 실제 답변은 7토큰이지만 전체는 202토큰입니다 — 사고 과정이 비용의 대부분을 차지할 수 있다는 뜻입니다.웹 검색 (google_search)
tools에 google_search를 넣으면 모델이 검색해서 답합니다.응답에
groundingMetadata가 함께 오며, 여기에 실제로 사용한 검색어(webSearchQueries)와 출처(groundingChunks)가 담깁니다. 검색은 별도로 과금됩니다.스트리밍
:streamGenerateContent에 ?alt=sse를 붙이면 SSE로 받습니다.토큰 계산은 무료입니다
:countTokens는 모델을 호출하지 않으므로 크레딧이 차감되지 않습니다. 긴 프롬프트를 보내기 전에 비용을 가늠할 때 쓰세요.Gemini CLI 연동
이 경로는 Gemini CLI가 기대하는 형식과 같으므로, 베이스 URL만 바꾸면 그대로 붙습니다.
GOOGLE_GEMINI_BASE_URL에 /v1beta까지 넣지 마세요. CLI가 뒤에 경로를 스스로 붙이므로 .../v1beta/v1beta/...가 되어 404가 납니다.자세한 설정은 Gemini CLI 연동 가이드를 참고하세요.
알아 두면 좋은 것
- 목록에 나오는 모델만 호출할 수 있습니다. 조직에서 허용하지 않은 모델은
403입니다. - 이 경로는 Gemini 모델 전용입니다. 다른 제공사 모델은
/chat/completions/를 쓰세요. - 과금은 OpenAI 호환 경로와 동일합니다 — 입력·출력 토큰 기준이며, 사고 토큰은 출력 단가로 계산합니다.
마지막 수정 날짜: Sep 18, 2026