gemini-webapi 1.9.0__tar.gz → 1.17.0__tar.gz

{gemini_webapi-1.9.0 → gemini_webapi-1.17.0}/.github/workflows/github-release.yml

@@ -11,7 +11,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: ncipollo/release-action@v1
         with:
           body: ${{ github.event.head_commit.message }}

{gemini_webapi-1.9.0 → gemini_webapi-1.17.0}/.github/workflows/pypi-publish.yml

@@ -24,9 +24,9 @@ jobs:
     name: Build package
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.x'
       - name: Install dependencies
@@ -36,7 +36,7 @@ jobs:
       - name: Build package
         run: python -m build
       - name: Archive production artifacts
-        uses: actions/upload-artifact@v4.6.0
+        uses: actions/upload-artifact@v4.6.2
         with:
           name: dist
           path: dist
@@ -52,9 +52,9 @@ jobs:
       id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
     steps:
       - name: Retrieve built artifacts
-        uses: actions/download-artifact@v4.1.8
+        uses: actions/download-artifact@v5.0.0
         with:
           name: dist
           path: dist
       - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@v1.12.4
+        uses: pypa/gh-action-pypi-publish@v1.13.0

{gemini_webapi-1.9.0 → gemini_webapi-1.17.0}/.gitignore

@@ -201,4 +201,4 @@ Temporary Items
 .apdisk
 
 # Temporary files
-temp/
+.temp/

{gemini_webapi-1.9.0 → gemini_webapi-1.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: gemini-webapi
-Version: 1.9.0
+Version: 1.17.0
 Summary: ✨ An elegant async Python wrapper for Google Gemini web app
 Author: UZQueen
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -677,8 +677,10 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx[http2]~=0.28.1
-Requires-Dist: pydantic~=2.10.5
 Requires-Dist: loguru~=0.7.3
+Requires-Dist: orjson~=3.11.1
+Requires-Dist: pydantic~=2.12.2
+Dynamic: license-file
 
 <p align="center">
     <img src="https://raw.githubusercontent.com/HanaokaYuzu/Gemini-API/master/assets/banner.png" width="55%" alt="Gemini Banner" align="center">
@@ -711,9 +713,10 @@ A reverse-engineered asynchronous python wrapper for [Google Gemini](https://gem
 ## Features
 
 - **Persistent Cookies** - Automatically refreshes cookies in background. Optimized for always-on services.
-- **ImageFx Support** - Supports retrieving images generated by ImageFx, Google's latest AI image generator.
+- **Image Generation** - Natively supports generating and editing images with natural language.
+- **System Prompt** - Supports customizing model's system prompt with [Gemini Gems](https://gemini.google.com/gems/view).
 - **Extension Support** - Supports generating contents with [Gemini extensions](https://gemini.google.com/extensions) on, like YouTube and Gmail.
-- **Classified Outputs** - Automatically categorizes texts, web images and AI generated images in the response.
+- **Classified Outputs** - Categorizes texts, thoughts, web images and AI generated images in the response.
 - **Official Flavor** - Provides a simple and elegant interface inspired by [Google Generative AI](https://ai.google.dev/tutorials/python_quickstart)'s official API.
 - **Asynchronous** - Utilizes `asyncio` to run generating tasks and return outputs efficiently.
 
@@ -725,18 +728,22 @@ A reverse-engineered asynchronous python wrapper for [Google Gemini](https://gem
 - [Authentication](#authentication)
 - [Usage](#usage)
   - [Initialization](#initialization)
-  - [Select language model](#select-language-model)
-  - [Generate contents from text](#generate-contents-from-text)
-  - [Generate contents from image](#generate-contents-from-image)
+  - [Generate contents](#generate-contents)
+  - [Generate contents with files](#generate-contents-with-files)
   - [Conversations across multiple turns](#conversations-across-multiple-turns)
   - [Continue previous conversations](#continue-previous-conversations)
+  - [Select language model](#select-language-model)
+  - [Apply system prompt with Gemini Gems](#apply-system-prompt-with-gemini-gems)
+  - [Manage Custom Gems](#manage-custom-gems)
+    - [Create a custom gem](#create-a-custom-gem)
+    - [Update an existing gem](#update-an-existing-gem)
+    - [Delete a custom gem](#delete-a-custom-gem)
   - [Retrieve model's thought process](#retrieve-models-thought-process)
   - [Retrieve images in response](#retrieve-images-in-response)
-  - [Generate images with ImageFx](#generate-images-with-imagefx)
-  - [Save images to local files](#save-images-to-local-files)
+  - [Generate and edit images](#generate-and-edit-images)
   - [Generate contents with Gemini extensions](#generate-contents-with-gemini-extensions)
   - [Check and switch to other reply candidates](#check-and-switch-to-other-reply-candidates)
-  - [Control log level](#control-log-level)
+  - [Logging Configuration](#logging-configuration)
 - [References](#references)
 - [Stargazers](#stargazers)
 
@@ -748,13 +755,13 @@ A reverse-engineered asynchronous python wrapper for [Google Gemini](https://gem
 
 Install/update the package with pip.
 
-```bash
+```sh
 pip install -U gemini_webapi
 ```
 
 Optionally, package offers a way to automatically import cookies from your local browser. To enable this feature, install `browser-cookie3` as well. Supported platforms and browsers can be found [here](https://github.com/borisbabic/browser_cookie3?tab=readme-ov-file#contribute).
 
-```bash
+```sh
 pip install -U browser-cookie3
 ```
 
@@ -770,15 +777,17 @@ pip install -U browser-cookie3
 
 > [!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.
+> 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:
 
 ```yaml
 services:
-    main:
-        volumes:
-            - ./gemini_cookies:/usr/local/lib/python3.12/site-packages/gemini_webapi/utils/temp
+  main:
+    environment:
+      GEMINI_COOKIE_PATH: /tmp/gemini_webapi
+    volumes:
+      - ./gemini_cookies:/tmp/gemini_webapi
 ```
 
 > [!NOTE]
@@ -816,44 +825,9 @@ asyncio.run(main())
 >
 > `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 chatbot, it's recommended to set `auto_close` to `True` combined with reasonable seconds of `close_delay` for better resource management.
 
-### Select language model
-
-You can specify which language model to use by passing `model` argument to `GeminiClient.generate_content` or `GeminiClient.start_chat`. The default value is `unspecified`.
-
-Currently available models (as of Feb 5, 2025):
-
-- `unspecified` - Default model (same as `gemini-2.0-flash` if account does NOT have Gemini Advanced subscription)
-- `gemini-2.0-flash` - Gemini 2.0 Flash
-- `gemini-2.0-flash-thinking` - Gemini 2.0 Flash Thinking Experimental
-- `gemini-2.0-flash-thinking-with-apps` - Gemini 2.0 Flash Thinking Experimental with apps
-- `gemini-1.5-flash` - Gemini 1.5 Flash
-
-Models pending update (may not work as expected):
+### Generate contents
 
-- `gemini-2.0-exp-advanced` - Gemini 2.0 Experimental Advanced **(requires Gemini Advanced account)**
-- `gemini-1.5-pro` - Gemini 1.5 Pro **(requires Gemini Advanced account)**
-- `gemini-1.5-pro-research` - Gemini 1.5 Pro with Deep Research **(requires Gemini Advanced account)**
-
-```python
-from gemini_webapi.constants import Model
-
-async def main():
-    response1 = await client.generate_content(
-        "What's you language model version? Reply version number only.",
-        model=Model.G_2_0_FLASH,
-    )
-    print(f"Model version ({Model.G_2_0_FLASH.model_name}): {response1.text}")
-
-    chat = client.start_chat(model="gemini-2.0-flash-thinking")
-    response2 = await chat.send_message("What's you language model version? Reply version number only.")
-    print(f"Model version (gemini-2.0-flash-thinking): {response2.text}")
-
-asyncio.run(main())
-```
-
-### Generate contents from text
-
-Ask a one-turn quick question by calling `GeminiClient.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.
 
 ```python
 async def main():
@@ -867,15 +841,15 @@ asyncio.run(main())
 >
 > Simply use `print(response)` to get the same output if you just want to see the response text
 
-### Generate contents from image
+### Generate contents with files
 
-Gemini supports image recognition and generating contents from images. Optionally, you can pass images in a list of file data in `bytes` or their paths in `str` or `pathlib.Path` to `GeminiClient.generate_content` together with text prompt.
+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 text prompt.
 
 ```python
 async def main():
     response = await client.generate_content(
-            "Describe each of these images",
-            images=["assets/banner.png", "assets/favicon.png"],
+            "Introduce the contents of these two files. Is there any connection between them?",
+            files=["assets/sample.pdf", Path("assets/banner.png")],
         )
     print(response.text)
 
@@ -884,14 +858,20 @@ asyncio.run(main())
 
 ### Conversations across multiple turns
 
-If you want to keep conversation continuous, please use `GeminiClient.start_chat` to create a `ChatSession` object and send messages through it. The conversation history will be automatically handled and get updated after each turn.
+If you want to keep conversation continuous, please use `GeminiClient.start_chat` to create a `gemini_webapi.ChatSession` object and send messages through it. The conversation history will be automatically handled and get updated after each turn.
 
 ```python
 async def main():
     chat = client.start_chat()
-    response1 = await chat.send_message("Briefly introduce Europe")
-    response2 = await chat.send_message("What's the population there?")
-    print(response1.text, response2.text, sep="\n\n----------------------------------\n\n")
+    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())
 ```
@@ -921,6 +901,139 @@ async def main():
 asyncio.run(main())
 ```
 
+### Select language model
+
+You can specify which language model to use by passing `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-2.5-pro` - Gemini 2.5 Pro
+- `gemini-2.5-flash` - Gemini 2.5 Flash
+
+```python
+from gemini_webapi.constants import Model
+
+async def main():
+    response1 = await client.generate_content(
+        "What's you language model version? Reply version number only.",
+        model=Model.G_2_5_FLASH,
+    )
+    print(f"Model version ({Model.G_2_5_FLASH.model_name}): {response1.text}")
+
+    chat = client.start_chat(model="gemini-2.5-pro")
+    response2 = await chat.send_message("What's you language model version? Reply version number only.")
+    print(f"Model version (gemini-2.5-pro): {response2.text}")
+
+asyncio.run(main())
+```
+
+### Apply system prompt with Gemini Gems
+
+System prompt can be applied to conversations via [Gemini Gems](https://gemini.google.com/gems/view). To use a gem, you can pass `gem` argument to `GeminiClient.generate_content` or `GeminiClient.start_chat`. `gem` can be either a string of gem id or a `gemini_webapi.Gem` object. Only one gem can be applied to a single conversation.
+
+> [!TIP]
+>
+> There are some system predefined gems that by default are not shown to users (and therefore may not work properly). Use `client.fetch_gems(include_hidden=True)` to include them in the fetch result.
+
+```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?",
+        model=Model.G_2_5_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:
+
+```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())
+```
+
+#### Update an existing gem
+
+> [!NOTE]
+>
+> When updating a gem, you must provide all parameters (name, prompt, description) even if you only want to change one of them.
+
+```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())
+```
+
+#### Delete a custom gem
+
+```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())
+```
+
 ### Retrieve model's thought process
 
 When using models with thinking capabilities, the model's thought process will be populated in `ModelOutput.thoughts`.
@@ -928,7 +1041,7 @@ When using models with thinking capabilities, the model's thought process will b
 ```python
 async def main():
     response = await client.generate_content(
-            "What's 1+1?", model="gemini-2.0-flash-thinking"
+            "What's 1+1?", model="gemini-2.5-pro"
         )
     print(response.thoughts)
     print(response.text)
@@ -938,7 +1051,7 @@ asyncio.run(main())
 
 ### Retrieve images in response
 
-Images in the API's output are stored as a list of `Image` objects. You can access the image title, URL, and description by calling `image.title`, `image.url` and `image.alt` respectively.
+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.
 
 ```python
 async def main():
@@ -949,24 +1062,27 @@ async def main():
 asyncio.run(main())
 ```
 
-### Generate images with ImageFx
+### Generate and edit images
 
-In February 2022, Google introduced a new AI image generator called ImageFx and integrated it into Gemini. You can ask Gemini to generate images with ImageFx simply by natural language.
+You can ask Gemini to generate and edit images with Nano Banana, Google's latest image model, simply by natural language.
 
 > [!IMPORTANT]
 >
-> Google has some limitations on the image generation feature in Gemini, so its availability could be different per region/account. Here's a summary copied from [official documentation](https://support.google.com/gemini/answer/14286560) (as of February 15th, 2024):
+> Google has some limitations on the image generation feature in Gemini, so its availability could be different per region/account. Here's a summary copied from [official documentation](https://support.google.com/gemini/answer/14286560) (as of Sep 10, 2025):
 >
-> > Image generation in Gemini Apps is available in most countries, except in the European Economic Area (EEA), Switzerland, and the UK. It’s only available for **English prompts**.
-> >
 > > This feature’s availability in any specific Gemini app is also limited to the supported languages and countries of that app.
 > >
 > > For now, this feature isn’t available to users under 18.
+> >
+> > To use this feature, you must be signed in to Gemini Apps.
+
+You can save images returned from Gemini to local 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`. Works for both `WebImage` and `GeneratedImage`.
 
 ```python
 async def main():
     response = await client.generate_content("Generate some pictures of cats")
-    for image in response.images:
+    for i, image in enumerate(response.images):
+        await image.save(path="temp/", filename=f"cat_{i}.png", verbose=True)
         print(image, "\n\n----------------------------------\n")
 
 asyncio.run(main())
@@ -976,32 +1092,17 @@ asyncio.run(main())
 >
 > by default, when asked to send images (like the previous example), Gemini will send images fetched from web instead of generating images with AI model, unless you specifically require to "generate" images in your prompt. In this package, web images and generated images are treated differently as `WebImage` and `GeneratedImage`, and will be automatically categorized in the output.
 
-### Save images to local files
-
-You can save images returned from Gemini to local files under `/temp` 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`. Works for both `WebImage` and `GeneratedImage`.
-
-```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)
-
-asyncio.run(main())
-```
-
 ### Generate contents with Gemini extensions
 
 > [!IMPORTANT]
 >
-> To access Gemini extensions in API, you must activate them on the [Gemini website](https://gemini.google.com/extensions) first. Same as image generation, Google also has limitations on the availability of Gemini extensions. Here's a summary copied from [official documentation](https://support.google.com/gemini/answer/13695044) (as of February 18th, 2024):
+> To access Gemini extensions in API, you must activate them on the [Gemini website](https://gemini.google.com/extensions) first. Same as image generation, Google also has limitations on the availability of Gemini extensions. Here's a summary copied from [official documentation](https://support.google.com/gemini/answer/13695044) (as of March 19th, 2025):
 >
-> > To use extensions in Gemini Apps:
-> >
-> > Sign in with your personal Google Account that you manage on your own. Extensions, including the Google Workspace extension, are currently not available to Google Workspace accounts for school, business, or other organizations.
+> > To connect apps to Gemini, you must have​​​​ Gemini Apps Activity on.
 > >
-> > Have Gemini Apps Activity on. Extensions are only available when Gemini Apps Activity is turned on.
+> > To use this feature, you must be signed in to Gemini Apps.
 > >
-> > Important: For now, extensions are available in **English, Japanese, and Korean** only.
+> > Important: If you’re under 18, Google Workspace and Maps apps currently only work with English prompts in Gemini.
 
 After activating extensions for your account, you can access them in your prompts either by natural language or by starting your prompt with "@" followed by the extension keyword.
 
@@ -1022,7 +1123,7 @@ asyncio.run(main())
 
 ### Check and switch to other reply candidates
 
-A response from Gemini usually contains multiple reply candidates with different generated contents. You can check all candidates and choose one to continue the conversation. By default, the first candidate will be chosen automatically.
+A response from Gemini sometimes contains multiple reply candidates with different generated contents. You can check all candidates and choose one to continue the conversation. By default, the first candidate will be chosen.
 
 ```python
 async def main():
@@ -1043,9 +1144,9 @@ async def main():
 asyncio.run(main())
 ```
 
-### Control log level
+### Logging Configuration
 
-You can set the log level of the package to one of the following values: `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL`. The default value is `INFO`.
+This package uses [loguru](https://loguru.readthedocs.io/en/stable/) for logging, and exposes a function `set_log_level` to control log level. You can set log level to one of the following values: `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL`. The default value is `INFO`.
 
 ```python
 from gemini_webapi import set_log_level
@@ -1053,6 +1154,10 @@ from gemini_webapi import set_log_level
 set_log_level("DEBUG")
 ```
 
+> [!NOTE]
+>
+> Calling `set_log_level` for the first time will **globally** remove all existing loguru handlers. You may want to configure logging directly with loguru to avoid this issue and have more advanced control over logging behaviors.
+
 ## References
 
 [Google AI Studio](https://ai.google.dev/tutorials/ai-studio_quickstart)