Gemini-API

A reverse-engineered asynchronous Python wrapper for the Google Gemini web app (formerly Bard).

Features

• Persistent Cookies - Automatically refreshes cookies in background. Optimized for always-on services.
• Image Generation - Natively supports generating and editing images with natural language.
• Video & Audio Generation - Supports generating videos and audio/music content natively.
• Deep Research - Full deep research workflow with plan creation, status polling, and result retrieval.
• System Prompt - Supports customizing the model's system prompt with Gemini Gems.
• Extension Support - Supports generating content with Gemini extensions, such as YouTube and Gmail.
• Classified Outputs - Categorizes text, thoughts, images, videos, and audio in the response.
• Streaming Mode - Supports stream generation, yielding partial outputs as they are generated.
• CLI Tool - Standalone command-line interface for quick interactions.
• Official Flavor - Provides a simple and elegant interface inspired by Google Generative AI's official API.
• Asynchronous - Utilizes asyncio to run generation tasks and return outputs efficiently.

Table of Contents

• Features
• Table of Contents
• Installation
• Authentication
• Usage
  • Initialization
  • Generate Content
  • Generate Content with Files
  • Conversations Across Multiple Turns
  • Continue Previous Conversations
  • Read Conversation History
  • Delete Previous Conversations from Gemini History
  • Temporary Mode
  • Streaming Mode
  • Select Language Model
  • List Available Models
  • Apply System Prompt with Gemini Gems
  • Manage Custom Gems
    • Create a Custom Gem
    • Update an Existing Gem
    • Delete a Custom Gem
  • Retrieve Model's Thought Process
  • Retrieve Images in Response
  • Generate and Edit Images
  • Retrieve Videos and Audio

Installation

[!NOTE]

This package requires Python 3.10 or higher.

Install or update the package with pip.

pip install -U gemini_webapi

Optionally, the package offers a way to automatically import cookies from your local browser via optional dependency browser-cookie3. To enable this feature, install gemini_webapi[browser] instead. Supported platforms and browsers can be found here.

pip install -U gemini_webapi[browser]

Authentication

[!TIP]

If browser-cookie3 is installed, you can skip this step and go directly to the usage section. Just make sure you are logged in to https://gemini.google.com in your browser.

• Go to https://gemini.google.com and log in with your Google account
• Press F12 to open the web inspector, go to the Network tab, and refresh the page
• Click any request and copy the cookie values of __Secure-1PSID and __Secure-1PSIDTS

[!NOTE]

If your application is deployed in a containerized environment (e.g. Docker), you may want to persist the cookies with a volume to avoid re-authentication every time the container rebuilds. You can set GEMINI_COOKIE_PATH environment variable to specify the path where auto-refreshed cookies are stored. Make sure the path is writable by the application.

Here's part of a sample docker-compose.yml file:

services:
    main:
        environment:
            GEMINI_COOKIE_PATH: /tmp/gemini_webapi
        volumes:
            - ./gemini_cookies:/tmp/gemini_webapi

[!NOTE]

The API's auto-cookie-refreshing feature doesn't require browser-cookie3 and is enabled by default. It allows you to keep the API service running without worrying about cookie expiration.

This feature may require you to log in to your Google account again in the browser. This is expected behavior and won't affect the API's functionality.

To avoid this, it's recommended to get cookies from a separate browser session and close it as soon as possible for best utilization (e.g. a fresh login in the browser's private mode). More details can be found here.

Usage

Initialization

Import the required packages and initialize a client with your cookies from the previous step. After successful initialization, the API will automatically refresh __Secure-1PSIDTS in the background as long as the process is alive.

import asyncio
from gemini_webapi import GeminiClient

# Replace "COOKIE VALUE HERE" with your actual cookie values.
# Leave Secure_1PSIDTS empty if it's not available for your account.
Secure_1PSID = "COOKIE VALUE HERE"
Secure_1PSIDTS = "COOKIE VALUE HERE"

async def main():
    # If browser-cookie3 is installed, simply use `client = GeminiClient()`
    client = GeminiClient(Secure_1PSID, Secure_1PSIDTS, proxy=None)
    await client.init(timeout=30, auto_close=False, close_delay=300, auto_refresh=True)

asyncio.run(main())

[!TIP]

auto_close and close_delay are optional arguments for automatically closing the client after a certain period of inactivity. This feature is disabled by default. In an always-on service like a chatbot, it's recommended to set auto_close to True with a reasonable close_delay value for better resource management.

Generate Content

Ask a single-turn question by calling GeminiClient.generate_content, which returns a gemini_webapi.ModelOutput object containing the generated text, images, thoughts, and conversation metadata.

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

asyncio.run(main())

[!TIP]

Simply use print(response) to get the same output if you just want to see the response text.

Generate Content with Files

Gemini supports file input, including images and documents. Optionally, you can pass files as a list of paths in str or pathlib.Path to GeminiClient.generate_content together with a text prompt.

async def main():
    response = await client.generate_content(
            "Introduce the contents of these two files. Is there any connection between them?",
            files=["assets/sample.pdf", Path("assets/banner.png")],
        )
    print(response.text)

asyncio.run(main())

Conversations Across Multiple Turns

If you want to keep the conversation continuous, use GeminiClient.start_chat to create a gemini_webapi.ChatSession object and send messages through it. The conversation history will be handled automatically and updated after each turn.

async def main():
    chat = client.start_chat()
    response1 = await chat.send_message(
        "Introduce the contents of these two files. Is there any connection between them?",
        files=["assets/sample.pdf", Path("assets/banner.png")],
    )
    print(response1.text)
    response2 = await chat.send_message(
        "Use image generation tool to modify the banner with another font and design."
    )
    print(response2.text, response2.images, sep="\n\n----------------------------------\n\n")

asyncio.run(main())

[!TIP]

Same as GeminiClient.generate_content, ChatSession.send_message also accepts image as an optional argument.

Continue Previous Conversations

To manually retrieve previous conversations, you can pass a previous ChatSession's metadata to GeminiClient.start_chat when creating a new ChatSession. Alternatively, you can persist previous metadata to a file or database if you need to access it after the current Python process has exited.

async def main():
    # Start a new chat session
    chat = client.start_chat()
    response = await chat.send_message("Fine weather today")

    # Save chat's metadata
    previous_session = chat.metadata

    # Load the previous conversation
    previous_chat = client.start_chat(metadata=previous_session)
    response = await previous_chat.send_message("What was my previous message?")
    print(response)

asyncio.run(main())

Read Conversation History

You can read the conversation history of a specific chat by calling GeminiClient.read_chat with the chat ID. It returns a ChatHistory object containing a list of ChatTurn objects ordered from newest to oldest.

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

    # Read the chat history
    history = await client.read_chat(chat.cid)
    if history:
        for turn in history.turns:
            print(f"[{turn.role.upper()}] {turn.text}")
            print("\n----------------------------------\n")

asyncio.run(main())

To list all recent chats, use GeminiClient.list_chats:

async def main():
    chats = client.list_chats()
    if chats:
        for chat_info in chats:
            print(f"{chat_info.cid}: {chat_info.title}")

asyncio.run(main())

Delete Previous Conversations from Gemini History

You can delete a specific chat