Gemini WebAPI

https://github.com/HanaokaYuzu/Gemini-API
Admin
Gemini WebAPI is an elegant asynchronous Python wrapper for the Google Gemini web app that enables...
Tokens:6,801
Snippets:77
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install gemini_webapi package

Source: https://pypi.org/project/gemini-webapi

Standard installation command for the library.

```bash
pip install -U gemini_webapi
```

--------------------------------

### Install gemini_webapi with browser support

Source: https://pypi.org/project/gemini-webapi

Installation command including optional browser-cookie3 dependency for automatic cookie retrieval.

```bash
pip install -U gemini_webapi[browser]
```

--------------------------------

### CLI Command Examples

Source: https://pypi.org/project/gemini-webapi

Common operations for interacting with Gemini, including asking questions, managing chat history, and inspecting account status.

```bash
# Ask a single question (streams by default)
python cli.py --cookies-json cookies.json ask "What is quantum computing?"

# Ask with image input
python cli.py --cookies-json cookies.json ask --image photo.jpg "Describe this"

# Non-streaming mode
python cli.py --cookies-json cookies.json ask --no-stream "Hello"

# Continue a conversation (chat ID from previous output)
python cli.py --cookies-json cookies.json reply c_abc123 "Tell me more"

# List your chat history
python cli.py --cookies-json cookies.json list

# Read a specific chat conversation
python cli.py --cookies-json cookies.json read c_abc123

# List the models your account can use
python cli.py --cookies-json cookies.json models

# Download a generated image
python cli.py --cookies-json cookies.json download "https://..." -o output.png

# Account diagnostics (status, quotas, usage limits, available models)
python cli.py --cookies-json cookies.json inspect
```

--------------------------------

### Configure Docker for cookie persistence

Source: https://pypi.org/project/gemini-webapi

Example docker-compose configuration to persist Gemini cookies across container rebuilds.

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

--------------------------------

### List Available Models

Source: https://pypi.org/project/gemini-webapi

Use this to discover models available for your account. Ensure the client is initialized before calling.

```python
async def main():
    await client.init()  # Make sure the client is initialized first
    models = client.list_models()
    if models:
        for model in models:
            print(f"{model.display_name}: {model.model_name}")


asyncio.run(main())
```

--------------------------------

### Initialize Gemini Client

Source: https://pypi.org/project/gemini-webapi

Import the client and initialize it with authentication cookies. The client automatically refreshes the session token in the background.

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

--------------------------------

### Select and Configure Language Models

Source: https://pypi.org/project/gemini-webapi

List available models and specify a model for generation or chat sessions.

```python
async def main():
    for model in client.list_models() or []:
        print(model.model_name, "|", model.display_name, "| available:", model.is_available)

    response1 = await client.generate_content(
        "What's your language model version? Reply with the version number only.",
        model="gemini-flash",  # a name, alias, display name or id
    )
    print(f"Model version (gemini-flash): {response1.text}")

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


asyncio.run(main())
```

```python
# "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,"fbb127bbb056c959",null,null,0,[4,5,6,8],null,null,1,null,null,1,1,"EA3C5672-E422-4A5F-BE26-B5B57D3B9AC3"]',
        "x-goog-ext-73010989-jspb": "[0]",
        "x-goog-ext-73010990-jspb": "[0,0,0]",
    },
}

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

--------------------------------

### GeminiClient.init

Source: https://pypi.org/project/gemini-webapi

Initializes the Gemini client with authentication cookies and configuration options.

```APIDOC
## GeminiClient.init(timeout, auto_close, close_delay, auto_refresh)

### Description
Initializes the client session. This must be called after instantiation to establish the connection and handle background token refreshing.

### Parameters
- **timeout** (int) - Optional - Connection timeout in seconds.
- **auto_close** (bool) - Optional - Whether to automatically close the client after inactivity.
- **close_delay** (int) - Optional - Delay in seconds before auto-closing.
- **auto_refresh** (bool) - Optional - Whether to automatically refresh authentication tokens.
```

--------------------------------

### GeminiClient.start_chat

Source: https://pypi.org/project/gemini-webapi

Creates a new chat session or resumes an existing one using metadata.

```APIDOC
## GeminiClient.start_chat(metadata)

