Gemini-API: Der Web-Client als Schnittstelle, nicht die offizielle API

Warum jemand die Weboberfläche statt der offiziellen API anspricht

Das offizielle Python-SDK von Google deckt Text- und Bildeingaben ab. Es deckt nicht alles ab, was die Weboberfläche gemini.google.com kann. Genau dort setzt dieses Projekt an: Es ist laut README ein reverse-engineered, asynchroner Wrapper für die Web-App, früher Bard. Die Zielgruppe sind Entwickler, die Funktionen der Weboberfläche programmatisch nutzen wollen, die über die offizielle Schnittstelle nicht erreichbar sind. Das README nennt konkret Video- und Audioerzeugung, Deep Research mit Planerstellung und Statusabfrage, Gemini Gems als System-Prompt sowie Extensions wie YouTube und Gmail. Dazu kommen Dinge, die eher den Web-Client als eine API betreffen: andere Antwortkandidaten durchschalten, den Gedankengang des Modells auslesen, den bisherigen Gesprächsverlauf lesen und löschen. Wer eine stabile, vertraglich abgesicherte Schnittstelle für ein Produkt sucht, ist hier falsch. Wer ein persönliches Werkzeug oder eine Automatisierung für den eigenen Account baut, findet Funktionen, die sonst nur im Browser existieren.

Cookie, Client und der Hintergrundprozess dazwischen

Der Mechanismus ist keine API im üblichen Sinn. Statt eines API-Schlüssels authentifiziert sich das Paket mit den Cookies `__Secure-1PSID` und `__Secure-1PSIDTS`, die man laut README aus dem Netzwerk-Tab der Browser-Entwicklertools kopiert. Damit tritt die Bibliothek gegenüber Google als Browser-Sitzung auf. Der zweite Baustein ist die Cookie-Aktualisierung: Das README beschreibt eine automatische Erneuerung im Hintergrund, die standardmäßig aktiv ist und ausdrücklich nicht von `browser-cookie3` abhängt. Für Dienste, die dauerhaft laufen, ist das der eigentliche Kern, denn abgelaufene Cookies sind der wahrscheinlichste Ausfallgrund. Die Nebenwirkung steht ebenfalls im README: Die Aktualisierung kann dazu führen, dass man sich im Browser erneut bei Google anmelden muss. Wer das vermeiden will, soll die Cookies aus einer separaten Sitzung beziehen. In Docker-Umgebungen lässt sich der Speicherort über die Umgebungsvariable `GEMINI_COOKIE_PATH` festlegen, damit die erneuerten Cookies ein Volume überleben. Ohne dieses Volume beginnt jeder Container-Neubau mit der ursprünglichen Authentifizierung. Die Antworten selbst kommen klassifiziert zurück: Text, Gedanken, Bilder, Videos und Audio werden getrennt ausgewiesen, und im Streaming-Modus liefert die Bibliothek Teilausgaben, während sie entstehen.

Installation, Authentifizierung und der schnellste Weg zum ersten Aufruf

Die Installation ist einzeilig und verlangt Python 3.11 oder neuer: `pip install -U gemini_webapi`. Wer die Cookies automatisch aus dem lokalen Browser importieren will, installiert stattdessen `gemini_webapi[browser]`; laut README wird derzeit nur Firefox unterstützt, Details zur Browserunterstützung liegen im Repository von `browser-cookie3`. Mit installiertem Extra entfällt der manuelle Schritt, sofern man in Firefox bei gemini.google.com angemeldet ist. Ohne das Extra bleibt der dokumentierte Ablauf: Anmeldung bei gemini.google.com, F12, Netzwerk-Tab, Seite neu laden, eine beliebige Anfrage anklicken und die Werte der beiden Cookies kopieren. Für containerisierte Deployments zeigt das README ein `docker-compose.yml`-Fragment, das `GEMINI_COOKIE_PATH: /tmp/gemini_webapi` setzt und `./gemini_cookies` auf genau diesen Pfad mountet. Der Pfad muss für die Anwendung beschreibbar sein, sonst schlägt die Aktualisierung fehl. Neben der Bibliothek gibt es ein eigenständiges CLI-Werkzeug mit eigener Cookie-Einrichtung und eigenen Befehlen, das im README einen eigenen Abschnitt hat. Wer die Bibliothek nur ausprobieren will, kann diesen Weg nehmen, ohne Python-Code zu schreiben.

Wo das Modell an seine Grenzen stößt

Die wichtigste Einschränkung steht nicht als Warnung im README, sondern ergibt sich aus dem Aufbau: Alles hängt an einem Google-Konto und dessen Cookies. Das ist kein austauschbarer Schlüssel, sondern eine Sitzung, die Google jederzeit beenden kann. Die Dokumentation räumt ein, dass die automatische Aktualisierung eine erneute Browser-Anmeldung erzwingen kann. Ein Dienst, der auf einem geteilten Konto läuft, teilt damit auch dessen Kontingente und dessen Risiko. Für Multi-Tenant-Anwendungen, bei denen jeder Nutzer eigene Limits haben soll, fehlt die Grundlage. Dazu kommt die Abhängigkeit von der Weboberfläche selbst: Ändert Google die internen Endpunkte, bricht der Wrapper, bis jemand nachzieht. Die Release-Historie zeigt genau dieses Muster. Zwischen v2.0.0 im April 2026 und v2.1.0 im August 2026 liegt ein größerer Sprung, v2.1.1 folgte zwölf Tage später als Korrektur. Solche Versionssprünge sind ein Hinweis darauf, dass sich die zugrunde liegende Schnittstelle bewegt. Wer keine Kapazität hat, bei einem Bruch kurzfristig zu reagieren, sollte den Wrapper nicht als tragende Schicht einsetzen.

