Gemini APIキーの生死確認｜複数キーを安全に調べる方法

Gemini APIキーの生死確認とは、手元のキーが今も使えるのか、止まっているのかを1本ずつ確かめる作業です。

複数のGemini APIキーを画面に出さずにまとめて確かめるPythonコードと、結果を残す管理表の作り方を紹介します。コードのうち、伏せ字・判定・書き出しはダミーの値で Windows 11 と Python 3.12 で動くことを確かめています。Googleに実際に問い合わせる部分は、APIキーが手元にないため動かしていません。公式ドキュメントの内容は2026年10月時点のものです。

Gemini APIキーが止まる理由と画面での見方

キーが使えなくなる理由は1つではなく、理由によって直す場所が変わります。主な理由と、画面で分かる範囲を先に押さえます。

• キーが止まる主な理由
• AI Studioの画面で見えること

キーが止まる主な理由

公式ドキュメントに書かれている理由は、次の5つです。

• 制限なしの標準キー：制限が付いていない標準キーからのリクエストは、Gemini APIが拒否します。
• 長く使われていないキー：2026年5月7日から、長期間使われていない制限なしキーはブロックされます（AI Studioでは「Blocked」）。
• 漏えいが分かったキー：Googleがブロックします。エラーは「Your API key was reported as leaked. Please use another API key.」です。
• Prepay（前払い）の残高ゼロ：請求アカウントにつながる全キーが同時に止まり、HTTP 402で失敗します。
• 上限（レート制限）への到達：キーは生きていても一時的に断られます。上限はキーごとではなく、プロジェクトごとに数えられます。

上の3つはキーそのものの問題で、制限を付けるか、新しいキーに差し替えて直します。残高と上限は、キーを替えても直りません。複数のキーが同じ日に一斉に失敗したら、キーより先に残高を疑います。

AI Studioの画面で見えること

手軽なのは、Google AI Studio の「API keys」ページです。制限なしのキーと、Gemini API専用のキーが並び、公式ドキュメントでは次の表示で状態が分かります。

• Key Type：標準キーか、認可キー（auth key）か。2026年5月28日以降にAI Studioで作るキーは認可キーです。
• 「Unrestricted」のラベル：制限なしの標準キーです。「Add restrictions」から制限を付けられます。
• 「Blocked」のタグ：ブロックされているキーです。

ただ、画面の表示で分かるのはキーの状態までで、そのキーで今呼び出しが通るかまでは示しません。通るかは実際に呼び出して確かめます。

Gemini APIキーのチェック準備｜キーを伏せたまま扱う設定

最初に、キーの置き場所を決めます。キーをコードや表に直接書かないことが、この記事で守る一番の決まりです。

公式ドキュメントも、キーは設定ファイルではなく環境変数から読む方法を勧めています。環境変数はWindowsに名前と値を覚えさせておく仕組みです。このコードは、名前が GEMINI_KEY_ で始まる環境変数を、すべてキーとして読みます。

1. Windowsの検索窓に「環境変数」と入力し、設定画面（英語表示では Environment Variables）を開く
2. 「ユーザー環境変数」の「新規」を押し、変数名に GEMINI_KEY_SALES のような名前（後ろの SALES は用途が分かる管理名）、変数値にキーを入れて「OK」を押す
3. 開いているコマンドプロンプトやPowerShellを閉じて、開き直す

PowerShellで $env:GEMINI_KEY_SALES = "ここにキー" と入力する方法もありますが、入力したキーは画面に映り、履歴にも残ることがあります。画面共有や録画中は避けます。

通信にはコマンドプロンプトで pip install requests と実行して入れる requests（PythonからWebへ通信するライブラリ）を使います。

Pythonの入れ方はPythonのインストール手順、requestsの使い方はrequests入門にあります。

Gemini APIキーのチェックコード｜モデル一覧の取得

確認にはGoogleにモデル一覧を1回だけ問い合わせる呼び出し（models.list）を使い、返ってきたステータスコードでキーの状態を判定します。本文が空の単純な呼び出しで、認証は公式のREST例と同じ x-goog-api-key ヘッダーで行います。

• キーを伏せる関数と判定の関数
• Googleに問い合わせる関数
• 複数のキーを順に調べる部分
• 動かしたときの表示

キーを伏せる関数と判定の関数