### Description
Initializes a ChatSession object for multi-turn conversations. Providing metadata allows resuming a previous conversation.

### Parameters
- **metadata** (dict) - Optional - Metadata object from a previous ChatSession to resume history.
```

--------------------------------

### Create a Custom Gem

Source: https://pypi.org/project/gemini-webapi

Define a new custom gem with a name, prompt, and description.

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

--------------------------------

### Apply System Prompt with Gemini Gems

Source: https://pypi.org/project/gemini-webapi

Apply system prompts using Gem IDs or objects. Use fetch_gems with include_hidden=True to access predefined system gems.

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

    # 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?",
        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)
```

--------------------------------

### GeminiClient.list_models()

Source: https://pypi.org/project/gemini-webapi

Lists available language models for the account.

```APIDOC
## GeminiClient.list_models()

### Description
Returns a list of available language models discovered dynamically from the account.
```

--------------------------------

### CLI Global Options

Source: https://pypi.org/project/gemini-webapi

Global configuration flags that must be placed before the subcommand to modify CLI behavior.

```bash
--cookies-json PATH    Path to cookies JSON file (required)
--proxy URL            Proxy URL (or uses HTTPS_PROXY env)
--model NAME           Model name, alias or id (default: your account's default model)
--verbose              Enable debug logging
--no-persist           Don't update cookies file after run
--request-timeout SEC  HTTP timeout in seconds (default: 300)
```

--------------------------------

### Generate Content with Files

Source: https://pypi.org/project/gemini-webapi

Include local files such as images or PDFs in the generation request.

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

--------------------------------

### Retrieve and Save Videos and Audio

Source: https://pypi.org/project/gemini-webapi

Access generated videos and media through ModelOutput objects and save them to disk. The save method automatically polls until the content is ready.

```python
async def main():
    response = await client.generate_content("Generate a short video of a cat playing")

    # Save generated videos
    for video in response.videos:
        result = await video.save(path="temp/", verbose=True)
        print(f"Video saved: {result}")

    # Save generated media (audio/music)
    for media in response.media:
        result = await media.save(path="temp/", verbose=True)
        print(f"Media saved: {result}")


asyncio.run(main())
```

--------------------------------

### GeminiClient.generate_content

Source: https://pypi.org/project/gemini-webapi

Generates content based on a text prompt and optional file attachments.

```APIDOC
## GeminiClient.generate_content(prompt, files)

### Description
Sends a single-turn request to the Gemini model and returns a ModelOutput object.

### Parameters
- **prompt** (str) - Required - The text prompt to send to the model.
- **files** (list) - Optional - A list of file paths (str or pathlib.Path) to include with the prompt.
```

--------------------------------

### Gem Management Methods

Source: https://pypi.org/project/gemini-webapi

Methods for fetching, creating, updating, and deleting custom Gems.

```APIDOC
## Gem Management

### Methods
- **client.fetch_gems(include_hidden=False)**: Fetches and caches gems for the account.
- **client.create_gem(name, prompt, description)**: Creates a new custom gem.
- **client.update_gem(gem, name, prompt, description)**: Updates an existing custom gem.
- **client.delete_gem(gem)**: Deletes a custom gem.

### Note
Predefined system gems cannot be modified or deleted.
```

--------------------------------

### GeminiClient.generate_content

Source: https://pypi.org/project/gemini-webapi

Generates content from a model, optionally applying a Gem for system instructions.

```APIDOC
## GeminiClient.generate_content

### Description
Sends a prompt to the model and returns the generated content. Supports applying a Gem to define system behavior.

### Method
Asynchronous Method

### Signature
`await client.generate_content(prompt, gem=None, model=None)`

### Parameters
- **prompt** (str) - Required - The input text for the model.
- **gem** (str|Gem) - Optional - A gem ID or Gem object to apply as a system prompt.
- **model** (str) - Optional - The model identifier to use.

### Returns
- **ModelOutput** - Contains `text`, `thoughts` (if applicable), and `images`.
```

--------------------------------

### Generate Content with Gemini Extensions

Source: https://pypi.org/project/gemini-webapi

Interact with activated Gemini extensions by prefixing prompts with the extension keyword. Ensure extensions are enabled in your Gemini account settings first.

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

--------------------------------

