Gemini-API レビュー: 公式APIではなくWebアプリを叩く非同期Pythonラッパー

公式 SDK が埋めない差分を狙ったラッパー

Google が提供する Generative AI SDK は、API キーを発行してモデルを呼ぶ経路を想定している。Gemini-API が対象にしているのはそこではない。README は「reverse-engineered asynchronous Python wrapper for the Google Gemini web app」と述べており、gemini.google.com の画面が内部で使っている通信を Python から再現する。利用者像としては、API キー経由では触れない Web 側の機能、たとえば画像生成と編集、動画と音声の生成、Deep Research、Gemini Gems によるシステムプロンプト、YouTube や Gmail の拡張機能を、スクリプトから呼びたい人がまず浮かぶ。公式の課金体系ではなく、ブラウザでログインしている Google アカウントの権限で動く点が最大の違いであり、利点であり同時に最大のリスクでもある。

認証は __Secure-1PSID と __Secure-1PSIDTS の2枚の Cookie

API キーの代わりに使うのは Google アカウントのセッション Cookie である。README の手順はこうだ。gemini.google.com にログインし、F12 で開発者ツールを開き、Network タブでページを再読み込みし、任意のリクエストから __Secure-1PSID と __Secure-1PSIDTS の値をコピーする。この2つをクライアントに渡すと、以降はライブラリ側がバックグラウンドで Cookie を自動更新する。README はこの自動更新について、browser-cookie3 を必要とせず既定で有効だと説明しており、常時稼働のサービスを想定した設計だと読める。コンテナで動かす場合、再起動のたびに再認証する羽目にならないよう、環境変数 GEMINI_COOKIE_PATH で保存先を指定し、そこをボリュームに載せる。README の docker-compose.yml の例では /tmp/gemini_webapi を指定し、./gemini_cookies をマウントしている。パスは書き込み可能でなければならない。なお、この自動更新はブラウザ側で Google アカウントへの再ログインを求めることがあり、README はそれを想定内の挙動だと書いている。

インストールと最初の呼び出しまで

Python 3.11 以上が必須である。pip install -U gemini_webapi で入る。ローカルのブラウザから Cookie を取り込みたい場合はオプション依存の browser-cookie3 を使い、pip install -U gemini_webapi[browser] とする。README の時点で対応ブラウザは Firefox のみと明記されており、他のブラウザの状況は browser-cookie3 側のリポジトリを参照するよう案内されている。Cookie を手動で渡す場合は、取得した2つの値をクライアントの初期化時に指定する。以降は generate_content 系の呼び出しでテキスト、画像、動画、音声が返り、戻り値は種類ごとに分類される。ストリーミングモードでは生成の途中経過が逐次 yield され、Deep Research は計画作成、状態のポーリング、結果取得という段階を踏む。CLI も同梱されており、Cookie を設定したうえで単発のやり取りをコマンドラインから実行できる。

asyncio 前提の設計が効く場面と邪魔になる場面

ライブラリ全体が asyncio で組まれており、README も「Utilizes asyncio to run generation tasks and return outputs efficiently」と説明している。複数の生成を並行で走らせたいバッチ処理や、常駐させて Cookie を更新し続けるサービスでは、この設計は素直に噛み合う。逆に、既存の同期コードに数行だけ組み込みたい場合は、イベントループの管理を自分で引き受けることになる。ここは好みの話ではなく構造上のコストで、たとえば Django の同期ビューの中で気軽に呼ぶ、といった使い方は想定されていない。CLI が用意されているのは、そうした同期の世界にいる人がまず挙動を確かめるための逃げ道として読める。

Web アプリを叩くということは壊れる前提で使うということ

最大の制約は、これが非公開の内部通信に依存している点である。Google が Web アプリの通信形式やパラメータを変えれば、ライブラリ側の対応が必要になる。リリース履歴を見ると v2.0.0 が 2026-04-06、v2.1.0 が 2026-08-15、v2.1.1 が 2026-08-27 で、メジャー更新を含む改版が続いている。活発だという事実ではあるが、同時に追従が必要な対象が動き続けている証拠でもある。もう一点、認証がアカウントの Cookie に依存する以上、利用規約上の位置づけは公式 API とは異なる。README はこの点に踏み込んでおらず、私からも断定はできない。判断材料として README が示していないことは、明示されていないという事実のほうである。

公式 Generative AI SDK との違いは機能ではなく経路

比較対象として自然なのは Google の Generative AI SDK である。両者は同じ Gemini を呼ぶが、経路が違う。公式 SDK は API キーを発行してモデルを呼び、課金とレート制限は Google の管理下にあり、返せるものは API が公開している範囲に限られる。Gemini-API はブラウザセッションを再利用するため、API が公開していない Web 側の機能に届く。代わりに、認証情報はアカウントそのものになり、可用性の保証はどこにもなく、壊れたときの修正はコミュニティの対応速度に依存する。どちらが優れているという話ではなく、必要な機能が API の公開範囲の外にあるかどうかで選ぶべきものである。

AGPL-3.0 という条件を先に読む

ライセンスは AGPL-3.0 である。ネットワーク越しに利用者へ機能を提供する形でこのソフトウェアを改変して使う場合、AGPL は通常の GPL よりも広い範囲でソース開示を求める。社内ツールとして閉じて使うのか、外部にサービスとして公開するのかで意味が変わるため、ここは法務の確認なしに進めないほうがよい。私は法律の助言はできないし、この記事でするつもりもない。言えるのは、pip install -U gemini_webapi の一行の裏に、依存関係としてこのライセンスが付いてくるという事実だけである。

どんなチームが手を出し、どんなチームが引くべきか

個人の自動化、研究目的のプロトタイピング、Gemini の Web 画面でしか出せない生成物を手元のパイプラインに流したいケースでは、このライブラリは最短経路になる。Cookie の永続化と自動更新が組み込まれているため、常駐させて使う前提が最初から用意されているのも大きい。一方で、外部に公開する商用サービス、可用性の数値目標があるシステム、Google のサポート窓口を必要とする案件では、経路そのものが適さない。導入を決める前に確かめるべきは3点ある。自分の環境で __Secure-1PSID と __Secure-1PSIDTS を再現可能な手順で取得できるか。GEMINI_COOKIE_PATH に書ける場所を用意できるか。そして、自分が使いたい機能が、いまのアカウントのプランで実際に呼び出しに成功するか。最後の一点は README を読んでも分からない。手元で一度動かして確かめるしかない。

編集部の結論

Gemini の Web アプリでしか使えない機能を Python から自動化したい個人や小規模チームには向く。逆に、Google の公式 SDK で足りる用途、SLA やサポートを必要とする商用サービス、AGPL-3.0 の条件を自社ポリシーで吸収できない組織には勧められない。導入前に確認すべきは、__Secure-1PSID と __Secure-1PSIDTS の取得手順が自分の環境で再現できるか、GEMINI_COOKIE_PATH を書き込み可能なボリュームに割り当てられるか、そして Gemini Gems や拡張機能の呼び出しが自分の Google アカウントのプランで実際に通るかである。

公式情報源

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