【Google AI 実験室 #1】準備編｜Google AI Studio で記事専用プロジェクトを作り、API キーを発行して Gemini を最初に呼ぶまで

はじめに：Gemini を「自分の道具」につなぐ最初の一歩

このサイトでは、Claude Code に MCP サーバーを生やしたり、スタックチャンに Gemini Live で喋らせたりしてきました。そのたびに、AI の手前で アカウント・プロジェクト・キー・SDK という 4 つの層を通っています。ここが曖昧なまま進むと、「動いたけど何に課金されているのか分からない」「キーをどこに置けばいいのか分からない」という状態で先に進むことになります。

「Google AI 実験室」の第 1 回は、その足場を固める 準備編 です。やることは 4 つ。

1. Google AI Studio で、この連載専用の Google Cloud プロジェクトを新しく作り、API キーを発行する（既存のプロジェクトは使わない）
2. 既存の課金アカウントに紐づけて、最初から Tier 1 で始めると決めて、その根拠（規約・料金・レート制限）を一次ドキュメントで押さえる
3. Windows に uv + Python 3.12 + google-genai を入れ、キーを .env に置き、リポジトリにも記事にも書かない仕組みを作る
4. gemini-3.8-flash に最初の 1 発を投げ、モデル一覧・構造化出力・トークン数まで読む

この記事を読み終えると、次のことが分かります。

• Gemini API／AI Studio／Cloud プロジェクト／API キーの関係と、Google AI Pro（¥2,900/月）に入っていても API は別会計であること
• 無料枠に投げた内容は Google の製品改善に使われる規約と、課金プロジェクトなら使われないこと。それでも投げないものの線引き
• レート制限の単位が「キー」ではなく「プロジェクト」であること、だから記事専用にプロジェクトを分ける意味があること
• 2027 年 1 月 1 日に Flash 系の有料単価が上がること

所要時間は、アカウントが既にあれば 30 分〜1 時間。費用は、今回の 3 本のスクリプトの実行分で 約 $0.0043（約 0.7 円） でした。課金アカウントを新しく作る場合は最低 $5 のプリペイが要りますが、今回は既存の課金アカウントに紐づけています。実測トークン数と計算式は 💰 費用の節に載せます。

🧭 Gemini API とは：4 つの層の関係

まず全体像です。読者がブラウザでやることと、Python がやることを 1 枚にすると、こうなります。

上から順に、それぞれが何者かを押さえます。

Gemini API（Gemini Developer API）

Google の生成 AI モデル（Gemini・Gemma・Nano Banana・Veo など）を HTTPS で呼ぶ API です。エンドポイントは generativelanguage.googleapis.com。テキスト生成のほか、画像・PDF・音声・動画の理解、構造化出力（JSON schema）、Function calling、Google 検索グラウンディング、コード実行、音声双方向の Live API などが同じキーで使えます。

2026 年 9 月時点の呼び方は Interactions API です。2026 年 6 月に GA になり、公式は「すべての新規プロジェクトに推奨」としています。従来の generateContent は「legacy だがサポート継続」の扱いで、新機能は Interactions API に先に載ると明記されています。この記事のコードは全部 Interactions API で書きます。

Google AI Studio

ブラウザで同じモデルを試せる 実験場 であり、同時に プロジェクト・API キー・使用量・レート制限・課金を管理する画面 でもあります。AI Studio の利用そのものは無料です（料金ページ末尾に「AI Studio usage is free of charge in all available regions」）。

Playground でプロンプトを試し、右側の Run settings で Thinking level や、Structured outputs・Function calling・Code execution・Grounding（Google Search／Google Maps）・URL context の各ツールを ON/OFF し、Get code で Python や JavaScript のコードを出せます。この「画面で試す → コードに落とす」の往復が、AI Studio の基本的な使い方です。

Google Cloud プロジェクト

API キーは必ず Google Cloud プロジェクトに紐づきます。 プロジェクトは「課金先・共同編集者・権限を管理する箱」で、レート制限もこの箱ごとに数えられます。

初めて AI Studio を使う人には、利用規約に同意した時点でプロジェクトとキーが自動で 1 組作られます。ただし すでに Google Cloud のアカウントを持っている人には自動作成されません。既存プロジェクトを AI Studio に「インポート」するか、AI Studio の「プロジェクト」（Projects）ページから新しく作ります（AI Studio から作れるのは最大 10 個）。今回はこの「新しく作る」ほうを使います。

API キー

キーは「プロジェクトの代理人」です。2026 年 9 月時点で AI Studio が発行するキーはすべて auth キー（authorization key）で、プロジェクト内のサービスアカウントに結びついています。旧来の Standard キーは 2026 年 9 月以降は API に拒否されると告知されているので、今から作るならこの区別を気にする必要はありませんが、古い記事の「無制限キー」の感覚は捨ててください。

漏洩すると、そのプロジェクトの クォータを他人に消費され、課金があれば請求され、ストレージ上のファイルにアクセスされる可能性があります。公式の「Treat your Gemini API key like a password」はそのままの意味です。

無料枠と有料 Tier

料金ページと Rate limits ページから、この記事に関係する範囲を並べます。

一番重要なのは最後から 3 行目です。利用規約の「Unpaid Services」の項には、無料枠に送った内容と生成結果を Google が製品・サービス・機械学習技術の改善に使うこと、人間のレビュアーが読んで注釈をつけることがあること、だから 「機密・個人情報を送るな」 と書いてあります。

一方、同じ規約の「Paid Services」の項には、課金アカウントに紐づいた Cloud プロジェクト経由の利用は Paid Service であり、Google はプロンプトと応答を製品改善に使わない（データ処理は DPA に従う。禁止用途の検出のために一定期間のログは取る）とあります。