### Generate Content

Source: https://pypi.org/project/gemini-webapi

Perform a single-turn request to generate text responses.

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


asyncio.run(main())
```

--------------------------------

### Cookie Configuration Format

Source: https://pypi.org/project/gemini-webapi

The CLI requires a JSON file containing authentication cookies. It supports both direct key-value pairs and browser-exported array-of-objects formats.

```json
{
  "__Secure-1PSID": "value...",
  "__Secure-1PSIDTS": "value..."
}
```

--------------------------------

### Continue Previous Conversations

Source: https://pypi.org/project/gemini-webapi

Resume a chat session by passing existing metadata to the start_chat method.

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

--------------------------------

### Deep Research Workflow Commands

Source: https://pypi.org/project/gemini-webapi

Commands for initiating, monitoring, and retrieving results from the autonomous deep research agent.

```bash
# 1. Submit a research task. Prints both a chat ID and a research (task) ID
python cli.py --cookies-json cookies.json research send --prompt "AI chip competition 2025"

# 2. Check progress. Pass --research-id for the actual task state - without it the chat
#    cannot be told apart from the plan and confirmation replies, which arrive immediately
python cli.py --cookies-json cookies.json research check c_abc123 --research-id 0f3d...

# 3. Fetch the full result
python cli.py --cookies-json cookies.json research get c_abc123

# 4. Save result to a file
python cli.py --cookies-json cookies.json research get c_abc123 --output report.md
```

--------------------------------

### GeminiClient.list_models

Source: https://pypi.org/project/gemini-webapi

Retrieves a list of all available models for the authenticated account.

```APIDOC
## GeminiClient.list_models

### Description
Returns a list of available models and their details. The client must be initialized using `await client.init()` before calling this method.

### Method
Synchronous Method

### Signature
`client.list_models()`

### Returns
- **List[Model]** - A list of model objects containing `display_name` and `model_name`.
```

--------------------------------

### Update an Existing Gem

Source: https://pypi.org/project/gemini-webapi

Update a custom gem by providing all parameters. Predefined system gems cannot be modified.

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

--------------------------------

### Retrieve Images in Response

Source: https://pypi.org/project/gemini-webapi

Access generated images as a list of Image objects, which contain title, URL, and alt text.

```python
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 Save Images

Source: https://pypi.org/project/gemini-webapi

Use generate_content to request images and save them locally using the Image.save method. Specify path and filename arguments to control output location.

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

--------------------------------

### Configure Logging Level

Source: https://pypi.org/project/gemini-webapi

Set the global log level using the loguru-based configuration function. Note that this resets existing loguru handlers.

```python
from gemini_webapi import set_log_level

set_log_level("DEBUG")
```

--------------------------------

### Stream Content Responses

Source: https://pypi.org/project/gemini-webapi

Receive partial outputs incrementally using generate_content_stream for improved responsiveness.

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

--------------------------------

### GeminiClient.generate_content_stream / ChatSession.send_message_stream

Source: https://pypi.org/project/gemini-webapi

Streams content generation for real-time applications.

```APIDOC
## GeminiClient.generate_content_stream / ChatSession.send_message_stream

### Description
Receives partial outputs as they are generated. Yields ModelOutput objects containing text_delta.
```

--------------------------------

### Check and Switch Reply Candidates

Source: https://pypi.org/project/gemini-webapi

Iterate through multiple response candidates and manually select one to influence subsequent conversation turns.

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

--------------------------------

### GeminiClient.list_chats

Source: https://pypi.org/project/gemini-webapi

Lists recent chat sessions.

```APIDOC
## GeminiClient.list_chats()

### Description
Returns a list of recent chat sessions, including their IDs and titles.
```

--------------------------------

### GeminiClient.generate_content / ChatSession.send_message

Source: https://pypi.org/project/gemini-webapi

Generates content or sends a message in a chat session, with support for temporary mode and model selection.

```APIDOC
## GeminiClient.generate_content / ChatSession.send_message

### Description
Generates content or sends a message. Supports temporary mode to prevent history saving and model selection.

### Parameters
- **temporary** (boolean) - Optional - If True, the chat will not be saved in history.
- **model** (string/AvailableModel/dict) - Optional - Specifies the language model to use.
```

