Gemini-API
A reverse-engineered asynchronous python wrapper for Google Gemini web app (formerly Bard).
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.
- Extension Support - Supports generating contents with Gemini extensions on, like YouTube and Gmail.
- Classified Outputs - Automatically categorizes texts, web images and AI generated images in the response.
- Official Flavor - Provides a simple and elegant interface inspired by Google Generative AI's official API.
- Asynchronous - Utilizes
asyncioto run generating tasks and return outputs efficiently.
Table of Contents
- Features
- Table of Contents
- Installation
- Authentication
- Usage
- Initialization
- Generate contents from text
- Generate contents from image
- Conversations across multiple turns
- Continue previous conversations
- Retrieve images in response
- Generate images with ImageFx
- Save images to local files
- Specify language model version
- Generate contents with Gemini extensions
- Check and switch to other reply candidates
- Control log level
- References
- Stargazers
Installation
Install/update the package with pip.
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.
pip install -U browser-cookie3
Authentication
- Go to https://gemini.google.com and login with your Google account
- Press F12 for web inspector, go to
Networktab and refresh the page - Click any request and copy cookie values of
__Secure-1PSIDand__Secure-1PSIDTS
services:
main:
volumes:
- ./gemini_cookies:/usr/local/lib/python3.12/site-packages/gemini_webapi/utils/temp
Usage
Initialization
Import required packages and initialize a client with your cookies obtained from the previous step. After a successful initialization, the API will automatically refresh __Secure-1PSIDTS in 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 contents from text
Ask a one-turn quick question by calling GeminiClient.generate_content.
async def main():
response = await client.generate_content("Hello World!")
print(response.text)
asyncio.run(main())
Generate contents from image
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.
async def main():
response = await client.generate_content(
"Describe each of these images",
images=["assets/banner.png", "assets/favicon.png"],
)
print(response.text)
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.
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")
asyncio.run(main())
Continue previous conversations
To manually retrieve previous conversations, you can pass previous ChatSession's metadata to GeminiClient.start_chat when creating a new ChatSession. Alternatively, you can persist previous metadata to a file or db if you need to access them 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())
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.
async def main():
response = await client.generate_content("Send me some pictures of cats")
for image in response.images:
print(image, "\n\n----------------------------------\n")
asyncio.run(main())
Generate images with ImageFx
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.
async def main():
response = await client.generate_content("Generate some pictures of cats")
for image in response.images:
print(image, "\n\n----------------------------------\n")
asyncio.run(main())
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.
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())
Specify language model version
You can choose a specified language model version by passing model argument to GeminiClient.generate_content or GeminiClient.start_chat. The default value is unspecified.
Currently available models (as of Dec 21, 2024):
unspecified- Default model (Gemini 1.5 Flash)gemini-1.5-flash- Gemini 1.5 Flashgemini-2.0-flash-exp- Gemini 2.0 Flash Experimental
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="gemini-1.5-flash",
)
print(f"Model version (gemini-1.5-flash): {response1.text}")
chat = client.start_chat(model=Model.G_2_0_FLASH_EXP)
response2 = await chat.send_message("What's you language model version? Reply version number only.")
print(f"Model version ({Model.G_2_0_FLASH_EXP.model_name}): {response2.text}")
asyncio.run(main())
Generate contents with Gemini extensions
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.
async def main():
response1 = await client.generate_content("@Gmail What's the latest message in my mailbox?")
print(response1, "\n\n----------------------------------\n")
response2 = await client.generate_content("@Youtube What's the latest activity of Taylor Swift?")
print(response2, "\n\n----------------------------------\n")
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.
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")
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 contents based on the chosen candidate
print(new_candidate, followup_response, sep="\n\n----------------------------------\n\n")
else:
print("Only one candidate available.")
asyncio.run(main())
Control log level
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.
from gemini_webapi import set_log_level
set_log_level("DEBUG")
References
Stargazers
Metadata
Release files for gemini-webapi 1.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gemini_webapi-1.8.0.tar.gz | 232.8 kB | With provenance | Details for gemini_webapi-1.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gemini_webapi-1.8.0-py3-none-any.whl | Python 3 | none | any | Details for gemini_webapi-1.8.0-py3-none-any.whl |
Total release size: 279.0 kB
Release files / gemini_webapi-1.8.0.tar.gz
| Download URL | gemini_webapi-1.8.0.tar.gz |
|---|---|
| Size | 232.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1772822b9b9bbca42f7ad42c920635a2d301b914be743c0fe01a35ee1494564b
|
|
BLAKE2b-256 checksum How to use checksums |
d0a63e33724f479bcebbcae631a696034e130710a0523ea8c1abecf506c22d5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.0.1 CPython/3.12.8
|
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 Dec 22, 2024.
Transparency logRelease files / gemini_webapi-1.8.0-py3-none-any.whl
| Download URL | gemini_webapi-1.8.0-py3-none-any.whl |
|---|---|
| Size | 46.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
411b13f7160284adafcf1a1d779fef4ea4594cdc738215ff4d93c85fde2a3031
|
|
BLAKE2b-256 checksum How to use checksums |
18664fa6e15c24c084bdeed88efe4eeefdce373eaf90aa7926713310a4189041
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.0.1 CPython/3.12.8
|
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 Dec 22, 2024.
Transparency logSecurity for gemini-webapi 1.8.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.
Attestation for gemini_webapi-1.8.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 Dec 22, 2024.
Transparency logA 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.