HanaokaYuzu/Gemini-API

Google Gemini 웹 앱(이전 Bard)을 위한 역공학(Reverse-engineered) 기반의 비동기 Python 래퍼 (wrapper)입니다.

지속적인 쿠키 (Persistent Cookies)

백그라운드에서 쿠키를 자동으로 갱신합니다. 항상 켜져 있는 서비스에 최적화되어 있습니다.
이미지 생성 (Image Generation)
자연어를 사용하여 이미지를 생성하고 편집하는 기능을 네이티브로 지원합니다.
비디오 및 오디오 생성 (Video & Audio Generation)
비디오 및 오디오/음악 콘텐츠 생성을 네이티브로 지원합니다.
딥 리서치 (Deep Research)
계획 생성, 상태 폴링(polling), 결과 검색을 포함한 전체 딥 리서치 워크플로우를 지원합니다.
시스템 프롬프트 (System Prompt)
Gemini Gems를 사용하여 모델의 시스템 프롬프트를 커스텀할 수 있습니다.
확장 기능 지원 (Extension Support)
YouTube 및 Gmail과 같은 Gemini 확장 기능을 사용하여 콘텐츠를 생성할 수 있습니다.
분류된 출력 (Classified Outputs)
응답 내의 텍스트, 생각(thoughts), 이미지, 비디오, 오디오를 분류합니다.
스트리밍 모드 (Streaming Mode)
스트림 생성(stream generation)을 지원하여 생성되는 대로 부분적인 출력을 반환합니다.
CLI 도구 (CLI Tool)
빠른 상호작용을 위한 독립형 명령줄 인터페이스(command-line interface)를 제공합니다.
공식 스타일 (Official Flavor)
Google Generative AI의 공식 API에서 영감을 받은 단순하고 우아한 인터페이스를 제공합니다.
비동기 (Asynchronous)
생성 작업을 실행하고 출력을 효율적으로 반환하기 위해 asyncio를 활용합니다.
기능 (Features)
목차 (Table of Contents)
설치 (Installation)
인증 (Authentication)
사용법 (Usage)
초기화 (Initialization)
콘텐츠 생성 (Generate Content)
파일과 함께 콘텐츠 생성 (Generate Content with Files)
다회차 대화 (Conversations Across Multiple Turns)
이전 대화 이어가기 (Continue Previous Conversations)
대화 기록 읽기 (Read Conversation History)
Gemini 기록에서 이전 대화 삭제 (Delete Previous Conversations from Gemini History)
임시 모드 (Temporary Mode)
스트리밍 모드 (Streaming Mode)
언어 모델 선택 (Select Language Model)
사용 가능한 모델 목록 (List Available Models)
Gemini Gems로 시스템 프롬프트 적용 (Apply System Prompt with Gemini Gems)
커스텀 Gems 관리 (Manage Custom Gems)
모델의 사고 과정 검색 (Retrieve Model's Thought Process)
응답 내 이미지 검색 (Retrieve Images in Response)
이미지 생성 및 편집 (Generate and Edit Images)
비디오 및 오디오 검색 (Retrieve Videos and Audio)
Gemini 확장 기능으로 콘텐츠 생성 (Generate Content with Gemini Extensions)
다른 답변 후보 확인 및 전환 (Check and Switch to Other Reply Candidates)
딥 리서치 (Deep Research)
로깅 설정 (Logging Configuration)
CLI 도구 (CLI Tool)
참고 문헌 (References)
Stargazers

참고 (Note)

이 패키지는 Python 3.10 이상을 요구합니다.

pip를 사용하여 패키지를 설치하거나 업데이트하세요.

pip install -U gemini_webapi

선택 사항으로, 이 패키지는 선택적 의존성(optional dependency)인 browser-cookie3를 통해 로컬 브라우저에서 쿠키를 자동으로 가져오는 방법을 제공합니다.

이 기능을 사용하려면 대신 gemini_webapi[browser]를 설치하세요. 지원되는 플랫폼 및 브라우저는 여기에서 확인할 수 있습니다.

pip install -U gemini_webapi[browser]

팁

browser-cookie3가 설치되어 있다면 이 단계를 건너뛰고 바로 사용 섹션으로 이동할 수 있습니다. 브라우저에서 https://gemini.google.com에 로그인되어 있는지만 확인하세요.

https://gemini.google.com으로 이동하여 Google 계정으로 로그인합니다.
F12를 눌러 웹 검사기(web inspector)를 열고, Network 탭으로 이동한 뒤 페이지를 새로고침합니다.
아무 요청(request)이나 클릭하여 __Secure-1PSID와 __Secure-1PSIDTS의 쿠키 값을 복사합니다.

참고

애플리케이션이 컨테이너화된 환경(예: Docker)에 배포되는 경우, 컨테이너가 재빌드될 때마다 재인증하는 것을 방지하기 위해 볼륨(volume)을 사용하여 쿠키를 유지하는 것이 좋습니다. GEMINI_COOKIE_PATH 환경 변수를 설정하여 자동 갱신된 쿠키가 저장될 경로를 지정할 수 있습니다. 해당 경로가 애플리케이션에 의해 쓰기 가능한지 확인하세요.

다음은 샘플 docker-compose.yml 파일의 일부입니다:

services:
main:
environment:
...

참고

API의 자동 쿠키 갱신(auto-cookie-refreshing) 기능은 browser-cookie3를 요구하지 않으며 기본적으로 활성화되어 있습니다. 이를 통해 쿠키 만료를 걱정하지 않고 API 서비스를 계속 실행할 수 있습니다.

이 기능으로 인해 브라우저에서 Google 계정에 다시 로그인해야 할 수도 있습니다. 이는 예상된 동작이며 API의 기능에는 영향을 미치지 않습니다.

이를 방지하려면, 최적의 활용을 위해 별도의 브라우저 세션에서 쿠키를 가져온 뒤 가능한 한 빨리 해당 세션을 닫는 것을 권장합니다(예: 브라우저의 시크릿 모드에서 새로 로그인).

자세한 내용은 여기에서 확인할 수 있습니다.

필요한 패키지를 임포트(Import)하고 이전 단계에서 가져온 쿠키로 클라이언트(client)를 초기화합니다. 초기화에 성공하면, 프로세스가 살아있는 동안 API는 백그라운드에서 __Secure-1PSIDTS를 자동으로 갱신합니다.

import asyncio
from gemini_webapi import GeminiClient
# "COOKIE VALUE HERE"를 실제 쿠키 값으로 교체하세요.
...

Tip

auto_close와 close_delay는 일정 기간 활동이 없을 경우 클라이언트를 자동으로 종료하기 위한 선택적 인자 (optional arguments)입니다. 이 기능은 기본적으로 비활성화되어 있습니다. 챗봇과 같이 항상 켜져 있는 서비스의 경우, 더 나은 리소스 관리를 위해 auto_close를 True로 설정하고 적절한 close_delay 값을 지정하는 것을 권장합니다.

GeminiClient.generate_content를 호출하여 단일 턴 (single-turn) 질문을 수행할 수 있으며, 이는 생성된 텍스트, 이미지, 사고 과정 (thoughts), 그리고 대화 메타데이터 (conversation metadata)를 포함하는 gemini_webapi.ModelOutput 객체를 반환합니다.

async def main():
    response = await client.generate_content("Hello World!")
    print(response.text)
...

Tip

단순히 응답 텍스트만 확인하고 싶다면, print(response)를 사용하여 동일한 출력을 얻을 수 있습니다.

Gemini는 이미지와 문서를 포함한 파일 입력을 지원합니다. 선택적으로, 텍스트 프롬프트와 함께 str 또는 pathlib.Path 형식의 경로 리스트로 파일을 GeminiClient.generate_content에 전달할 수 있습니다.

async def main():
    response = await client.generate_content(
        "이 두 파일의 내용을 소개해주세요. 두 파일 사이에 어떤 연관성이 있나요?",
        ...
    )

대화를 연속적으로 유지하고 싶다면, GeminiClient.start_chat을 사용하여 gemini_webapi.ChatSession 객체를 생성하고 이를 통해 메시지를 보내세요. 대화 기록 (conversation history)은 자동으로 처리되며 매 턴마다 업데이트됩니다.

async def main():
    chat = client.start_chat()
    response1 = await chat.send_message(
        ...
    )

Tip

GeminiClient.generate_content와 마찬가지로, ChatSession.send_message 또한 선택적 인자로 image를 허용합니다.

이전 대화를 수동으로 불러오려면, 새로운 ChatSession을 생성할 때 이전 ChatSession의 메타데이터를 GeminiClient.start_chat에 전달할 수 있습니다.

또는, 현재 Python 프로세스가 종료된 후에도 메타데이터에 접근해야 하는 경우 이전 메타데이터를 파일이나 데이터베이스에 저장할 수 있습니다.

async def main():
# 새로운 채팅 세션 시작
chat = client.start_chat()
...

특정 채팅의 대화 기록은 채팅 ID와 함께 GeminiClient.read_chat을 호출하여 읽을 수 있습니다. 이 메서드는 최신순에서 오래된 순으로 정렬된 ChatTurn 객체 리스트를 포함하는 ChatHistory 객체를 반환합니다.

async def main():
chat = client.start_chat()
await chat.send_message("What is the capital of France?")
...

최근의 모든 채팅 목록을 나열하려면 GeminiClient.list_chats를 사용하십시오:

async def main():
chats = client.list_chats()
if chats:
...

채팅 ID와 함께 GeminiClient.delete_chat을 호출하여 서버의 Gemini 기록에서 특정 채팅을 삭제할 수 있습니다.

async def main():
# 새로운 채팅 세션 시작
chat = client.start_chat()
...

GeminiClient.generate_content 또는 ChatSession.send_message에 temporary=True를 전달하여 임시 채팅을 시작할 수 있습니다. 임시 채팅은 Gemini 기록에 저장되지 않습니다.

async def main():
response = await client.generate_content("Hello World!", temporary=True)
print(response.text, "\n\n----------------------------------\n\n")
...

더 긴 응답의 경우, 스트리밍 모드 (streaming mode)를 사용하여 출력이 생성되는 대로 부분적인 출력을 받을 수 있습니다. 이는 특히 챗봇과 같은 실시간 애플리케이션에서 더 반응성이 좋은 사용자 경험을 제공합니다.

generate_content_stream 메서드는 ModelOutput 객체를 생성(yield)하며, 여기서 text_delta 속성은 마지막 생성 이후 수신된 새로운 문자들만 포함하므로 증분 업데이트를 표시하기 쉽습니다.

async def main():
async for chunk in client.generate_content_stream(
"What's the difference between 'await' and 'async for'?"
...

팁

스트리밍 모드는 generate_content와 동일한 인자를 허용합니다. 또한 ChatSession.send_message_stream을 사용하여 멀티턴 대화 (multi-turn conversations)에서도 스트리밍 모드를 사용할 수 있습니다.

GeminiClient.generate_content 또는 GeminiClient.start_chat에 model 인자를 전달하여 사용할 언어 모델 (language model)을 지정할 수 있습니다. 기본값은 unspecified입니다.

사용 가능한 모델은 계정 등급 (account tier)에 따라 초기화 시점에 동적 (dynamically) 으로 검색됩니다. Model 열거형 (enum)을 사용하면 편리한 단축키를 제공합니다.

from gemini_webapi.constants import Model
async def main():
response1 = await client.generate_content(
...

또한, 위에 나열되지 않은 모델에 접근하기 위해 커스텀 모델 헤더 문자열 (custom model header strings)을 직접 전달할 수도 있습니다.

# "model_name" 및 "model_header" 키가 반드시 존재해야 합니다
custom_model = {
"model_name": "xxx",
...

클라이언트는 초기화 시점에 귀하의 계정에서 사용 가능한 모델을 동적으로 검색합니다. GeminiClient.list_models를 사용하여 사용 가능한 모든 모델과 그 세부 정보를 확인할 수 있습니다.

async def main():
await client.init() # 먼저 클라이언트가 초기화되었는지 확인하세요
models = client.list_models()
...

시스템 프롬프트 (System prompts)는 Gemini Gems를 통해 대화에 적용할 수 있습니다. Gem을 사용하려면 GeminiClient.generate_content 또는 GeminiClient.start_chat에 gem 인자를 전달하면 됩니다. gem은 Gem ID 문자열 또는 gemini_webapi.Gem 객체일 수 있습니다. 단일 대화에는 하나의 Gem만 적용할 수 있습니다.

팁 (Tip)

기본적으로 사용자에게 표시되지 않는 일부 시스템 사전 정의 Gem (system predefined gems)이 있으며 (따라서 제대로 작동하지 않을 수 있습니다), client.fetch_gems(include_hidden=True)를 사용하여 이를 가져오기 결과에 포함할 수 있습니다.

async def main():
# 사전 정의된 Gem과 사용자가 생성한 Gem을 모두 포함하여 현재 계정의 모든 Gem을 가져옵니다
await client.fetch_gems(include_hidden=False)
...

API를 통해 프로그래밍 방식으로 커스텀 Gem을 생성, 업데이트 및 삭제할 수 있습니다. 사전 정의된 시스템 Gem은 수정하거나 삭제할 수 없음에 유의하세요.

이름, 시스템 프롬프트 (지침, instructions), 그리고 선택 사항인 설명을 사용하여 새로운 커스텀 Gem을 생성합니다:

async def main():
# 새로운 커스텀 Gem 생성
new_gem = await client.create_gem(
...

참고 (Note)

Gem을 업데이트할 때는 단 하나만 변경하고 싶더라도 모든 파라미터(name, prompt, description)를 반드시 제공해야 합니다.

async def main():
# 커스텀 Gem 가져오기 ("Python Tutor"라는 이름의 Gem이 있다고 가정)
await client.fetch_gems()
...

async def main():
# 삭제할 Gem 가져오기
await client.fetch_gems()
...

사고 능력 (thinking capabilities)을 가진 모델을 사용할 때, 모델의 사고 과정 (thought process)은 ModelOutput.thoughts에 채워집니다.

async def main():
response = await client.generate_content(
"What's 1+1?", model="gemini-3-pro"
...

API 출력 결과의 이미지들은 gemini_webapi.Image 객체의 리스트로 저장됩니다. Image.title, Image.url, 그리고 Image.alt를 각각 호출하여 이미지의 제목, URL, 설명을 확인할 수 있습니다.

async def main():
response = await client.generate_content("Send me some pictures of cats")
for image in response.images:
...

자연어를 사용하여 Google의 최신 이미지 모델인 Nano Banana로 Gemini에게 이미지를 생성하거나 편집하도록 요청할 수 있습니다.

중요 (Important)

Google은 Gemini의 이미지 생성 기능에 대해 몇 가지 제한 사항을 두고 있으므로, 지역/계정에 따라 사용 가능 여부가 다를 수 있습니다. 다음은 공식 문서에서 복사한 요약 내용입니다 (2025년 9월 10일 기준):

특정 Gemini 앱에서의 이 기능 사용 가능 여부는 해당 앱이 지원하는 언어 및 국가로 제한됩니다.

현재 이 기능은 18세 미만 사용자에게는 제공되지 않습니다.

이 기능을 사용하려면 Gemini Apps에 로그인해야 합니다.

Image.save()를 호출하여 Gemini로부터 반환된 이미지를 로컬에 저장할 수 있습니다. 선택적으로 함수에 path 및 filename 인자를 전달하여 파일 경로와 파일 이름을 지정할 수 있습니다. 이는 WebImage와 GeneratedImage 모두에서 작동합니다.

async def main():
response = await client.generate_content("Generate some pictures of cats")
for i, image in enumerate(response.images):
...

참고 (Note)

기본적으로, (이전 예시와 같이) 이미지를 보내달라는 요청을 받았을 때, 프롬프트에서 명시적으로 이미지를 "생성(generate)"해달라고 요청하지 않는 한, Gemini는 AI 모델로 이미지를 생성하는 대신 웹에서 가져온 이미지를 보냅니다. 이 패키지에서는 웹 이미지와 생성된 이미지를 각각 WebImage와 GeneratedImage로 다르게 취급하며, 출력 시 자동으로 분류됩니다.

Gemini는 비디오 및 오디오/음악 콘텐츠를 생성할 수 있습니다. 이러한 콘텐츠는 각각 ModelOutput.videos 및 ModelOutput.media 내의 GeneratedVideo 및 GeneratedMedia 객체로 반환됩니다. 이미지와 마찬가지로 이를 디스크에 저장할 수 있습니다.

참고

Gemini의 비디오 및 오디오 생성 기능에 접근하려면 활성화된 구독(active subscription)이 필요할 수 있습니다.

HanaokaYuzu/Gemini-API

요약

핵심 포인트

댓글