--------------------------------

### Manage Multi-turn Conversations

Source: https://pypi.org/project/gemini-webapi

Use a ChatSession object to maintain conversation history across multiple messages.

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

--------------------------------

### Deep Research Execution and Retrieval

Source: https://pypi.org/project/gemini-webapi

Perform autonomous web research and retrieve generated reports. Reports are delivered as inline documents accessible via the result object or chat history.

```python
result = await client.deep_research("...")
doc = result.document
print(doc.title)  # 'SQLite vs DuckDB for Analytics'
print(doc.content)  # markdown report: headings, tables, links, [cite: N] markers
print(doc.sources)  # the web sources those [cite: N] markers resolve to

Path("report.md").write_text(doc.markdown, encoding="utf-8")  # body + numbered source list
```

```python
output = await client.fetch_latest_chat_response("c_abc123")
if (doc := output.deep_research_document) and doc.ready:
    print(doc.content)
```

```python
async def main():
    result = await client.deep_research(
        "Compare the top 3 cloud providers and their AI offerings",
        poll_interval=10.0,
        timeout=600.0,
    )
    print(f"Done: {result.done}")
    print(result.text)


asyncio.run(main())
```

```python
async def main():
    # Plan and confirmation are two turns of one conversation, so share a chat session
    chat = client.start_chat()

    # Step 1: Create a research plan
    plan = await client.create_deep_research_plan(
        "What are the latest advancements in quantum computing?",
        chat=chat,
    )
    print(f"Title: {plan.title}")
    print(f"ETA: {plan.eta_text}")
    for step in plan.steps:
        print(f"  - {step}")

    # Step 2 (optional): Ask for changes on the same session to get a revised plan back
    # plan = await client.create_deep_research_plan("Focus on error correction", chat=chat)

    # Step 3: Confirm the plan to start the research
    await client.start_deep_research(plan, chat=chat)

    # Step 4: Poll for completion
    result = await client.wait_for_deep_research(
        plan,
        poll_interval=10.0,
        timeout=600.0,
    )

    print(result.text)


asyncio.run(main())
```

--------------------------------

### Retrieve Model's Thought Process

Source: https://pypi.org/project/gemini-webapi

Access the internal reasoning of models that support thinking capabilities via the thoughts attribute.

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


asyncio.run(main())
```

--------------------------------

### List Recent Chats

Source: https://pypi.org/project/gemini-webapi

Retrieve a list of recent chat sessions associated with the account.

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

--------------------------------

### Manage Temporary Chat Sessions

Source: https://pypi.org/project/gemini-webapi

Use the temporary flag to prevent chat messages from being saved to the Gemini history.

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

--------------------------------

### GeminiClient.read_chat

Source: https://pypi.org/project/gemini-webapi

Retrieves the history of a specific conversation.

```APIDOC
## GeminiClient.read_chat(cid)

### Description
Fetches the conversation history for a given chat ID.

### Parameters
- **cid** (str) - Required - The unique identifier of the chat session.
```

--------------------------------

### Read Conversation History

Source: https://pypi.org/project/gemini-webapi

Retrieve and iterate through the history of a specific chat session.

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

--------------------------------

### Delete a Custom Gem

Source: https://pypi.org/project/gemini-webapi

Remove a custom gem using its object or ID.

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

--------------------------------

### ChatSession.send_message

Source: https://pypi.org/project/gemini-webapi

Sends a message within an active chat session.

```APIDOC
## ChatSession.send_message(message, files)

### Description
Sends a message to the current chat session and updates the conversation history.

### Parameters
- **message** (str) - Required - The text message to send.
- **files** (list) - Optional - A list of file paths to include with the message.
```

--------------------------------

### GeminiClient.delete_chat(cid)

Source: https://pypi.org/project/gemini-webapi

Deletes a specific chat session from the server history using the chat ID.

```APIDOC
## GeminiClient.delete_chat(cid)

### Description
Deletes a specific chat from Gemini history on the server.

### Parameters
- **cid** (string) - Required - The unique identifier of the chat to delete.
```

--------------------------------

### Delete Chat History

Source: https://pypi.org/project/gemini-webapi

Remove a specific conversation from the server history using the chat ID.

```python
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())
```
Tokens:
Raw