Gemini-API: A Reverse-Engineered Python Client for the Gemini Web App
✨ Reverse-engineered Python API for Google Gemini web app
At a glance
- What is it?
- Gemini-API wraps Google's Gemini web interface in an async Python library, offering cookie refresh, image generation, and deep research. It is powerful for personal automation, but its reverse-engineered nature and AGPL license demand careful evaluation.
- Who is it for?
- Adopt Gemini-API if you are a Python developer building personal or internal tools that need to automate interactions with the Gemini web app, including image generation or deep research, and you accept the AGPL-3.0 license and the risk of breakage from undocumented web changes. Do not use it for production services that depend on stable, officially supported APIs, especially if you need a commercial-friendly license or guaranteed uptime.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 19 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Gemini-API Solves and Who It Serves
Gemini-API addresses a specific gap: developers who want to use Google's Gemini models without paying for the official API or dealing with its rate limits. The project reverse-engineers the gemini.google.com web app, which is free for consumer use, and exposes it through a Python interface. The intended users are hobbyists, researchers, and automation builders who want to script conversations, generate images, or run deep research tasks using their personal Google account. It is not a substitute for the official Generative AI API in a commercial product. The README makes clear it is a wrapper for the web app, not a sanctioned backend, which immediately signals a different risk profile than using ai.google.dev endpoints.
How the Library Works: Web App Internals and Async Wrapping
The library operates by mimicking the requests that the Gemini web app makes to its internal endpoints. It uses asyncio for concurrency, which suits always-on services that need to handle multiple generation tasks. A key mechanism is the persistent cookie management. The library automatically refreshes cookies in the background, which is essential because the web app's authentication tokens expire. This refresh happens without requiring browser-cookie3, but if that optional dependency is installed, cookies can be imported automatically from a Firefox browser. The response handling categorizes outputs into text, thoughts, images, videos, and audio, which suggests the library parses the web app's structured response payloads. The design mimics the official Google Generative AI Python API's style, so developers familiar with that SDK can adapt quickly. The library also supports streaming, yielding partial outputs as they arrive. This is a thin wrapper over undocumented endpoints, so the data flow is entirely dependent on the web app's current behavior.
Getting It Running: Installation and Authentication
Installation requires Python 3.11 or higher. The command is straightforward: pip install -U gemini_webapi. For browser cookie import, you install gemini_webapi[browser], but only Firefox is supported at this time, according to the README. Authentication is manual unless you use the browser-cookie3 path. You must log in to gemini.google.com, open the developer tools, go to the Network tab, and copy the values for __Secure-1PSID and __Secure-1PSIDTS from any request. Those two cookies are the core credentials. For containerized deployments, the README recommends setting the GEMINI_COOKIE_PATH environment variable to a writable volume path so auto-refreshed cookies persist across container rebuilds. The README includes a docker-compose snippet showing that environment variable paired with a volume mount. The auto-cookie-refresh feature is enabled by default and does not require browser-cookie3. It may occasionally require you to re-login in your browser, which is expected and does not disrupt the API. This setup is more involved than using an official API key, but it avoids per-token costs.
Feature Breadth: Beyond Text Generation
The feature list goes far beyond simple chat. The library supports image generation and editing with natural language, video and audio generation, and a full deep research workflow that includes plan creation, status polling, and result retrieval. It also handles Gemini Gems for system prompts, including creating, updating, and deleting custom gems. Extensions such as YouTube and Gmail can be used to generate content. The response object separates thoughts from final text, which is useful for debugging or for surfacing the model's reasoning. There is also support for reading conversation history, deleting past conversations, and switching between reply candidates. These features map to capabilities that the web app exposes, so they are not available through the official API, which is a strong reason to consider this library. The CLI tool provides a standalone interface for quick interactions, which lowers the barrier for testing without writing Python code.
Limitations and Failure Modes
The most significant limitation is that this library depends on reverse-engineered endpoints. Google can change the web app's internal API at any time, which would break the library until a fix is released. The README does not mention any fallback or official API support. Another limitation is the authentication fragility. The manual cookie extraction is a one-time step, but cookie refresh may require re-authentication in the browser, which can be disruptive in headless or always-on environments. The README warns about this behavior, but it is a real operational burden. The browser-cookie3 dependency only supports Firefox, so Chrome or Edge users must manually copy cookies. There is also no mention of rate limits or usage policies for the web app, which could lead to account restrictions if abused. For production workloads, this is the wrong tool because there is no SLA, no guaranteed uptime, and no official support. The library is best for personal scripts and prototypes where occasional breakage is acceptable.
A Real Alternative: Official Google Generative AI SDK
The obvious alternative is the official Google Generative AI Python SDK, which the README explicitly says its interface is inspired by. That SDK uses an API key and hits sanctioned endpoints at ai.google.dev. The core difference is stability and licensing. The official SDK is backed by Google, has documented rate limits, and is intended for production use. However, it does not offer the web app features that Gemini-API exposes, such as image editing, video generation, or deep research workflows. The official API also requires payment beyond a free tier, while Gemini-API uses your free consumer account. If you need those advanced generation features and are willing to accept the reverse-engineering risk, Gemini-API is the only option in this comparison. If you need reliability and a clear commercial path, the official SDK is the safer choice, even if it means losing some capabilities.
Maintenance and License Considerations
The repository shows recent activity, with releases in August 2026, suggesting active maintenance. The last push date is 2026-08-27, and the project is not archived. That is a positive signal, but reverse-engineered projects can die quickly if the maintainer loses interest or Google changes protocols. The license is AGPL-3.0, which has significant implications. If you use this library in a network service, the AGPL requires you to offer the complete source code of that service to users. That is a strong copyleft condition that many companies cannot accept. The README does not include any dual licensing or commercial exception. The package is on PyPI, so installation is easy, but the license is a real barrier for proprietary or closed-source projects. Before adopting, you should read the full AGPL text and consult a lawyer if you are unsure. The dependency tree is small, but browser-cookie3 is an optional extra that brings its own maintenance risks.
Editorial conclusion
Adopt Gemini-API if you are a Python developer building personal or internal tools that need to automate interactions with the Gemini web app, including image generation or deep research, and you accept the AGPL-3.0 license and the risk of breakage from undocumented web changes. Do not use it for production services that depend on stable, officially supported APIs, especially if you need a commercial-friendly license or guaranteed uptime. Before adopting, verify the current authentication flow, test that cookie refresh works in your environment, and check the repository's issue tracker for recent breakage reports. The project is actively maintained as of late 2026, but the underlying web app can change without notice, so budget for periodic maintenance.
Community notes