無料枠は、料金ページ（2026-09-16 更新）の上では確かに存在します。gemini-3.8-flash の入出力トークンは Free Tier で「Free of charge」です。ただし、この連載では無料枠を使いません。 記事専用プロジェクトは最初から課金アカウントに紐づけて Tier 1 で始めます。理由は 3 つです。

1. 投げた内容が製品改善に使われない。 私的なデータ（自宅センサーの生データ、実運用のタスクボードの中身）を扱う回が来ても、同じプロジェクトのまま進められます
2. Pro 系モデル・Batch API・Google 検索グラウンディングが使える。 無料枠の gemini-3.8-flash は Batch もグラウンディングも「Not available」で、Pro 系はそもそも Free Tier がありません
3. Google AI Pro の Developer Program クレジット（月 $10）が API 側に届く。 次の節で確認するとおり、クレジットは課金を有効にしたプロジェクトでプリペイ残高がある場合にしか効きません。課金にして初めて、Pro の恩恵が API の請求に反映されます

それでも、API キー・パスワード・個人情報は投げません。 「製品改善に使われない」と「何を投げてもよい」は別の話で、Paid でも禁止用途の検出のためにログは残ります。公開できるデータでなくても扱える、というだけです。

Google AI Pro との関係

ここが今回いちばん確認したかったところです。私は Google AI Pro（¥2,900/月） に入っています。「Pro に入っているのだから API も使い放題では」と一度は思いました。答えは No で、公式ページ（Google AI plans・2026-08-18 更新）にはっきり書いてあります。

つまり、AI Pro に入っていても、Python から API キーで呼ぶ分は API 側の Tier で決まり、自分でプリペイした残高から引かれます。逆に言えば、AI Pro に入っていなくても API の使い方と単価は同じです。

Pro に付く Google Developer Program の「毎月 $10 の GenAI & Cloud クレジット」 については、開発者向けページに「Subscribers with GCP projects and Cloud Billing enabled are eligible to receive monthly Cloud credits from the Google Developer Program for Cloud services, including the Gemini API」とあります。Gemini API に使えること自体は書かれていますが、課金を有効にしたプロジェクトが前提で、さらにプリペイのアカウントでは 残高が $0 より大きくないと促進クレジットが有効にならないとも書かれています。今回の記事専用プロジェクトは前払いの課金アカウントに紐づけるので、この条件を満たします。課金にして初めて、Pro の恩恵が API 側に届くわけです。AI Pro の加入者が Developer Program に参加し、クレジットを課金アカウントに適用するまでの手順は次のとおりです（2026-09-17 に実施）。

手順 1：参加する。 Google Developer Program の「プランと料金設定」を開くと、プレミアムのカードに「Google AI Pro で提供」のバッジが付いています。「プロフィールを作成」のダイアログで職種を選び、メール受信の希望にチェックを入れて参加します。支払いの操作はありません。

手順 2：クレジットを課金アカウントに適用する。 特典ページの「月間 $10 相当の生成 AI および Cloud クレジット」のカードで、請求先アカウント（Gemini API のプロジェクトを紐づけた課金アカウント）を選び、「適用」を押します。

手順 3：適用後の表示を確認する。 カードの表示が「月間 ¥1,594 相当」に変わり、「残高: ¥1,594」と、チェック済みの「常にこの請求先アカウントを使用する」が出ます。ボタンは「Google Cloud Billing」（Cloud Console の課金ページへのリンク）に変わります。$10 が ¥1,594 なので、このクレジットの換算レートは ¥159.4/$ です。この記事の円換算はこの値を使います。

AI Studio 側での見え方。 AI Studio の「課金」（Billing）ページでこのクレジットがどう表示され、どう消費されるかは筆者未確認です。適用の順序は、公式が「Eligible Google Cloud credits, if any, are applied first」（プリペイ残高より先にクレジットが消費される）としています。

2027 年 1 月 1 日の単価改定

gemini-3.8-flash の有料単価（100 万トークンあたり・USD）は、料金ページに 2 段で書かれています。

ちょうど 2 倍です。課金プロジェクトで回すこの連載には直接効いてくるので、「円換算」を出すときは、2026 年内に書いた記事の値が 2027 年に変わることを毎回注記します。

🗂️ なぜ記事専用のプロジェクトを作るか

手元には、自作のアナリティクスが使っている Google Cloud プロジェクトが既にあります。課金を有効にしていて、Pro 系モデルを呼んでいます。「そのキーを流用すれば今日すぐ書ける」のは事実です。それでもプロジェクトは新しく作り、課金アカウントは既存のものに紐づけます。理由は 3 つで、「何がプロジェクト単位で、何が課金アカウント単位か」から来ています。

1. 漏洩時の影響範囲を切る。 記事にはコードを載せ、スクショを貼り、リポジトリを公開します。キーを書かない仕組みは作りますが、事故は「起きない前提」ではなく「起きても被害が閉じる前提」で組みます。記事用プロジェクトのキーが漏れても、そのキーで触れるのは記事用プロジェクトだけで、無効化してもアナリティクス側のキーは影響を受けません。金額の上限は Tier 1 の月 $250 と、課金アカウントの前払い残高です。ただし Prepay は残高が $0 になった時点で、その課金アカウントに紐づく 全プロジェクトの全キーが同時に止まる（公式）ので、記事用のキーが漏れて残高を使い切られると既存プロジェクトも止まります。ここが課金アカウントを共有する代償で、自動リロードを設定しないことと、AI Studio の「利用額」（Spend）ページにある プロジェクト別の月間支出上限（Monthly spend cap） で抑えられます（公式の手段）
2. 課金アカウントは共有し、プロジェクトで数える。 Tier・レート制限の枠・月の支出上限は 課金アカウント単位で決まります（公式: “Tiers, rate limits, and billing account caps are all determined at the billing account level”）。記事用プロジェクトを既存の課金アカウントに紐づけたので、Tier 1 の枠と月 $250 の上限、前払い残高は既存プロジェクトと共有です。それでも課金アカウントを分けなかったのは、レート制限の カウントはプロジェクトごとで、月の支出上限もプロジェクト別に設定でき、Developer Program のクレジットの適用先も課金アカウント単位だからです。連載のためにプリペイの最低額 $5 をもう 1 口積む理由がありませんでした
3. 実費をプロジェクト別に読める。 記事用プロジェクトの支出は、この連載の実験の分だけです。AI Studio の「利用額」（Spend）ページはプロジェクト別に支出を出すので、課金アカウントを共有していても、他の用途の分を引き算せずに「この回の費用」として書けます。この記事では、それに加えて usage のトークン数と公式単価から自算した額も載せます

