google-genai SDK を Python で使い始めると、最初の数分でかならず何かしらのエラーに出会います。Unauthenticated、ImportError、404 model not found——エラーメッセージを見ても「どこを直せばいいのか」ピンとこないことは少なくないのではないでしょうか。
私自身、Antigravity 上で Python の google-genai ライブラリを本格的に使い始めたとき、同じエラーを何度も繰り返してしまいました。ここではその経験をもとに「よく発生するエラーのパターン」と「それぞれの修正方法」を整理しました。
認証エラー:Unauthenticated / API_KEY_INVALID
最もよく遭遇するのが認証系のエラーです。メッセージはいくつかのバリエーションがあります。
google.api_core.exceptions.Unauthenticated: 401 Request had invalid authentication credentials.
google.api_core.exceptions.PermissionDenied: 403 API key not valid.
原因は大きく2つです。
- API キーが正しく渡されていない
- API キーの有効範囲(Antigravity AI API)が有効になっていない
まず、API キーの渡し方を確認しましょう。google-genai SDK(バージョン 1.0 以降)では、configure() を使った旧来の書き方と、クライアントインスタンス生成時に渡す新しい書き方の2種類があります。
# 旧来の書き方(google-generativeai パッケージ)
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY") # ← 旧パッケージ
# 新しい書き方(google-genai パッケージ)
from google import genai
client = genai.Client(api_key="YOUR_API_KEY") # ← これが正しい
response = client.models.generate_content(
model="gemini-2.0-flash",
contents="Hello, Antigravity\!"
)
print(response.text)重要な落とし穴: google-generativeai(旧)と google-genai(新)はパッケージ名が似ていますが、インポート方法が異なります。どちらのパッケージがインストールされているかを確認してください。
pip list | grep google-gen
# google-genai 1.x.x ← 新パッケージ
# google-generativeai 0.x.x ← 旧パッケージ(非推奨)Antigravity の仮想環境を使っている場合、エディタ内ターミナルで pip list を実行すると確認できます。API キーの有効範囲については、Google AI Studio でキーを生成した後、「Generative Language API」が有効になっているかを Google Cloud Console でも確認してみてください。
ImportError:モジュール名の混乱
ImportError: cannot import name 'genai' from 'google'
ModuleNotFoundError: No module named 'google.generativeai'
このエラーが出る場合、インポート文とインストールされているパッケージが一致していないことがほぼ確実です。
# パターン1: 新パッケージのインポート(google-genai をインストールした場合)
from google import genai # ✅ 正しい
import google.generativeai as genai # ❌ 旧パッケージのインポート文
# パターン2: Antigravity の仮想環境にインストールされていない
# → エディタ内ターミナルで以下を実行
pip install google-genaiAntigravity 上でよくあるのが、グローバル環境にインストールしたパッケージが仮想環境から見えないというケースです。プロジェクトフォルダに .venv や venv があれば、そちらを有効にしてから pip install する必要があります。
# Antigravity のターミナルで実行
python -m venv .venv
source .venv/bin/activate # Mac/Linux
.venv\Scripts\activate # Windows
pip install google-genaiAntigravity のエディタが正しい Python インタープリタを認識しているかどうかも確認しましょう。コマンドパレット(Cmd+Shift+P)から Python: Select Interpreter を実行して、.venv の Python を選択してください。
NotFound:廃止されたモデル名
google.api_core.exceptions.NotFound: 404 models/gemini-pro is not found for API version v1beta
Google は定期的にモデルを更新・廃止しています。古いチュートリアルをそのまま使うと、このエラーが発生します。
# ❌ 廃止または利用不可のモデル名
model="gemini-pro"
model="gemini-1.0-pro"
model="models/gemini-pro"
# ✅ 2026年時点で推奨されるモデル名
model="gemini-2.0-flash" # 高速・バランス型(おすすめ)
model="gemini-2.5-pro-preview" # 高性能(Antigravity AIと連携する場合)
model="gemini-2.0-flash-lite" # 低コスト・軽量タスク向け使用可能なモデルの一覧を動的に取得するには、以下のコードが便利です。
from google import genai
client = genai.Client(api_key="YOUR_API_KEY")
for model in client.models.list():
if "generateContent" in model.supported_generation_methods:
print(model.name)
# 出力例:
# models/gemini-2.0-flash
# models/gemini-2.0-flash-lite
# models/gemini-2.5-pro-previewモデル名は models/gemini-2.0-flash の形式で返ってきますが、generate_content() に渡すときは gemini-2.0-flash(models/ プレフィックスなし)でも動作します。
ResourceExhausted:レート制限エラーへの対処
google.api_core.exceptions.ResourceExhausted: 429 Quota exceeded for quota metric
無料枠での開発中は特によく発生します。単純にリトライするだけでは同じエラーが続くため、**指数バックオフ(Exponential Backoff)**を実装するのが実用的です。
import time
import random
from google import genai
from google.api_core import exceptions
def generate_with_retry(client, model, contents, max_retries=5):
"""レート制限エラー時に指数バックオフでリトライする"""
for attempt in range(max_retries):
try:
response = client.models.generate_content(
model=model,
contents=contents
)
return response
except exceptions.ResourceExhausted as e:
if attempt == max_retries - 1:
raise # 最大リトライ数を超えたら例外を再スロー
# 指数バックオフ + ジッター(ランダムな遅延を加える)
wait_time = (2 ** attempt) + random.uniform(0, 1)
print(f"レート制限エラー。{wait_time:.1f}秒後にリトライ({attempt+1}/{max_retries})")
time.sleep(wait_time)
except exceptions.GoogleAPIError as e:
# レート制限以外のエラーは即座に再スロー
raise
client = genai.Client(api_key="YOUR_API_KEY")
response = generate_with_retry(client, "gemini-2.0-flash", "Pythonでクイックソートを実装して")
print(response.text)本番環境であれば、tenacity ライブラリを使うとより簡潔に書けます(pip install tenacity)。
Antigravity の仮想環境と環境変数の罠
API キーをコードに直接書きたくない場合、.env ファイルを使うことが多いと思います。Antigravity でこれがうまく動かない場合の確認ポイントをまとめます。
# .env ファイルを自動読み込みする設定
from dotenv import load_dotenv # pip install python-dotenv
import os
from google import genai
load_dotenv() # .env ファイルから環境変数を読み込む
api_key = os.environ.get("GOOGLE_API_KEY")
if not api_key:
raise ValueError("GOOGLE_API_KEY が設定されていません。.env ファイルを確認してください。")
client = genai.Client(api_key=api_key)よくあるミス: .env ファイルがプロジェクトルートではなく、別のフォルダにあります。Antigravity でターミナルを開くと、カレントディレクトリがプロジェクトルートではない場合があります。os.getcwd() で現在のディレクトリを確認してみてください。
また、GOOGLE_API_KEY と GEMINI_API_KEY——どちらの変数名を使っているかも確認しましょう。google-genai SDK はデフォルトで GOOGLE_API_KEY を参照しますが、コードによっては別の変数名を期待していることがあります。
エラー診断チェックリスト
問題が解決しない場合、以下の順番で確認してみてください。
1. パッケージとインポートの確認
pip list | grep google-gen
python -c "from google import genai; print(genai.__version__)"2. API キーの有効性確認
curl -H "x-goog-api-key: YOUR_API_KEY" \
"https://generativelanguage.googleapis.com/v1beta/models"200 が返れば API キーは有効です。403 や 401 が返れば認証の問題です。
3. モデル名の確認(上記のモデル一覧コードを使用)
4. 仮想環境の確認
which python # 使用している Python のパスを確認
pip show google-genai # インストール済みか確認エラーメッセージをそのまま Antigravity のチャットに貼り付けて「このエラーの原因と修正方法を教えて」と聞くのも、私がよく使う手です。エラーのスタックトレース全体を渡すと、より的確な回答が返ってくることが多いです。
ぜひ今日、pip list | grep google-gen だけでも実行して、使っているパッケージのバージョンを確認してみてください。多くのエラーはそこから解決の糸口が見えてきます。
Python での AI 開発