Gemini-API : piloter l'application web Gemini depuis Python, sans cle d'API officielle
✨ Reverse-engineered Python API for Google Gemini web app
En bref
- De quoi s’agit-il ?
- Le paquet gemini_webapi encapsule l'interface web de Gemini en client asyncio. Il resout le probleme des cookies et des fonctions absentes de l'API officielle, au prix d'une dependance a un service non documente et d'une licence AGPL-3.0.
- À qui s’adresse-t-il ?
- A adopter si vous avez besoin des fonctions de l'application web (images, videos, Deep Research, Gems) et que vous acceptez de dependre d'un service non documente sous AGPL-3.0. A eviter si votre produit doit rester ferme ou si vous exigez un contrat de disponibilite.
- Puis-je l’utiliser commercialement ?
- Oui, sous conditions strictes. AGPL-3.0 est une licence à copyleft réseau : si des personnes utilisent une version modifiée via un réseau, par exemple comme service hébergé, vous devez leur proposer son code source sous la même licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 19 jours.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le probleme : l'API officielle ne couvre pas tout ce que fait le site
Google expose une API Generative Language documentee, avec des cles, des quotas et des conditions d'utilisation claires. Mais certaines fonctions visibles sur gemini.google.com n'y figurent pas au meme niveau : generation et edition d'images en langage naturel, generation de videos et d'audio, Deep Research, extensions YouTube et Gmail, Gems comme prompt systeme. Gemini-API prend le probleme par l'autre bout. Au lieu de parler a un point d'entree public, il reproduit les requetes que le navigateur envoie a l'application web, en reutilisant la session Google de l'utilisateur. Le public vise est donc precis : developpeurs Python qui veulent automatiser leur propre compte Gemini, prototyper un agent, ou exposer ces fonctions dans un outil interne. Ce n'est pas un remplacement de l'API officielle pour un produit commercial, et le README ne le presente pas comme tel.
Ce qui circule entre votre code et les serveurs de Google
L'authentification repose sur deux cookies : __Secure-1PSID et __Secure-1PSIDTS, recuperes depuis l'inspecteur reseau du navigateur. Le client les stocke, puis les rafraichit en arriere-plan. Le README precise que ce rafraichissement automatique est active par defaut et ne depend pas de browser-cookie3. Il signale aussi un effet de bord assume : le compte Google peut redemander une connexion dans le navigateur apres coup, ce qui est decrit comme un comportement attendu sans incidence sur le fonctionnement de l'API. Les reponses ne sont pas renvoyees sous forme de texte brut. Le projet les classe en categories distinctes : texte, reflexions du modele, images, videos, audio. Le mode streaming restitue des sorties partielles au fil de la generation, et il est possible de consulter les autres candidats de reponse puis d'en selectionner un autre. La bibliotheque s'appuie sur asyncio, ce qui correspond a un usage ou plusieurs generations tournent en parallele.
Installation et premiers appels
Le paquet s'installe depuis PyPI avec pip install -U gemini_webapi, et il exige Python 3.11 ou superieur. Une variante existe pour importer les cookies directement depuis un navigateur local : pip install -U gemini_webapi[browser]. Elle depend de browser-cookie3, et le README indique que seul Firefox est pris en charge a ce jour, le suivi des navigateurs supportes renvoyant au depot browser-cookie3. Si vous n'utilisez pas cette option, il faut copier manuellement les deux cookies depuis l'inspecteur. En conteneur, le README recommande de definir la variable d'environnement GEMINI_COOKIE_PATH et de monter un volume sur ce chemin, avec un exemple de docker-compose.yml ou GEMINI_COOKIE_PATH vaut /tmp/gemini_webapi et ou ./gemini_cookies est monte sur ce meme repertoire. Le chemin doit etre accessible en ecriture par l'application, sinon le rafraichissement echoue. Un outil en ligne de commande autonome est fourni pour des interactions rapides, avec sa propre etape de configuration des cookies et ses commandes dediees.
Les fonctions qui justifient le detour
Trois domaines depassent ce qu'un simple appel texte permet. D'abord la generation et l'edition d'images en langage naturel, avec recuperation des images presentes dans une reponse. Ensuite les videos et l'audio, que le README liste comme sorties natives et classe separement des images. Enfin Deep Research, decrit comme un flux complet : creation du plan, interrogation repetee de l'etat d'avancement, puis recuperation du resultat, avec une procedure equivalente cote CLI. S'y ajoutent les Gems, utilises comme prompt systeme et gerables par le code (creation, mise a jour, suppression), et les extensions Gemini comme YouTube ou Gmail. La lecture de l'historique, la reprise d'une conversation anterieure, la suppression de conversations et un mode temporaire completent le tableau. C'est cette couverture, plus que l'acces au modele lui-meme, qui distingue le projet d'un client HTTP minimal.
Ce que le projet ne protege pas
Le point faible est structurel : rien dans le depot ne garantit la stabilite des points d'entree utilises. Le projet est presente comme reverse-engineere, ce qui signifie que les formats de requete et de reponse dependent d'une application web que Google fait evoluer sans preavis. Une mise a jour du site peut casser une fonction, et la correction dependra d'une nouvelle version du paquet. La cadence de publication est irreguliere : v2.0.0 en avril 2026, v2.1.0 en aout 2026, v2.1.1 le meme mois. Le saut de version majeure entre avril et aout suggere des ruptures d'API cote bibliotheque, donc un cout de migration pour les codebases existantes. Autre limite pratique : l'authentification par cookies lie l'usage a un compte personnel. Un service toujours actif qui rafraichit les cookies du compte peut provoquer des deconnexions dans le navigateur, ce que le README reconnait explicitement. Enfin, le paquet est sous AGPL-3.0, une licence copyleft forte avec des obligations de diffusion du code source pour les services exposes en reseau. Ce n'est pas un choix neutre pour un backend proprietaire, et je ne peux pas evaluer ici les consequences juridiques exactes de votre usage.
Face a l'API officielle et aux clients HTTP generiques
L'alternative la plus directe est l'API Generative Language de Google, dont le README s'inspire ouvertement pour la forme de l'interface, avec une syntaxe proche du quickstart officiel. La difference n'est pas cosmetique. L'API officielle s'appuie sur une cle, documente ses modeles et ses limites, et ne depend pas de vos cookies. Elle ne donne pas acces aux Gems, aux extensions Gmail et YouTube ni au flux Deep Research tel que le site le propose. Un client HTTP generique (requests, httpx) atteindrait les memes points d'entree que Gemini-API, mais vous devriez reconstituer vous-meme le rafraichissement des cookies, le decoupage des sorties classees, le streaming et la gestion des candidats de reponse. Le compromis est donc clair : l'API officielle achete la stabilite et la conformite, Gemini-API achete la couverture fonctionnelle du site au prix d'une dependance a du non documente.
Cout de maintenance et implications de licence
Le cout se decompose en trois postes. Le premier est le suivi de version : quand une rupture majeure survient, comme entre v2.0.0 et v2.1.0, il faut relire le code appelant et adapter les signatures. Le deuxieme est l'exploitation : le fichier de cookies doit vivre sur un volume persistant, via GEMINI_COOKIE_PATH, et ce stockage contient des identifiants de session Google. Le traiter comme un secret est un minimum, le README ne va pas plus loin sur ce point. Le troisieme est la licence. AGPL-3.0 impose, pour un logiciel modifie et mis a disposition via un reseau, de fournir le code source correspondant aux utilisateurs de ce service. Un outil interne non distribue reste dans une zone que je ne peux pas trancher ici. Si votre organisation interdit les dependances copyleft fortes, le paquet est ecarte d'office, quelle que soit sa qualite technique.
Conclusion éditoriale
A adopter si vous avez besoin des fonctions de l'application web (images, videos, Deep Research, Gems) et que vous acceptez de dependre d'un service non documente sous AGPL-3.0. A eviter si votre produit doit rester ferme ou si vous exigez un contrat de disponibilite. Avant de valider, verifiez que le rafraichissement automatique des cookies fonctionne dans votre environnement et que votre compte Google accepte d'etre deconnecte du navigateur.
Notes de la communauté