Skip to main content

Gemini Banner

PyPI Downloads Dependencies License Code style

GitHub stars GitHub issues CI

Gemini Icon 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.
  • 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, web images, and AI-generated images in the response.
  • Streaming Mode - Supports stream generation, yielding partial outputs as they are generated.
  • 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

Installation

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

  • 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
services:
    main:
        environment:
            GEMINI_COOKIE_PATH: /tmp/gemini_webapi
        volumes:
            - ./gemini_cookies:/tmp/gemini_webapi

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())

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())

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())

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.

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)
    for turn in history:
        print(
            f"Input: {turn.user_prompt}\n"
            f"Output: {turn.assistant_response}"
            "\n\n----------------------------------\n\n"
        )

asyncio.run(main())

Delete Previous Conversations from Gemini History

You can delete a specific chat from Gemini history on the server by calling GeminiClient.delete_chat with the chat ID.

async def main():
    # Start a new chat session
    chat = client.start_chat()
    await chat.send_message("This is a temporary conversation.")

    # Delete the chat
    await client.delete_chat(chat.cid)
    print(f"Chat deleted: {chat.cid}")

asyncio.run(main())

Temporary Mode

You can start a temporary chat by passing temporary=True to GeminiClient.generate_content or ChatSession.send_message. Temporary chats won't be saved in Gemini history.

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

    chat = client.start_chat()
    await chat.send_message("Fine weather today", temporary=False)
    response2 = await chat.send_message("What's my last message?", temporary=True)
    print(response2.text)

asyncio.run(main())

Streaming Mode

For longer responses, you can use streaming mode to receive partial outputs as they are generated. This provides a more responsive user experience, especially for real-time applications like chatbots.

The generate_content_stream method yields ModelOutput objects where the text_delta attribute contains only the new characters received since the last yield, making it easy to display incremental updates.

async def main():
    async for chunk in client.generate_content_stream(
        "What's the difference between 'await' and 'async for'?"
    ):
        print(chunk.text_delta, end="", flush=True)

    print()

asyncio.run(main())

Select Language Model

You can specify which language model to use by passing the model argument to GeminiClient.generate_content or GeminiClient.start_chat. The default value is unspecified.

Currently available models (as of November 20, 2025):

  • unspecified - Default model
  • gemini-3.0-pro - Gemini 3.0 Pro
  • gemini-3.0-flash - Gemini 3.0 Flash
  • gemini-3.0-flash-thinking - Gemini 3.0 Flash Thinking
from gemini_webapi.constants import Model

async def main():
    response1 = await client.generate_content(
        "What's your language model version? Reply with the version number only.",
        model=Model.G_3_0_FLASH,
    )
    print(f"Model version ({Model.G_3_0_FLASH.model_name}): {response1.text}")

    chat = client.start_chat(model="gemini-2.5-pro")
    response2 = await chat.send_message("What's your language model version? Reply with the version number only.")
    print(f"Model version (gemini-2.5-pro): {response2.text}")

asyncio.run(main())

You can also pass custom model header strings directly to access models that are not listed above.

# "model_name" and "model_header" keys must be present
custom_model = {
    "model_name": "xxx",
    "model_header": {
        "x-goog-ext-525001261-jspb": "[1,null,null,null,'e6fa609c3fa255c0',null,null,null,[4]]"
    },
}

response = await client.generate_content(
    "What's your model version?",
    model=custom_model
)

Apply System Prompt with Gemini Gems

System prompts can be applied to conversations via Gemini Gems. To use a gem, you can pass the gem argument to GeminiClient.generate_content or GeminiClient.start_chat. gem can be either a gem ID string or a gemini_webapi.Gem object. Only one gem can be applied to a single conversation.

async def main():
    # Fetch all gems for the current account, including both predefined and user-created ones
    await client.fetch_gems(include_hidden=False, language="en")

    # Once fetched, gems will be cached in `GeminiClient.gems`
    gems = client.gems

    # Get the gem you want to use
    system_gems = gems.filter(predefined=True)
    coding_partner = system_gems.get(id="coding-partner")

    response1 = await client.generate_content(
        "What's your system prompt?",
        model=Model.G_3_0_FLASH,
        gem=coding_partner,
    )
    print(response1.text)

    # Another example with a user-created custom gem
    # Gem ids are consistent strings. Store them somewhere to avoid fetching gems every time
    your_gem = gems.get(name="Your Gem Name")
    your_gem_id = your_gem.id
    chat = client.start_chat(gem=your_gem_id)
    response2 = await chat.send_message("What's your system prompt?")
    print(response2)

Manage Custom Gems

You can create, update, and delete your custom gems programmatically with the API. Note that predefined system gems cannot be modified or deleted.

Create a Custom Gem

Create a new custom gem with a name, system prompt (instructions), and optional description:

async def main():
    # Create a new custom gem
    new_gem = await client.create_gem(
        name="Python Tutor",
        prompt="You are a helpful Python programming tutor.",
        description="A specialized gem for Python programming"
    )

    print(f"Custom gem created: {new_gem}")

    # Use the newly created gem in a conversation
    response = await client.generate_content(
        "Explain how list comprehensions work in Python",
        gem=new_gem
    )
    print(response.text)

asyncio.run(main())

Update an Existing Gem

async def main():
    # Get a custom gem (assuming you have one named "Python Tutor")
    await client.fetch_gems()
    python_tutor = client.gems.get(name="Python Tutor")

    # Update the gem with new instructions
    updated_gem = await client.update_gem(
        gem=python_tutor,  # Can also pass gem ID string
        name="Advanced Python Tutor",
        prompt="You are an expert Python programming tutor.",
        description="An advanced Python programming assistant"
    )

    print(f"Custom gem updated: {updated_gem}")

asyncio.run(main())

Delete a Custom Gem

async def main():
    # Get the gem to delete
    await client.fetch_gems()
    gem_to_delete = client.gems.get(name="Advanced Python Tutor")

    # Delete the gem
    await client.delete_gem(gem_to_delete)  # Can also pass gem ID string
    print(f"Custom gem deleted: {gem_to_delete.name}")

asyncio.run(main())

Retrieve Model's Thought Process

When using models with thinking capabilities, the model's thought process will be populated in ModelOutput.thoughts.

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

asyncio.run(main())

Retrieve Images in Response

Images in the API's output are stored as a list of gemini_webapi.Image objects. You can access the image title, URL, and description by calling Image.title, Image.url and Image.alt respectively.

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

asyncio.run(main())

Generate and Edit Images

You can ask Gemini to generate and edit images with Nano Banana, Google's latest image model, using natural language.

You can save images returned from Gemini locally by calling Image.save(). Optionally, you can specify the file path and file name by passing path and filename arguments to the function, and skip images with invalid file names by passing skip_invalid_filename=True. This works for both WebImage and GeneratedImage.

async def main():
    response = await client.generate_content("Generate some pictures of cats")
    for i, image in enumerate(response.images):
        await image.save(path="temp/", filename=f"cat_{i}.png", verbose=True)
        print(image, "\n\n----------------------------------\n\n")

asyncio.run(main())

Generate Content with Gemini Extensions

After activating extensions for your account, you can access them in your prompts either in natural language or by starting your prompt with "@" followed by the extension keyword.

async def main():
    response1 = await client.generate_content("@Gmail What's the latest message in my mailbox?")
    print(response1, "\n\n----------------------------------\n\n")

    response2 = await client.generate_content("@Youtube What's the latest activity of Taylor Swift?")
    print(response2, "\n\n----------------------------------\n\n")

asyncio.run(main())

Check and Switch to Other Reply Candidates

A response from Gemini sometimes contains multiple reply candidates with different generated content. You can check all candidates and choose one to continue the conversation. By default, the first candidate is chosen.

async def main():
    # Start a conversation and list all reply candidates
    chat = client.start_chat()
    response = await chat.send_message("Recommend a science fiction book for me.")
    for candidate in response.candidates:
        print(candidate, "\n\n----------------------------------\n\n")

    if len(response.candidates) > 1:
        # Control the ongoing conversation flow by choosing candidate manually
        new_candidate = chat.choose_candidate(index=1)  # Choose the second candidate here
        followup_response = await chat.send_message("Tell me more about it.")  # Will generate content based on the chosen candidate
        print(new_candidate, followup_response, sep="\n\n----------------------------------\n\n")
    else:
        print("Only one candidate available.")

asyncio.run(main())

Logging Configuration

This package uses loguru for logging and exposes a function set_log_level to control the log level. You can set the log level to one of the following values: DEBUG, INFO, WARNING, ERROR, and CRITICAL. The default value is INFO.

from gemini_webapi import set_log_level

set_log_level("DEBUG")

References

Google AI Studio

acheong08/Bard

Stargazers

Star History Chart

Metadata

Release files for gemini-webapi 1.21.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gemini-webapi 1.21.0
File Size Uploaded Provenance Actions
gemini_webapi-1.21.0.tar.gz 272.6 kB With provenance Details for gemini_webapi-1.21.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gemini-webapi 1.21.0
File Interpreter ABI Platform Actions
gemini_webapi-1.21.0-py3-none-any.whl Python 3 none any Details for gemini_webapi-1.21.0-py3-none-any.whl

Total release size: 342.4 kB

Release files / gemini_webapi-1.21.0.tar.gz

Download URL gemini_webapi-1.21.0.tar.gz
Size 272.6 kB
Tags Source
SHA-256 checksum
How to use checksums
0b75c29b5380b109f663b35c8df76f5244dae819b12a472bd25df9016a46b76c
BLAKE2b-256 checksum
How to use checksums
b31eec164b7af828b2561a6d0d6235d895e2997698d16fcbbcc652b20ca0ba49
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 6, 2026.

Transparency log

Release files / gemini_webapi-1.21.0-py3-none-any.whl

Download URL gemini_webapi-1.21.0-py3-none-any.whl
Size 69.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
04fbaef555537892c2c824ea127796770d210dbe65df4f178723897dd969b72e
BLAKE2b-256 checksum
How to use checksums
a8c71e94cbfdf7c6add59f61897d0069e83ca099eafb0affeac7a56881c4298e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 6, 2026.

Transparency log

Security for gemini-webapi 1.21.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gemini_webapi-1.21.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.21.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page