副産物として、規約上の「Paid Service」の範囲もプロジェクトの境界と一致します。記事用プロジェクトを通る限り製品改善には使われない、という状態が、キーの使い分けだけで守れます。

🧰 準備 1：AI Studio でプロジェクトとキーを作る

ここからは実際の手順です。ブラウザで Google AI Studio を開き、Google アカウントでログインした状態から始めます。

手順 1：「プロジェクト」（Projects）で新しいプロジェクトを作る

左のナビゲーション（日本語 UI では API キー／プロジェクト／使用量／レート制限／利用額／課金／ログとデータセット の順）から プロジェクト（Projects）を開きます。既存の Google Cloud プロジェクトを持っている場合、ここには「インポート」したものしか並びません（公式: “By default, Google AI Studio does not display all of your Google Cloud projects”）。既存のものはインポートせず、新規作成します。名前は後から変えられるので、google-ai-lab のような分かりやすいものにします。

作成直後は、プロジェクトの請求階層（Billing Tier）が 無料枠（Free） になっているはずです（または「Set up billing」のボタンが出ます）。手順 3 でここを Tier 1 に変えます。

手順 2：「API キー」（API keys）で、そのプロジェクトのキーを発行する

API キー（API keys）ページからキーの作成に進むと、「新しいキーを作成する」ダイアログが開きます。「キー名の設定」は既定の Gemini API Key のままでよく、「インポートしたプロジェクトを選択」は既定で Gemini Project になっているので、ここを 手順 1 で作ったプロジェクト（google-ai-lab）に切り替えてから「キーを作成」を押します。2026 年 9 月時点では、ここで作られるキーは自動的に auth キーです。

作成後の API キー一覧には、キー（末尾 4 文字だけの省略表示）・プロジェクト・作成日時・請求階層の 4 列が並びます。

表示されたキーは この画面でしかコピーできない扱いとして、次の節で作る .env に直接貼ります。メモ帳やチャットに一時保存しないでください。スクショも、キーが表示された状態では撮りません。

手順 3：課金アカウントに紐づけて Tier 1 にする

プロジェクトの一覧（または API キーの一覧）の Set up billing を押します。流れは公式の Billing ページのとおりです。

1. Cloud Billing アカウントを選ぶ。 初めてなら国を選んで規約に同意し、連絡先と支払い方法を入れます。すでに課金アカウントがある場合は一覧から選ぶ画面になり、使いたくなければ Add new billing account で新しく作れます。今回は 既存の課金アカウント（前払い）を選びました。新しい課金アカウントは作っていません
2. （新規の課金アカウントなら）$5 以上をプリペイする。 新規ユーザーは Prepay プランが既定で、最低 $5・最大 $5,000 をクレジットとして先に買います。買ったクレジットは 12 か月で失効し、原則返金されません。既存の前払いアカウントを選んだ場合は、その残高がそのまま使われます
3. 一覧に戻り、請求階層（Billing Tier）が Tier 1・前払いに変わったことを確認します。Free → Tier 1 は通常即時です。手順 2 に載せた API キー一覧の図が、この状態です

Tier 1 には 月の支出上限 $250 があります（課金アカウント単位。紐づく全プロジェクトの合計）。上限に達するとその月は止まり、翌月 1 日に再開します。加えて Prepay は 残高が $0 になった時点で、その課金アカウントに紐づく全プロジェクトの全キーが止まるので、自動リロード（auto-reload）を設定しない限り、使える額は「前払いした分」で頭打ちです。この二重の上限が、記事用プロジェクトの「被害の上限」でもあります。既存の課金アカウントを共有しているので、この上限は既存プロジェクトと共通です。

最後に、Google AI Pro の Developer Program クレジットをこの課金アカウントに届かせます。手順は前の節（🧭 Google AI Pro との関係）の 3 枚の図のとおりで、条件（課金有効・プリペイ残高 > $0）はこの時点で満たしています。

手順 4：「レート制限」（Rate limits）で「自分の枠」を読む

レート制限（Rate limits）ページを開き、Project で google-ai-lab を選ぶと、画面名「Gemini API のレート制限」の横に Tier 1 のバッジが付き、モデルごとの RPM／TPM／RPD が「過去 28 日間の最大使用量 / 上限」の形で出ます。この上限の数値は公開ドキュメントには載っていません。 自分のプロジェクトの画面が唯一の一次情報なので、ここで読んで控えます。手順 3 の後に読んでいるので、表の値は Tier 1 のものです。

読んだ日は 2026-09-19（Tier 1）です。同じ画面の使用量側は gemini-3.8-flash が RPM 6・TPM 328・RPD 6 で、この記事の実行分がそのまま載っています。この表の値は、あなたのプロジェクトでは違う可能性があります。Tier とアカウントの状態で自動的に変わる、と公式が明記しています。課金を有効にする前（無料枠）の値は控えていません。

🔐 準備 2：キーの置き場所を先に決める

コードを書く前に、キーがどこを通ってモデルに届くかを決めておきます。キーが「ファイルとして存在する場所」を .env 1 か所だけにします。

google-genai の genai.Client() は、引数を渡さなければ環境変数 GEMINI_API_KEY（または GOOGLE_API_KEY）を自動で読みます。両方あると GOOGLE_API_KEY が優先されます。だから、コード側には api_key= を一切書かず、環境変数に載せる役だけを python-dotenv に任せます。

