zhiyu1998/Gemi2Api-Server

Gemi2Api‑Server – Google Gemini 웹 UI를 OpenAI 호환 API로 변환하는 가벼운 래퍼

무엇인가요

• 일반 브라우저 세션에서 내보낸 쿠키(__Secure-1PSID 및 __Secure-1PSIDTS)를 사용해 Google Gemini에 로그인하는 작은 FastAPI 서비스입니다.
• 이후 챗 완성 요청을 Gemini의 비공개 웹 API로 전달하고, OpenAI의 /v1/chat/completions 엔드포인트와 동일한 형식으로 응답을 반환합니다.
• 선택 사항인 관리 패널(/admin)을 통해 연결 상태 확인, 쿠키 편집, 인증에 사용되는 API 키 변경, 모델 실시간 테스트가 가능합니다.

왜 존재하는가

• Google은 현재 공개된 유료 Gemini 엔드포인트를 제공하지 않습니다(README 작성 시점 기준). 이 프로젝트는 OpenAI 스타일 REST API를 기대하는 도구에서 Gemini를 호출할 수 있도록 하는 자체 호스팅 브리지입니다.
• 또한 YAML 파일을 통해 사용자 정의 모델 정의를 추가하고, /v1/models 목록을 통해 노출할 수 있습니다.

실행 방법

1. Gemini 쿠키 확보 – 인코그니토 창에서 https://gemini.google.com에 로그인하고 개발자 도구를 열어 __Secure-1PSID와 __Secure-1PSIDTS의 값을 복사합니다.
2. .env 파일 생성 – .env.example을 복사하여 두 쿠키 값과 관리 UI에 접근하기 위한 API_KEY를 붙여넣습니다.
3. 배포 – 다음 중 하나로 실행 가능:
   • Python 종속성(fastapi, uvicorn, gemini-webapi, httpx, h2)을 설치한 후 uvicorn main:app --reload로 로컬 실행.
   • 제공된 Docker-Compose 설정(docker-compose up -d) 사용.
   • "Deploy to Render" 또는 "Duplicate on HuggingFace" 배지 클릭으로 호스팅 인스턴스 빠르게 배포.
4. 선택 사항: 사용자 정의 모델 – custom_models.yaml을 추가하여 Gemini 내부 API에 필요한 x-goog-ext-… 헤더 값을 친숙한 이름(예: gemini-3.5-flash)으로 매핑합니다. 파일은 핫 리로드되므로 재시작 없이 편집 가능합니다.

주요 설정 옵션

변수	목적
SECURE_1PSID / SECURE_1PSIDTS	Gemini 인증용 쿠키(필수).
API_KEY	/admin 접근 및 공개 API 보호에 필요한 단순 토큰.
TEMPORARY_CHAT	true일 경우 Gemini의 "임시 대화" 모드를 사용하며, 이미지 생성 및 사고 체인 추론 기능이 비활성화됩니다.
AUTO_DELETE_CHAT	true일 경우 응답 후 Gemini에 대화를 삭제하도록 지시하여 웹 계정을 깨끗하게 유지합니다.
PUBLIC_BASE_URL	생성된 이미지를 프록시할 때 사용되는 기본 URL; 리버스 프록시 뒤에서 실행할 경우 필요합니다.
CUSTOM_MODELS_FILE	모델 정의를 추가하거나 오버라이드하는 YAML/JSON 파일의 경로.
DISABLE_BUILTIN_MODELS	설정 시, /v1/models에서 공개되는 모델은 CUSTOM_MODELS_FILE에 나열된 모델만입니다.

API로 할 수 있는 일

• GET /v1/models – 서버가 알고 있는 모델 ID 목록을 반환합니다.
• POST /v1/chat/completions – OpenAI의 챗 API와 동일한 JSON 페이로드를 전송합니다. 서버는 이를 Gemini에 전달하고 응답을 스트리밍으로 반환합니다.
• GET /gemini-proxy/image – Gemini가 생성한 이미지 URL을 반환할 때 사용되는 작은 이미지 프록시 엔드포인트입니다. 이미지를 서버 호스트에서 가져올 수 있도록 URL을 재작성합니다.
• GET /admin – 상태 모니터링, 쿠키 편집, 채팅 테스트를 위한 웹 UI입니다.

누가 사용할 수 있나요

• 노트북, LangChain, 또는 이미 OpenAI 스타일 엔드포인트를 지원하는 다른 프레임워크에서 Gemini를 실험하고 싶은 개발자.
• 상용 Gemini API 비용을 지불하고 싶지 않은 소규모 팀으로, 상용 API가 출시될 경우 빠르게 자체 호스팅 브리지가 필요할 때.
• Render, HuggingFace Spaces, 또는 자체 VPS에서 개인용 "Gemini-as-a-service" 인스턴스를 운영하고 싶은 애호가.

제한 사항 및 주의사항

• 비공식 내부 Gemini 웹 API에 의존하고 있습니다. Google은 언제든지 쿠키 형식이나 요청 헤더를 변경할 수 있으며, 이로 인해 브리지가 작동하지 않을 수 있습니다.
• 유효하고 만료되지 않은 Gemini 로그인이 필요합니다. 자주 발생하는 500 에러는 쿠키가 만료되었거나 IP가 차단되었을 가능성이 큽니다.
• 보안은 최소한입니다. 보호는 설정한 API_KEY 하나뿐입니다. 이 서버를 신뢰할 수 있는 내부 구성 요소로 취급하고, 공개 인터넷 서비스로 취급하지 마세요.

자세한 정보 찾기

• 원본 상류 프로젝트는 HanaokaYuzu / Gemini‑API입니다. Gemi2Api‑Server는 이 라이브러리 위에 구축된 경량 서버 래퍼입니다.
• README에 문제 해결 및 트러블슈팅 팁이 링크되어 있습니다(예: 500 에러 처리).

---

위의 모든 세부 정보는 리포지토리의 README에서 직접 가져온 것이며, 외부 추측은 전혀 포함되지 않았습니다.