次の3つのコードを、上から順に1つのファイル gemini_key_check.py へ続けて貼り、環境変数を登録して python gemini_key_check.py で実行します。1つ目の mask はキーの末尾4文字だけを残し、judge はステータスコードを日本語の判定に直します。

import csv
import os
import time
from datetime import datetime

import requests

PREFIX = "GEMINI_KEY_"  # GEMINI_KEY_SALES なら、管理名は SALES
URL = "https://generativelanguage.googleapis.com/v1beta/models"


def mask(key):
    if len(key) < 8:
        return "****"
    return "****" + key[-4:]  # 末尾4文字だけ残す


def judge(status):
    labels = {200: "有効", 400: "無効の疑い", 401: "無効の疑い",
              402: "残高切れの疑い", 403: "権限・制限を確認", 429: "上限に到達（再確認）"}
    if status in labels:
        return labels[status]
    return "保留（再確認）" if status == 408 or status >= 500 else "要確認"

8文字未満の短い値は全部伏せます。短い値で末尾4文字を出すと、中身の大半が見えるためです。

Googleに問い合わせる関数

2つ目は実際にGoogleへ送る関数です。ヘッダーにキーを入れて1回呼び、返すのはステータスコードだけです。通信に失敗したときは、エラーの種類名だけを表示します。

def check_key(key):
    try:
        res = requests.get(URL, headers={"x-goog-api-key": key}, timeout=15)
    except requests.RequestException as e:
        print(f"  通信エラー: {type(e).__name__}")  # 種類名だけ表示する
        return None
    return res.status_code

キーをURLに付ける方式（?key=）にしなかったのは、通信エラーの文にキーが出るためです。自分のPC（127.0.0.1）の使われていないポートへダミーのキーで送ると、エラー文に url: /v1beta/models?key=DUMMY-KEY-AAAA1111 とキーが丸ごと入りました。ヘッダーに入れた場合は url: /v1beta/models で終わり、キーは出ませんでした。

このチェックで分かるのは、モデル一覧の取得が通ったかどうかまでです。文章生成が通るかは確かめていません。

複数のキーを順に調べる部分

3つ目は環境変数からキーを集め、1本ずつ調べて、画面とCSVに結果を出す部分です。

def load_keys():
    return {
        name[len(PREFIX):]: value
        for name, value in os.environ.items()
        if name.startswith(PREFIX) and value
    }


def main():
    keys = load_keys()
    if not keys:
        print(f"{PREFIX} で始まる環境変数が見つかりません")
        return

    rows = []
    for name, key in sorted(keys.items()):
        status = check_key(key)
        label = "通信できず（再確認）" if status is None else judge(status)
        checked_at = datetime.now().strftime("%Y-%m-%d %H:%M")
        print(f"{name:<10} {mask(key)}  {status}  {label}")
        rows.append([name, mask(key), status, label, checked_at])
        time.sleep(1)  # 1本ずつ、間をあけて確認する

    with open("key_check_result.csv", "w", newline="", encoding="utf-8-sig") as f:
        writer = csv.writer(f)
        writer.writerow(["管理名", "キー末尾", "ステータス", "判定", "確認日時"])
        writer.writerows(rows)
    print("key_check_result.csv に書き出しました")


if __name__ == "__main__":
    main()

1本ずつ1秒あけて確認します（time.sleep(1)）。上限がプロジェクトごとに数えられるため、続けて大量に送らないようにしています。CSVは utf-8-sig で保存し、Excelで日本語が崩れにくいようにします。

動かしたときの表示

ダミーのキー5本とテスト用の応答で動かしました。requests.get をテスト用の関数に差し替えたので、Googleには何も送っていません。応答は、SALESが200、OLDが401、TRIALが429、BATCHが503、LABが接続エラーです。

BATCH      ****4444  503  保留（再確認）
  通信エラー: ConnectionError
LAB        ****5555  None  通信できず（再確認）
OLD        ****2222  401  無効の疑い
SALES      ****1111  200  有効
TRIAL      ****3333  429  上限に到達（再確認）
key_check_result.csv に書き出しました

Gemini APIキーのチェック結果｜ステータス別の対応

表示された判定はステータスコードからの目安で、確定ではありません。対応表で意味を確かめたあと、判定ごとの動き方を見ます。

• ステータスコードと判定の対応表
• 無効の疑いが出たときの差し替え
• 429と5xxが出たとき

ステータスコードと判定の対応表