キーを 書いてよい場所と書いてはいけない場所 を表にします。

具体策は 3 つです。

1. .gitignore に .env を最初のコミットより前に書く。 後から足しても、一度コミットした履歴からは消えません
2. .env.example を用意して、値の入っていないひな形だけをコミットする。 読者はこれをコピーして .env を作ります
3. genai.Client() に引数を渡さない。 AI Studio の Get code が出すコードには api_key="..." の形が混ざることがあるので、貼るときに消します

🐍 準備 3：Windows に uv + Python 3.12 + google-genai

Python 環境は uv で作ります。pip と venv を別々に扱わなくてよく、Python 本体のインストールまで面倒を見てくれるからです。

# uv が無ければ（uv 公式のインストール手順）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version

この記事のコードは GitHub の google-ai-lab に置いてあります。クローンして uv sync するだけで、Python 3.12 と依存パッケージが .venv に入ります。

git clone https://github.com/ramtuc/google-ai-lab.git
cd google-ai-lab
uv sync

リポジトリの構成はこれだけです。

google-ai-lab/
├── .gitignore            # .env / *.key / __pycache__ を除外
├── .python-version       # 3.12
├── pyproject.toml        # google-genai と python-dotenv
├── README.md
└── 01-setup/
    ├── .env.example      # これを .env にコピーしてキーを入れる
    ├── list_models.py    # このキーで呼べるモデル一覧
    ├── first_call.py     # gemini-3.8-flash に最初の 1 発
    └── structured_output.py  # 構造化出力（JSON schema）の最小例

pyproject.toml の中身です。バージョンは PyPI で 2026-09-16 時点の最新（google-genai 2.23.0 は 2026-09-10 公開、python-dotenv 1.2.3 は 2026-08-16 公開）を下限にしています。Interactions API を使うには google-genai 2.3.0 以上が必要、と公式にあります。

[project]
name = "google-ai-lab"
version = "0.1.0"
description = "Google AI 実験室 — Gemini / Google AI を毎回1つ、手を動かして確かめる連載のコード置き場"
readme = "README.md"
license = "MIT"
requires-python = ">=3.12"
dependencies = [
    "google-genai>=2.23.0,<3",
    "python-dotenv>=1.2.3,<2",
]

[tool.uv]
package = false

次に .env を作ります。.env.example をコピーして、YOUR_API_KEY の部分を手順 2 で発行したキーに置き換えます。

Copy-Item 01-setup\.env.example 01-setup\.env
notepad 01-setup\.env

.env.example の中身はこうです。モデル名も環境変数に追い出してあるので、世代交代したときは .env を 1 行変えれば済みます。

# このファイルを同じフォルダに .env という名前でコピーし、値を埋める
# .env は .gitignore 済み。キーは記事・スクショ・リポジトリに絶対に書かない

# Google AI Studio の「API keys」ページで発行したキー
GEMINI_API_KEY=YOUR_API_KEY

# 呼ぶモデル。世代交代したらここだけ変える（省略時は gemini-3.8-flash）
GEMINI_MODEL=gemini-3.8-flash

🔬 使い方 1：AI Studio の画面で試す

コードに入る前に、AI Studio の Playground で 1 往復しておくと、SDK の引数が「画面のどのつまみか」で理解できます。

• Playground: 左の Playground を開くと「Explore Google models」（Featured・Code and Chat・Image Generation・Video Generation・Speech and Music・Real-time）の画面になります。右の Run settings のモデル欄で gemini-3.8-flash（Gemini 3.8 Flash）を選び、下の入力欄に質問を打って Run（Ctrl+Enter）を押すだけです
• Run settings（右側のパネル）: モデルのカード、System instructions（役割の指示）、Thinking level（既定は Medium）、Tools の Structured outputs・Code execution・Function calling・Grounding with Google Search・Grounding with Google Maps・URL context のトグル、Advanced settings がここにあります。後で Python から response_format や tools として渡すものと同じです
• Text preview（画面下）: 今のプロンプトが何トークンか、モデルの上限が何トークンかを表示します。課金の感覚をつかむのに便利です
• Get code（Run settings パネルの上）: 画面で試した状態を Python／JavaScript などのコードとして書き出します。2026-09-19 時点の Python 出力は client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY")) と 環境変数から読む形で、キーの直書きではありません。genai.Client() は引数なしでも同じ環境変数を読むので、この記事のコードはそちらに揃えています。モデル名は models/gemini-3.8-flash と models/ 接頭辞付きで、generation_config に thinking_level: 'medium' と max_output_tokens: 65536 が入った状態で出てきます

なお、Google AI Pro の恩恵が出るのは この画面の中だけです。Playground の日次クォータが Free より高く、Pro 系や Nano Banana を画面で試せます。ここで試したことを Python に持っていった瞬間、課金の世界は API 側（課金アカウントの前払い残高）に切り替わります。

🔬 使い方 2：Python から呼ぶ

ここからが本題です。3 本のスクリプトを順に回します。すべて uv run で実行するので、仮想環境の activate は要りません。

(1) models.list()：このキーで呼べるモデルを一覧する

最初に投げるのは生成ではなく 一覧 です。「一覧に載っているモデル」と「今のプロジェクトで実際に呼べるモデル」は同じとは限らないので、自分のキーで何が返るかを先に見ます。

"""この API キーで呼べるモデルを一覧する（Google AI 実験室 #1）"""

from dotenv import load_dotenv
from google import genai

load_dotenv()  # 同じフォルダ（または上位）の .env から GEMINI_API_KEY を読む

client = genai.Client()  # 環境変数 GEMINI_API_KEY を自動で拾う。引数にキーを書かない