Was die offizielle Gemini-API anders macht

Die naheliegende Alternative ist das offizielle Python-SDK von Google, das im README selbst als Vorbild für die Oberfläche genannt wird: Die Bibliothek bietet laut Feature-Liste einen "Official Flavor" mit einer Schnittstelle, die an die offizielle Generative-AI-Bibliothek angelehnt ist. Der Unterschied liegt nicht in der Syntax, sondern im Vertragsverhältnis. Die offizielle API arbeitet mit API-Schlüsseln und projektbezogenen Kontingenten, nicht mit Browser-Cookies. Sie ist an dokumentierte Endpunkte gebunden, die Google als Produkt pflegt, und sie bringt Abrechnung, Quotas und Support mit. Dafür fehlen ihr die Funktionen, die nur in der Weboberfläche existieren: Deep Research, Gems als System-Prompt, Extensions wie Gmail und YouTube, das Durchschalten alternativer Antwortkandidaten. Wer diese Funktionen braucht, kann sie nicht durch die offizielle API ersetzen. Wer sie nicht braucht, sollte die offizielle API nehmen, weil sie die stabilere Grundlage ist. Die Wahl ist damit keine Geschmacksfrage, sondern eine Frage, welche Funktionen tatsächlich im Lastenheft stehen.

Pflegeaufwand und was die AGPL-3.0 praktisch bedeutet

Die Pflegekosten liegen nicht im Paket, sondern in der Umgebung. Cookies müssen beschaffbar und erneuerbar bleiben, der Pfad in `GEMINI_COOKIE_PATH` muss persistent und beschreibbar sein, und nach jedem grünen Update ist zu prüfen, ob die verwendeten Funktionen noch tragen. Das Paket wird über PyPI verteilt, die CI veröffentlicht laut Repository-Aufbau über einen GitHub-Actions-Workflow. Ein Update ist ein `pip install -U gemini_webapi`, aber die Versionsnummern sagen nichts über Bruchfreiheit: Der Sprung von v2.0.0 auf v2.1.0 innerhalb weniger Monate deutet auf Änderungen an den internen Aufrufen hin. Zur Lizenz: Das Projekt steht unter AGPL-3.0. Diese Lizenz verlangt, dass abgeleitete Werke ebenfalls unter AGPL-3.0 stehen, und sie enthält eine Netzwerkklausel, die bei Nutzung über ein Netzwerk zusätzliche Pflichten auslösen kann. Ob das für den eigenen Fall greift, hängt davon ab, ob man das Paket unverändert einbindet, verändert oder als Dienst betreibt. Das ist keine Rechtsberatung, und die Grenze zwischen interner Nutzung und Weitergabe sollte man vor dem Einsatz mit der eigenen Rechtsabteilung klären. Wer den Code in ein proprietäres Produkt einbetten will, hat hier eine ernsthafte Hürde.

Für wen sich der Wrapper lohnt und für wen nicht

Der sinnvolle Einsatz ist ein persönlicher oder interner Dienst auf einem eigenen Google-Konto, der Funktionen der Weboberfläche braucht, die die offizielle API nicht bietet. Ein Bot, der auf Zuruf Bilder erzeugt und bearbeitet, ein Werkzeug, das Deep Research startet und den Fortschritt abfragt, oder eine Automatisierung, die einen Custom Gem als System-Prompt verwendet: Für diese Fälle ist die Bibliothek gebaut, und das README dokumentiert sie bis auf die Ebene einzelner Aufrufe. Nicht geeignet ist sie für Produkte mit Verfügbarkeitszusagen, für Dienste, bei denen Nutzer eigene Kontingente erwarten, und für Umgebungen, in denen kein Google-Login möglich oder erlaubt ist. Auch wer die AGPL-3.0 nicht mit seinem Vertriebsmodell vereinbaren kann, sollte Abstand nehmen. Vor dem ersten Deployment sind drei Dinge konkret zu prüfen: ob `__Secure-1PSID` und `__Secure-1PSIDTS` in der Zielumgebung beschaffbar sind, ob das Volume hinter `GEMINI_COOKIE_PATH` beschreibbar bleibt, und ob die verwendeten Funktionen nach einem Update noch existieren. Der letzte Punkt ist keine Formalie. Er entscheidet, ob der Wrapper ein Werkzeug bleibt oder zu einer dauerhaften Wartungsaufgabe wird.

Redaktionelles Fazit

Wer Bild-, Video- und Audioausgabe, Gems als System-Prompt oder Deep Research aus Python heraus braucht und bereit ist, einen Google-Account per Cookie zu binden, findet hier eine dokumentierte Lösung. Für Produktionssysteme mit SLA, für Multi-Tenant-Dienste und für alles, was ohne Google-Login laufen muss, ist es das falsche Werkzeug. Vor dem Einsatz zu prüfen: ob `__Secure-1PSID` und `__Secure-1PSIDTS` in der Zielumgebung überhaupt beschaffbar sind, ob `GEMINI_COOKIE_PATH` auf einem beschreibbaren Volume liegt, und ob die AGPL-3.0-Bedingungen mit der eigenen Weitergabeform vereinbar sind.

Offizielle Quellen

1. HanaokaYuzu/Gemini-API on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases