gemini-web2api: 웹 채팅 화면을 OpenAI 호환 API로 바꾸는 단일 파일 프록시

9bow · 7월 5, 2026, 12:30오전

gemini-web2api 소개

Google Gemini의 공식 API를 쓰려면 Google AI Studio나 Vertex AI에 가입하고 API 키를 발급받아야 하며, 사용량에 따라 과금됩니다. gemini-web2api는 이 과정을 건너뛰고, 브라우저로 접속하는 Gemini 웹 채팅 화면 자체를 OpenAI 호환 REST API처럼 쓸 수 있게 바꿔주는 파이썬 스크립트입니다. /v1/chat/completions, /v1/models 같은 OpenAI 형식 엔드포인트를 그대로 흉내 내기 때문에, OpenAI SDK나 OpenAI 호환을 지원하는 Cherry Studio·ChatBox 같은 클라이언트를 코드 수정 없이 그대로 연결할 수 있습니다.

README는 이 프로젝트를 "Google Gemini의 웹 인터페이스를 OpenAI 호환 API로 변환. 무료, 크로스 플랫폼, 단일 파일"이라고 소개합니다. 별도 설치 과정이 복잡하지 않고 httpx 하나만 있으면 실행되는 단일 파이썬 파일로 되어 있어, 로컬에서 빠르게 띄워보고 싶은 개발자에게 접근성이 높습니다. 2026년 5월 공개된 뒤 두 달 만에 GitHub에서 1,900개 이상의 스타를 받았습니다.

이 저장소의 "How It Works" 절은 동작 원리를 숨기지 않고 그대로 밝히고 있습니다. Gemini 웹 앱이 사용하는 것과 동일한 StreamGenerate 엔드포인트로 요청을 보내며, 모델 선택은 요청 페이로드의 특정 필드 값을 Gemini 프런트엔드 자바스크립트의 MODE_CATEGORY enum에서 가져와 매핑한다고 설명합니다. 즉 Google이 공식적으로 공개한 API가 아니라, 웹 페이지가 내부적으로 쓰는 비공개 프로토콜을 분석해 재현한 것입니다.

gemini-web2api의 요청 처리 흐름

클라이언트가 OpenAI 형식으로 /v1/chat/completions에 요청을 보내면, 로컬에서 실행 중인 gemini-web2api 서버가 이를 받아 Gemini 웹이 쓰는 내부 프로토콜 형식으로 변환합니다. 이 변환된 요청이 gemini.google.com으로 전송되고, 돌아온 응답은 다시 OpenAI 형식의 JSON(또는 SSE 스트림)으로 변환되어 클라이언트에 전달됩니다. 인증 없이도 대부분의 모델을 사용할 수 있지만, api_keys 설정을 채워 두면 Authorization: Bearer 헤더 기반 인증을 추가할 수 있습니다.

gemini-3.1-pro 모델은 무인증 상태에서는 Flash 모델로 자동 라우팅되며, 실제로 Pro 모델 라우팅을 받으려면 유료 구독인 Gemini Advanced 계정의 브라우저 쿠키(SID, HSID, SSID, APISID, SAPISID, __Secure-1PSID)를 추출해 cookie.txt로 넘겨야 합니다. README는 이 쿠키를 Chrome 개발자 도구의 Application 탭에서 직접 복사하는 방법을 안내하고 있습니다.

주의할 점: 이 도구는 Google이 공식 문서화하지 않은 웹 프로토콜을 분석해 동작하기 때문에, Google이 프런트엔드 구조를 바꾸면 사전 고지 없이 작동을 멈추거나 오동작할 수 있습니다. 또한 브라우저 세션 쿠키를 서버 설정 파일에 담아 사용하는 방식은 Google 서비스 약관이 허용하는 사용 범위를 벗어날 가능성이 있으므로, 이 프로젝트를 실제로 사용할지 여부와 계정 정지 등의 위험은 사용자 스스로 판단해야 합니다.

gemini-web2api의 기능과 한계

README가 명시하는 기능은 다음과 같습니다.

선택적 API 키: api_keys를 비워 두면 인증 없이, 값을 채우면 OpenAI 방식의 Bearer 인증으로 동작합니다.
OpenAI 호환: /v1/chat/completions, /v1/models를 그대로 대체할 수 있습니다.
툴 콜링: OpenAI 형식의 함수 호출(Function Calling)을 지원합니다.
다양한 모델: Flash, Flash Thinking(2만자 이상 출력), Pro, Auto, Lite 모델을 제공합니다.
사고 깊이 조절: 모델 이름 뒤에 @think=N을 붙여 사고 깊이를 0(가장 깊음)부터 4(가장 얕음)까지 조절할 수 있습니다.
웹 검색: Gemini 자체의 인터넷 검색 기능을 그대로 활용합니다.
Codex CLI·Gemini CLI 호환: /v1/responses로 OpenAI Codex CLI를, /v1beta/models로 Gemini CLI를 각각 지원합니다.

README는 한계도 함께 밝히고 있습니다. 이미지 업로드는 Gemini의 독자적인 스트리밍 RPC 프로토콜(WIZ/ProcessFile)을 복제할 수 없어 지원하지 않으며, 메시지에 이미지가 포함되면 무시된다는 안내와 함께 처리됩니다. 유료 구독 쿠키 없이는 gemini-3.1-pro도 실제로는 Flash 모델로 응답하고, 각 요청은 독립된 대화로 처리되어 멀티턴 맥락은 이전 메시지를 프롬프트에 포함시켜 흉내 내는 방식입니다. Google이 높은 빈도의 요청을 차단할 수 있어 지속적인 대량 사용은 제한될 수 있다고도 명시합니다.

gemini-web2api 설치 및 사용법

의존성은 스트리밍에 쓰이는 httpx 하나뿐입니다.

pip install httpx
python gemini_web2api.py

서버는 http://localhost:8081/v1에서 시작됩니다. OpenAI Python SDK로 바로 연결해 쓸 수 있습니다.

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8081/v1", api_key="sk-your-key")
resp = client.chat.completions.create(
    model="gemini-3.5-flash-thinking",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)
print(resp.choices[0].message.content)

Docker로도 실행할 수 있습니다.

cp config.example.json config.json
docker build -t gemini-web2api .
docker run -d --name gemini-web2api -p 8081:8081 -v ./config.json:/app/config.json gemini-web2api

gemini.google.com에 직접 접속할 수 없는 환경이라면 --proxy 인자나 config.json의 proxy 필드, 또는 HTTPS_PROXY 환경 변수로 프록시를 지정할 수 있습니다.

gemini-web2api의 라이선스

gemini-web2api는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

gemini-web2api 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~