print(f"{'model':<44} {'in_limit':>9} {'out_limit':>9}  actions")
for m in client.models.list():
    name = (m.name or "").removeprefix("models/")
    actions = ",".join(m.supported_actions or [])
    print(f"{name:<44} {m.input_token_limit or 0:>9} {m.output_token_limit or 0:>9}  {actions}")

uv run 01-setup/list_models.py

出力は次のような表になります（列は、モデル ID・入力トークン上限・出力トークン上限・対応する操作）。2026-09-19 の実出力は見出し 1 行＋ 58 モデルで、その一部を抜粋します。

model                                         in_limit out_limit  actions
gemini-2.5-flash                               1048576     65536  generateContent,countTokens,createCachedContent,batchGenerateContent
gemini-2.5-pro                                 1048576     65536  generateContent,countTokens,createCachedContent,batchGenerateContent
gemma-4-31b-it                                  262144     32768  generateContent,countTokens
gemini-3.1-pro-preview                         1048576     65536  generateContent,countTokens,createCachedContent,batchGenerateContent
gemini-3.1-flash-image                           65536     65536  generateContent,countTokens,batchGenerateContent
gemini-3.5-flash                               1048576     65536  generateContent,countTokens,createCachedContent,batchGenerateContent
gemini-3.5-flash-lite                          1048576     65536  generateContent,countTokens,createCachedContent,batchGenerateContent
gemini-3.7-flash                               1048576     65536  generateContent,countTokens,createCachedContent,batchGenerateContent
gemini-3.8-flash                               1048576     65536  generateContent,countTokens,createCachedContent,batchGenerateContent
lyria-3.5                                      1048576     65536  generateContent,countTokens
antigravity-preview-09-2026                    1048576     65536  generateContent,countTokens
gemini-embedding-2                                8192         1  embedContent,countTextTokens,countTokens,asyncBatchEmbedContent
veo-3.1-generate-preview                           480      8192  predictLongRunning
gemini-3.8-live                                 131072     65536  bidiGenerateContent
gemini-3.8-live-extended-thinking               131072     65536  bidiGenerateContent
（…全 58 行）

一覧を眺めて分かることを並べます。

• gemini-3.8-flash は入力上限 1,048,576（1M）・出力上限 65,536 トークン。actions は generateContent・countTokens・createCachedContent・batchGenerateContent の 4 つで、interactions という名前は出てきません。この一覧は generateContent 系の操作名で書かれていて、次の first_call.py では同じモデルを Interactions API で呼べます
• 名前に pro を含む行が 10（gemini-2.5-pro・gemini-3.1-pro-preview・gemini-3-pro-image・nano-banana-pro-preview など）。Tier 1 なので Pro 系も呼べる状態ですが、この記事では使いません。テキストの Pro 系で安定版なのは gemini-2.5-pro で、3 世代は gemini-3.1-pro-preview のまま。Flash 系は gemini-3.5〜3.8 まで安定版が並びます
• 2.5 世代（gemini-2.5-flash・gemini-2.5-pro・gemini-2.5-flash-lite など）もまだ載っています。古い記事のコードが今も動く理由です
• Gemma が 2 行（gemma-4-26b-a4b-it・gemma-4-31b-it）、名前に image を含む画像系が 6 行、Veo が 3 行、Lyria（音楽）が 4 行、埋め込みが 3 行。テキスト生成だけでなく、同じキーで画像・動画・音楽・埋め込みまで呼べる一覧になっています
• 末尾の bidiGenerateContent の 9 行（gemini-3.8-live など）は Live API 用で、generateContent では呼べません

(2) first_call.py：gemini-3.8-flash に最初の 1 発

"""gemini-3.8-flash に最初の 1 発を投げ、返答とトークン数を表示する（Google AI 実験室 #1）"""

import os

from dotenv import load_dotenv
from google import genai

load_dotenv()
MODEL = os.environ.get("GEMINI_MODEL", "gemini-3.8-flash")  # モデル名は設定値に追い出す

client = genai.Client()
interaction = client.interactions.create(
    model=MODEL,
    input="NE555 タイマー IC を、電子工作を始めたばかりの人に 3 行で説明してください。",
    store=False,  # サーバ側に会話を残さない（続きの会話をしないので不要）
)

print(interaction.output_text)
print("---")
u = interaction.usage
print(f"model  : {MODEL}")
print(f"input  : {u.total_input_tokens or 0} tokens")
print(f"thought: {u.total_thought_tokens or 0} tokens")
print(f"output : {u.total_output_tokens or 0} tokens")
print(f"total  : {u.total_tokens or 0} tokens")

uv run 01-setup/first_call.py

一定のリズムで電気を「オン・オフ」繰り返したり、時間を測ったりできる超定番の部品です。
プログラミング不要で、抵抗やコンデンサをつなぐだけでLEDの点滅やブザーの音を作れます。
安くて壊れにくく扱いやすいため、電子工作で「時間やリズムを操る基本」を学ぶのに最適です。
---
model  : gemini-3.8-flash
input  : 24 tokens
thought: 628 tokens
output : 81 tokens
total  : 733 tokens

返答は 3 行で 81 トークン。その手前で 628 トークンの思考が走っています。出力単価は思考トークン込みなので、この 1 発の費用の 9 割近くは画面に出ない思考の分です。なお、9/17 に無料枠のまま同じスクリプトを初めて流したときは、API リクエスト 5 件のうち 1 件が 500 InternalServerError で落ち、再実行でそのまま通りました（💰 費用の節の使用量グラフに残っています）。

コードの要点は 3 つです。

• client.interactions.create(model=..., input=...) が Interactions API の基本形です。generateContent 時代の client.models.generate_content(model=..., contents=...) に相当します。返り値は Interaction で、最終テキストは interaction.output_text、途中経過は interaction.steps に入ります
• store=False は「このやりとりをサーバー側に保存しない」指定です。既定では保存され（Free Tier は 1 日、Paid Tier は 55 日）、previous_interaction_id で続きの会話ができます。今回は 1 発で終わるので切っています。ただし store=False と、規約上のデータ利用は別の話です。製品改善に使われないのは Paid Service（課金プロジェクト）だからであって、この設定のおかげではありません
• interaction.usage にトークン数が入ります。total_input_tokens・total_output_tokens・total_thought_tokens（思考トークン）・total_tokens。generateContent 時代の usage_metadata.prompt_token_count などに相当する場所です。出力単価は思考トークン込みなので、費用を見積もるときは thought を忘れないでください

