zhiyu1998/Gemi2Api-Server

Gemi2Api‑Server – Google Gemini를 위한 경량 셀프 호스팅 프록시

무엇인가요

• unofficial Google Gemini 웹 API(Gemini‑API 프로젝트에서 사용하는 것과 동일한 API)로 요청을 전달하는 작은 FastAPI 서비스입니다. 기존 클라이언트가 Google의 공식 SDK를 사용하지 않고도 Gemini와 통신할 수 있도록 OpenAI /v1/chat/completions 엔드포인트를 모방합니다.
• 서비스 상태를 확인하고, 필요한 Gemini 쿠키를 편집하고, API 키를 변경하고, 채팅 테스트를 할 수 있는 내장 관리 UI가 포함되어 있습니다.

존재 이유

• Google Gemini는 (이 글을 작성하는 시점 기준으로) 공개된 유료 API를 제공하지 않습니다. 프로그래밍 방식으로 호출하는 유일한 방법은 웹 UI를 역공학하여 브라우저가 보내는 것과 동일한 HTTP 요청을 보내는 것입니다. 이 저장소는 해당 역공학된 클라이언트(gemini‑webapi)를 재사용 가능한 서버로 패키징합니다.
• 표준 OpenAI 호환 엔드포인트를 노출함으로써, 개발자는 Gemini를 ChatGPT 스타일의 서비스에 대한 드롭인 대체제로 사용할 수 있습니다.

작동 방식

1. 인증 – 로그인된 Gemini 세션이 생성하는 두 개의 쿠키(__Secure-1PSID 및 __Secure-1PSIDTS)를 제공해야 합니다. README에서 브라우저의 개발자 도구를 사용하여 이를 추출하는 방법을 설명합니다.
2. FastAPI + Uvicorn – 서버는 FastAPI 앱(main.py)을 실행합니다. /v1/models로의 요청은 사용 가능한 Gemini 모델 목록을 반환하며, /v1/chat/completions로의 POST 요청은 페이로드를 Gemini 웹 엔드포인트로 전달하고 OpenAI 형식으로 응답을 반환합니다.
3. 커스텀 모델 정의 – 선택 사항인 custom_models.yaml을 통해 모델 항목을 재정의하거나 추가할 수 있으며, 이를 통해 Gemini가 기대하는 요청 헤더(x-goog-ext‑…‑jspb)를 변경할 수 있습니다.
4. 이미지 프록시 – Gemini가 생성된 이미지 URL을 반환할 때, 서버는 /gemini‑proxy/image를 통해 이미지를 프록시하여 방화벽이나 리브스 프록시 뒤에 있는 이미지에 접근할 수 있도록 합니다.
5. 관리 패널 – /admin에서 접속할 수 있습니다. 패널은 .env에 설정한 API_KEY로 보호됩니다. 다음 기능을 제공합니다:
   • Gemini 연결 상태 확인.
   • 서버 재시작 없이 쿠키 값 업데이트.
   • 속도 제한(rate-limit) 설정 조정.
   • 실시간 로그 확인 및 빠른 채팅 테스트 실행.

실행 방법

• Docker (권장) – .env.example을 .env로 복사하고 쿠키 값을 채운 후 docker-compose up -d를 실행합니다.
• 직접 실행 – 의존성(uv 또는 pip)을 설치하고, 가상환경을 활성화한 후 uvicorn main:app --reload를 실행합니다.
• 환경 변수는 선택적 동작을 제어합니다:
  • TEMPORARY_CHAT은 “thinking” 또는 이미지 생성과 같은 기능을 비활성화합니다.
  • AUTO_DELETE_CHAT은 응답 후 Gemini에서 대화를 삭제합니다.
  • PUBLIC_BASE_URL은 리브스 프록시 뒤에 있을 때 정확한 이미지 프록시 URL을 위해 필요합니다.

사용 사례

• 제3자 호스팅 서비스에 의존하지 않고 자신의 애플리케이션에서 Gemini를 실험해보고 싶은 개발자.
• 이미 OpenAI API를 사용하는 중인 내부 도구를 구축하는 팀이 비용이나 기능 측면에서 Gemini로 전환하고자 하는 경우.
• Render, HuggingFace Spaces 또는 셀프 호스팅 서버에서 Gemini의 채팅 및 이미지 생성 기능을 빠르게 데모할 수 있는 사람이 필요한 경우.

제한 사항

• 사용자 제공 쿠키에 의존합니다. Google이 쿠키를 순회환(rotate)하거나 무효화하면, 쿠키를 갱신할 때까지 서비스가 중단됩니다.
• 문서화되지 않은 웹 API를 사용하므로, 예고 없이 중단될 수 있습니다.
• 데모 배포본(Render, HuggingFace)은 자리표시자(placeholder) 비밀번호와 Gemini 쿠키가 포함되어 있지 않으므로, 관리 UI만 보여줍니다.

감사의 말

• 저수준 요청 처리를 위해 gemini‑webapi 라이브러리를 사용합니다.
• 이미지 워터마크 제거 코드는 journey‑ad/gemini-watermark-remover 및 allenk/GeminiWatermarkTool 프로젝트에서 가져왔습니다.

---

TL;DR: Gemi2Api‑Server는 Gemini를 OpenAI 호환 API처럼 호출할 수 있게 해주는 FastAPI 기반 프록시입니다. 자신의 Gemini 로그인 쿠키를 제공하고, 선택적으로 모델 헤더를를하게 할 수 있으며, 로컬 또는 컨테이너에서 실행합니다. 공식 API가 없는 Gemini의 채팅 및 이미지 생성 기능을 사용하고자 하는 개발자들에게 실용적인 가교 역할을 합니다.