公式のエラー一覧は、401を「キーがない・無効・期限切れ」、402を「残高切れ」、403を「権限がない」、429を「上限の超過」と説明しています（2026年10月時点）。これをもとに判定を分けました。

400も「無効の疑い」に入れたのは、公式が400・402・403を再試行しても直らないエラーとし、原因の例に「無効なAPIキー」を挙げているためです。この呼び出しは本文もパラメーターもないので、書き方よりキーを先に疑います。

この表は公式ドキュメントから組み立てたもので、実際の返事では確かめていません。400と401のどちらが返るかも、最初の1回で見比べてください。

無効の疑いが出たときの差し替え

1. 環境変数に入れたキーに、貼り付けたときの余分な文字が入っていないか見る
2. AI Studio の「API keys」ページで、キーが一覧に残っているか、「Unrestricted」や「Blocked」の表示がないかを見る
3. 「Unrestricted」なら、「Add restrictions」から「Restrict to Gemini API only」を選ぶ（プロジェクトの apikeys.keys.update 権限が必要）
4. 「Blocked」の表示がある、またはキーが一覧にない場合は、新しいキーを作って差し替える

新しいキーに替えるときは、動くことを確かめてから古いキーを無効にします。漏えいが疑われるときも同じ流れです。

429と5xxが出たとき

429は、キーが無効という意味ではなく上限に当たって一時的に断られたという意味です。このチェックでは有効か無効かを判断できないので、時間をおいて再確認します。1日あたりの上限は、太平洋時間の午前0時（日本時間では午後4時か5時ごろ）にリセットされます。

408や5xxは、Google側や通信の一時的な問題です。公式は、待ち時間を延ばして再試行する「指数バックオフ」を勧めていますが、このコードは再試行せず「保留」と記録するだけです。上限は同じプロジェクトのキーで共有されるため、続けて確認すると、後ろのキーほど429になりやすくなります。

Gemini APIキーの管理表｜複数キーの状態を安全に残す

チェック結果は、キー本体を含まない管理表にして残します。コードが書き出すCSVは、管理名・キー末尾・ステータス・判定・確認日時の5列で、管理表（スプレッドシート）では、ここに手で書く列を足します。

反対に、キー全体や先頭の数文字は書きません。末尾4文字だけなら、表を共有してもキーとしては使えません。

key_check_result.csv は、実行のたびに上書きされます。履歴を残すときは、管理表の判定と確認日時の列へ、その都度貼り写します。

毎週など決まったタイミングで自動実行したくなったら、コードより先に、次の2つを決めます。

• 頻度：確認の呼び出しが上限にどう数えられるかは、公式ドキュメントでは確かめられませんでした。週1回など、必要な頻度から始めます。
• 差し替えの担当：「無効の疑い」が出たとき、誰が新しいキーに入れ替えるかを決めます。画面やログにキーが出ない作りは、そのまま保ちます。

勝率が高いのは、最初の数回を手で実行してから自動実行へ進める順番です。設定はWindowsタスクスケジューラの記事で扱っています。

Gemini APIキーの確認に関するよくある質問

キーの生死確認について、よくある疑問をまとめました。

429が出たキーは、無効になったのですか？

無効とは限りません。429は上限に当たったことを示すコードで、このチェックでは有効・無効を判断できません。公式は、待ち時間を延ばしながら再試行するよう案内しています。

同じプロジェクトでキーを増やすと、使える量も増えますか？

増えません。公式ドキュメントによると、レート制限はAPIキーごとではなく、プロジェクトごとに適用されます。引き上げの申請フォームはありますが、公式は保証していません。

Gemini APIキーを伏せた確認と結果の記録

Gemini APIキーの生死確認のポイントを整理します。

最初は1本のキーで動かし、想定と違う表示が出たら、公式のエラー一覧と照らすのが近道です。

キーの扱いやエラーの切り分けは、次の記事でも扱っています。

• APIキーの安全な管理方法｜環境変数で守る基本と書き方
• AI APIエラーの切り分け方｜キー・モデル・権限・料金を見る順番
• Gemini APIを初めて動かす手順｜キー確認からサンプル実行まで

参考資料
Gemini API キー | Google AI for Developers
トラブルシューティング | Gemini API
API errors | Gemini API
Models | Gemini API リファレンス
レート制限 | Gemini API
課金 | Gemini API