(3) structured_output.py：JSON schema で「型のある答え」を返させる

この連載で毎回使う道具です。次回のデータシート QA では「値・単位・根拠ページ」を JSON で返させますが、今回はその最小形として、架空のセンサーの仕様文から諸元を抜き出す例にします。投げるのはダミーの文章だけです。

"""構造化出力（JSON schema）の最小例：仕様文からセンサーの諸元を JSON で抜き出す（Google AI 実験室 #1）"""

import os

from dotenv import load_dotenv
from google import genai
from pydantic import BaseModel, Field

load_dotenv()
MODEL = os.environ.get("GEMINI_MODEL", "gemini-3.8-flash")

# 架空のセンサーの仕様文。公開してよいダミーデータだけを API に投げる（キー・個人情報は投げない）
SPEC_TEXT = """
温湿度センサーモジュール ELW-TH01
・電源電圧: 2.7V〜3.6V
・インターフェース: I2C（アドレス 0x44、最大 400kHz）
・測定範囲: 温度 -40〜+125℃、湿度 0〜100%RH
・精度: 温度 ±0.2℃、湿度 ±2%RH
・消費電流: 測定時 600µA、スリープ時 0.2µA
"""


class VoltageRange(BaseModel):
    min_v: float = Field(description="最小電源電圧 [V]")
    max_v: float = Field(description="最大電源電圧 [V]")


class SensorSpec(BaseModel):
    part_number: str = Field(description="型番")
    interface: str = Field(description="通信インターフェース名（I2C / SPI / UART など）")
    i2c_address: str | None = Field(description="I2C アドレス（0x 付き 16 進表記）。I2C でなければ null")
    supply_voltage: VoltageRange
    temperature_range_c: list[float] = Field(description="[最小, 最大] の温度測定範囲 [℃]")
    sleep_current_ua: float | None = Field(description="スリープ時消費電流 [µA]")


client = genai.Client()
interaction = client.interactions.create(
    model=MODEL,
    input="次の仕様文から諸元を抜き出してください。\n" + SPEC_TEXT,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": SensorSpec.model_json_schema(),  # Pydantic → JSON Schema
    },
    store=False,
)

print(interaction.output_text)  # モデルが返した生の JSON 文字列
spec = SensorSpec.model_validate_json(interaction.output_text)  # スキーマどおりか検証して型付きに
print("---")
print(f"{spec.part_number}: {spec.interface} @ {spec.i2c_address}, "
      f"{spec.supply_voltage.min_v}-{spec.supply_voltage.max_v} V")
u = interaction.usage
print(f"tokens: in={u.total_input_tokens or 0} out={u.total_output_tokens or 0} total={u.total_tokens or 0}")

uv run 01-setup/structured_output.py

{
  "part_number": "ELW-TH01",
  "interface": "I2C",
  "i2c_address": "0x44",
  "supply_voltage": {
    "min_v": 2.7,
    "max_v": 3.6
  },
  "temperature_range_c": [-40, 125],
  "sleep_current_ua": 0.2
}
---
ELW-TH01: I2C @ 0x44, 2.7-3.6 V
tokens: in=130 out=108 total=544

6 つのフィールドがすべてスキーマどおりで、i2c_address は 0x 付き、temperature_range_c は [最小, 最大] の順、sleep_current_ua は 0.2 と、仕様文の値がそのまま入っています。トークン数が in=130 out=108 なのに total=544 なのは、差の 306 トークンが思考トークンだからです（このスクリプトは thought を表示していません）。

ポイントは、スキーマを Pydantic のクラスで書き、model_json_schema() で JSON Schema にして response_format に渡すところです。返ってきた output_text はスキーマに沿った JSON 文字列なので、同じクラスの model_validate_json() で型付きオブジェクトに戻せます。str | None のような「無いかもしれない値」も、公式の例と同じく Optional として渡せます。

公式ドキュメントが「出力は構文的には正しい JSON だが、値の妥当性は必ずアプリ側で検証せよ」と念を押しているのは、この連載にとって本題そのものです。次回はここに「データシートの原文」と「実測値」を突き合わせる採点を足します。

💰 費用：実測トークン数と、実費の確認方法

今回 3 本のスクリプトで消費したトークン数です（2026-09-19・Tier 1 での実行分）。

※ structured_output.py は thought を表示していないので、合計 − 入力 − 出力（544 − 130 − 108）で求めた値です。

単価は料金ページ（Last updated 2026-09-16・2026-09-19 に再確認）の gemini-3.8-flash Paid Tier で、入力 $0.75、出力 $3.75／100 万トークン。出力の行には 「Output price (including thinking tokens)」 と明記されていて、思考トークンは出力単価で課金されます。これで自算します。

円換算は、前の節の Developer Program の表示（$10 ＝ ¥1,594、つまり ¥159.4/$）を使うと 約 0.69 円です。2027 年 1 月からは単価が 2 倍なので、同じ実行が約 $0.0087（約 1.4 円）になります。models.list() は生成を伴わないので、トークン課金はありません。

実費の確認先は 3 つです。

1. AI Studio の「使用量」（Usage）: プロジェクトを選ぶと、API リクエスト数・エラー数と、モデルごとの入出力トークン数・リクエスト数が日別に出ます。今回の実行分（9/19）と、初回に無料枠のまま流した 9/17 の分が並んでいます
2. AI Studio の「課金」（Billing）と「利用額」（Spend）: 課金アカウントの残高と、プロジェクトごとの月の支出。反映まで最大 24 時間程度かかることがあります。今回の約 0.7 円がこれらのページでどう見えるかは筆者未確認です
3. Google Cloud Console の Cloud Billing レポート: サービス「Gemini API」で絞ると SKU 単位の内訳が見えます。こちらは 1 日以上遅れることがあります

Google AI Pro 加入者として API 側で得られるのは、Developer Program の月 $10（¥1,594）クレジットです。課金アカウントに前払い残高がある、という今回の構成がその条件で、公式はプリペイ残高より先にクレジットが消費されるとしています。理屈の上では今回の約 0.7 円はこのクレジットから引かれ、前払い残高は減らないはずですが、AI Studio の課金ページでの見え方と残高の推移は筆者未確認です。Pro のそれ以外の恩恵（Playground・Build の日次クォータ、Pro 系モデルを画面で試せること）は AI Studio の画面内に限られ、API キー経由の呼び出しには効きません。

💭 所感：「電源を分ける」のと同じ感覚だった

⚠️ できないこと・確認していないこと

• レート制限の数値は、この記事の表に載せた自分のプロジェクトの値だけです。公開ドキュメントには載っておらず、Tier とアカウント状態で自動的に変わります。読者の環境で同じ値である保証はありません
• Developer Program の $10 クレジットが実際に API の請求に充当される様子は確認していません。課金アカウントへの適用まで（🧭 の節の 3 枚）は実施しましたが、AI Studio の課金ページでの表示と残高の推移は筆者未確認です。適用条件（課金有効・プリペイ残高 > 0・クレジットが先に消費される）は公式ページの記述に基づきます
• 無料枠での動作は、初回（9/17）に一度流しただけです。3 本とも同じコードで動きました（そのときの 1 件の 500 は再実行で解消）が、本文の数値は Tier 1 化後の 9/19 のものです。無料枠のレート制限の値は控えていません。規約上のデータの扱いは無料枠と課金で違います
• 課金アカウントは既存プロジェクトと共有しています。Tier 1 の枠（RPM/TPM/RPD）・月 $250 の上限・前払い残高は既存プロジェクトと共通で、記事用プロジェクト単独の月間支出上限（「利用額」ページ）はこの記事では扱っていません
• store=False の効果は「サーバー側に Interaction を残さない」ことだけです。製品改善に使われないのは Paid Service（課金プロジェクト）だからで、無料枠でこの設定を付けても規約上の扱いは変わりません
• generateContent との互換: Interactions API には Batch API・Python の自動 Function calling・明示的キャッシュ・カスタム safety settings が まだ無いと公式にあります。これらが必要なら legacy 側を使うことになりますが、この記事では試していません
• macOS／Linux では動かしていません。SDK 側に OS 依存は無いはずですが、コマンドは PowerShell のものです
• Windows のユーザー環境変数にキーを置く方法は公式に載っていますが、複数プロジェクトを使い分けにくいので今回は .env に統一しました。どちらが正解というものではありません
• Standard キーの拒否時期は公式ページに「September 2026」とあるだけで、日付までは書かれていません
• 利用規約には、AI Studio と Gemini API は「開発者がプロフェッショナル／ビジネス目的で Google の AI モデルを使って構築するためのもので、消費者向け利用ではない」ともあります。この連載は開発者としての利用にあたると考えていますが、規約の解釈はしていません

✅ まとめ

• Gemini API は アカウント → AI Studio → Cloud プロジェクト → API キー → SDK → モデル の順につながる。キーは必ずプロジェクトに紐づき、レート制限も課金もプロジェクト（と課金アカウント）の単位
• Google AI Pro と Gemini API の課金は別物。Pro の恩恵は AI Studio の画面内だけで、API キー経由の呼び出しには効かない。例外は Developer Program の月 $10 クレジットで、課金プロジェクト＋プリペイ残高がある場合にだけ API 側に届く
• 無料枠は「投げた内容が製品改善に使われる」。この連載は最初から課金アカウントに紐づけて Tier 1 で始め、Paid Service として扱う。それでもキー・パスワード・個人情報は投げない
• 記事専用プロジェクトを新規作成し、課金アカウントは既存のものに紐づけた。Tier・月上限・残高は課金アカウント単位で共有、レート制限のカウントと利用額の表示はプロジェクト別
• キーは .env 1 か所。.gitignore を先に書き、.env.example だけコミットし、genai.Client() に引数を渡さない
• 呼び方は Interactions API（client.interactions.create）。output_text で答え、usage でトークン数（思考トークン込み）
• 構造化出力は Pydantic → model_json_schema() → response_format、戻りは model_validate_json() で型付きに
• 今回の実費は 1,277 トークンで 約 $0.0043（約 0.7 円・¥159.4/$）。思考トークン（934）が出力単価で課金され、費用の大半を占める。確認先は AI Studio の使用量・課金・利用額。2027-01-01 から Flash 系の有料単価は 2 倍

よくある質問（FAQ）

Q: Google AI Pro に入っていれば、Gemini API も無料で使い放題になりますか？

A: なりません。公式の「Google AI plans」ページに、プランの恩恵は AI Studio の Web 画面内に限られ、API キーを使った直接の呼び出しは別に課金・管理されると明記されています。API は API 側の Tier（無料枠、または Cloud Billing を紐づけてプリペイした分）で使います。Pro に入っていると Developer Program 経由の月 $10 クレジットが課金プロジェクトに充当されますが、それも API 側の請求に対する話です。

Q: 無料枠で始めてはいけないのですか？

A: 始められます。gemini-3.8-flash は Free Tier で入出力トークンが無料です。ただし規約上、無料枠（Unpaid Services）に送った内容と生成結果は Google の製品改善に使われ、人間のレビュアーが読むことがあります。公式は「機密・個人情報を送らないこと」としています。この連載は私的なデータを扱う回が来ることが分かっているので、最初から課金プロジェクト（Paid Service）で始めました。store=False は規約上の扱いを変えません。

Q: API キーを GitHub に push してしまいました。どうすればいいですか？

A: 公式のチェックリストどおり、AI Studio で新しいキーを作る → アプリ側を新しいキーに差し替える → 古いキーを無効化する → Usage と Cloud Console で不正利用の形跡を確認する、の順です。古いキーは新しいキーが動くのを確認してから無効化します。今回の記事用プロジェクトは前払いの課金アカウントに紐づいているので、被害の上限はその残高と Tier 1 の月上限 $250 です。自動リロードを設定していなければ、残高が尽きた時点で止まります（同じ課金アカウントの既存プロジェクトも一緒に止まります）。

Q: ネットの記事の client.models.generate_content(...) と書き方が違うのはなぜですか？

A: 2026 年 6 月に Interactions API が GA になり、公式が新規プロジェクトに推奨する呼び方が client.interactions.create(...) に変わったためです。generateContent は legacy 扱いでサポートは続いていますが、新機能は Interactions API に先に載ります。google-genai 2.3.0 以上で両方使えます。

Q: 記事用に課金アカウントも分けたほうがよいですか？

A: 分けなくても、レート制限のカウントと「利用額」ページの支出はプロジェクト別なので、記事の実費は読めます。分けると Tier・月の支出上限・前払い残高を既存プロジェクトから独立にできる代わりに、新しい課金アカウントに最低 $5 のプリペイが要ります。この記事は既存の課金アカウントに紐づけ、プロジェクト単独の上限は「利用額」ページの月間支出上限で付けられる、という整理にしました。

Q: Pro 系のモデル（gemini-3.1-pro-preview）は無料枠で呼べますか？

A: 呼べません。料金ページで Pro 系は Free Tier が「Not available」です。2026 年 9 月時点で Pro 系は preview のみで安定版が無く、課金プロジェクトが前提です。今回作った Tier 1 のプロジェクトなら呼べますが、この記事では Flash 系（gemini-3.8-flash）だけを使っています。

関連記事

• 【連載】Google AI 実験室 ― Gemini・Gemma・Google Labs を一つずつ、手を動かして確かめる：この連載のハブ。収録記事と「次に試すもの」の基準
• Claude Code で使える MCP ツールの作り方｜Python で自作サーバを1本通す：Python + uv で AI の道具を作る、という同じ型の入門
• 自作 Web アプリに MCP を生やして Claude Code から書き込む｜状態を持つ MCP サーバーの作り方：author を環境変数で固定する話は、今回の「キーを環境変数に追い出す」と同じ発想
• スタックチャンに『毎日1つ課題を出す関西弁の師匠』を宿らせた｜Gemini Live習慣コーチ：Gemini API を実機（ESP32）から直接呼んだ記録。今回作った環境の「先」にあるもの

参考

一次ドキュメントの取得日は 2026-09-16（料金・課金・レート制限の 3 ページは 2026-09-19 に再確認）です。

• Using Gemini API keys（ai.google.dev）：キーとプロジェクトの関係・auth キー・環境変数・漏洩時の手順・AI Studio から作れるプロジェクト数（Last updated 2026-09-02）
• Rate limits（ai.google.dev）：RPM/TPM/RPD・プロジェクト単位・Tier の条件（Last updated 2026-09-02）
• Billing（ai.google.dev）：Tier の条件・$5 プリペイ・既存の課金アカウントを選ぶ流れ・Prepay の失効と残高 $0 の挙動（紐づく全プロジェクトの全キーが止まる）・Tier／レート制限／上限が課金アカウント単位であること・プロジェクト別の月間支出上限・Usage／Billing／Spend の見方・無料枠に戻す方法・$300 クレジットの扱い（Last updated 2026-09-03）
• Gemini Developer API pricing（ai.google.dev）：gemini-3.8-flash の単価と 2027-01-01 改定・「Output price (including thinking tokens)」の明記・「Used to improve our products」の Yes/No（Last updated 2026-09-16）
• Gemini API Additional Terms of Service（ai.google.dev）：Unpaid Services のデータ利用・18 歳以上（Effective 2026-03-23）
• Google AI plans（ai.google.dev）：AI Pro/Ultra と AI Studio・API 課金の関係・Developer Program クレジットの条件（Last updated 2026-08-18）
• Google Developer Program plans and pricing（developers.google.com）：AI Pro に付く「$10 GenAI and Cloud monthly credit」・参加画面（2026-09-17 に操作）
• Google Developer Program: 特典（me.developers.google.com）：月 $10 クレジットを請求先アカウントに適用する画面（2026-09-17 に操作。$10 ＝ ¥1,594 の表示はここ）
• Interactions API（ai.google.dev）：GA・store・保存期間・SDK 2.3.0 以上・未対応機能（Last updated 2026-09-04）
• Getting started（ai.google.dev）：最初の呼び出し・構造化出力の公式コード（Last updated 2026-09-04）
• Structured outputs（ai.google.dev）：対応する JSON Schema のサブセット（Last updated 2026-09-02）
• Google AI Studio quickstart（ai.google.dev）：Run settings・Get code（Last updated 2026-07-30）
• Troubleshoot Google AI Studio（ai.google.dev）：Text preview・ダッシュボードの権限（Last updated 2026-09-09）
• Gemini API libraries（ai.google.dev）：google-genai が正、旧 google-generativeai は非推奨（Last updated 2026-06-22）
• Available regions（ai.google.dev）：Japan を含む提供地域（Last updated 2026-04-28）
• google-genai（PyPI）：2.23.0（2026-09-10）／ python-genai（GitHub）：Interaction.usage のフィールド名
• python-dotenv（PyPI）：1.2.3（2026-08-16）
• uv: Installation（docs.astral.sh）：Windows のインストールコマンド
• google-ai-lab（GitHub）：この記事のコード全文