Gemini API Python入門｜google-genaiのコピペ集

Python から Gemini API を呼ぶには、pip install google-genai で入る Google Gen AI SDK を使い、client.models.generate_content() を呼びます。 返答の文字は response.text で取り出せます。import google.generativeai で始まる以前のライブラリは、2025年11月30日でサポートが終わっています。

from google import genai

client = genai.Client()  # 環境変数 GEMINI_API_KEY を読む
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Gemini APIを一言で説明して",
)
print(response.text)

確認環境：google-genai 2.29.0（pip の最新版）・pydantic 2.14.1・Python 3.11.15（Linux）。SDK が送る URL と JSON、返答の取り出し方、チャットの履歴、自動の関数呼び出し、例外の種類と再試行の回数は、http_options の base_url を手元の擬似エンドポイント（Gemini API の応答の形を返す小さな HTTP サーバー）に向けて確かめました。再試行の既定値は SDK のソース（_api_client.py）で確かめました。モデル名・料金・無料枠・仕様は Google の公式ドキュメントに基づきます（確認日 2026年10月12日）。

最初に用意するもの

pip install -U google-genai
export GEMINI_API_KEY="AIza..."   # Windows PowerShell は $env:GEMINI_API_KEY="AIza..."

SDK は GOOGLE_API_KEY と GEMINI_API_KEY の両方を読みます。両方あると GOOGLE_API_KEY が使われます（SDK のソースと README で確認）。キーが無いと、genai.Client() の時点で次のエラーになりました。

ValueError: No API key was provided. Please pass a valid API key. Learn how to create an API key at https://ai.google.dev/gemini-api/docs/api-key.

キーをコードに直書きしない方法は、関連記事「.envの使い方と注意点｜APIキーを安全に管理する方法」で扱っています。

モデルと料金・無料枠（2026年10月12日に公式ドキュメントで確認）

• 料金ページでは、無料枠のデータは製品の改善に使われる（有料は使われない）とされています。社外秘のデータは有料枠で送るのが安全です。
• 無料枠の回数（1分あたり・1日あたり）は、レート制限のページでは数値が載っておらず、Google AI Studio で確認する形です。1日の回数は太平洋時間の0時にリセットされます。
• gemini-3-pro-preview・gemini-2.0-flash などはモデル一覧で「Shut down」になっていました。以前の記事にあるモデル名をそのまま使うと、404 になることがあります。

本文のコードは gemini-3.8-flash で書いています。

最小コード

from google import genai

client = genai.Client()
response = client.models.generate_content(model="gemini-3.8-flash", contents="こんにちは")

print(response.text)                                   # 返答の文字
print(response.candidates[0].finish_reason)            # FinishReason.STOP
print(response.usage_metadata.prompt_token_count)      # 入力トークン
print(response.usage_metadata.candidates_token_count)  # 出力トークン

擬似エンドポイントで受けたとき、SDK は次の URL と JSON を送っていました。文字列の contents は、role: user のメッセージに包まれます。

POST /v1beta/models/gemini-3.8-flash:generateContent
{"contents": [{"parts": [{"text": "こんにちは"}], "role": "user"}]}

system_instruction と config

system_instruction や temperature は、config にまとめて渡します。 以前のライブラリのように、モデルを作るときに渡す形ではありません。

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="VPNにつながりません",
    config=types.GenerateContentConfig(
        system_instruction="あなたは社内ヘルプデスクです。100文字以内で答えます。",
        temperature=0.2,
        max_output_tokens=300,
        stop_sequences=["###"],
        thinking_config=types.ThinkingConfig(thinking_level="low"),
    ),
)

SDK は名前を camelCase に直し、systemInstruction と generationConfig に分けて送っていました。

{"contents": [...], "systemInstruction": {"parts": [{"text": "あなたは社内ヘルプデスクです。"}], "role": "user"},
 "generationConfig": {"temperature": 0.2, "maxOutputTokens": 300, "stopSequences": ["###"], "thinkingConfig": {"thinking_level": "LOW"}}}

config は dict でも書けます。config={"system_instruction": "簡潔に", "max_output_tokens": 100} も同じ形で送られました。

指示の書き方は、関連記事「システムプロンプトの書き方と例｜エンジニア向けカスタム指示テンプレート」で扱っています。

チャット：会話を続ける

client.chats.create() で作ったチャットは、履歴を SDK の中に持ち、send_message() のたびに全部まとめて送ります。 サーバーが覚えているわけではありません。

from google import genai
from google.genai import types

client = genai.Client()
chat = client.chats.create(
    model="gemini-3.8-flash",
    config=types.GenerateContentConfig(system_instruction="簡潔に答えてください。"),
)
print(chat.send_message("私の名前は山田です。").text)
print(chat.send_message("私の名前は？").text)

for message in chat.get_history():
    print(message.role, message.parts[0].text)

2回目のリクエストでは、contents が「user → model → user」の3件で送られていました。system_instruction も毎回付きます。

{"contents": [{"parts": [{"text": "私の名前は山田です。"}], "role": "user"},
              {"parts": [{"text": "こんにちは。ご用件をどうぞ。"}], "role": "model"},
              {"parts": [{"text": "私の名前は？"}], "role": "user"}], "systemInstruction": {...}}

チャットを使わずに書くなら、contents に types.Content のリストを自分で積み上げます。履歴を DB に保存したいときはこちらが扱いやすくなります。

history = [types.Content(role="user", parts=[types.Part(text="私の名前は山田です。")])]
r = client.models.generate_content(model="gemini-3.8-flash", contents=history)
history.append(r.candidates[0].content)          # role: model の返答をそのまま足す
history.append(types.Content(role="user", parts=[types.Part(text="私の名前は？")]))
r = client.models.generate_content(model="gemini-3.8-flash", contents=history)

履歴が長いほど入力トークンが増えます。トークンの数え方は、関連記事「トークンとは｜生成AIの数え方・日本語の文字数目安と節約方法」で扱っています。

ストリーム：少しずつ受け取る

generate_content_stream() は、返り値を for で回すと GenerateContentResponse の断片が順に届きます。 各断片の .text を出力します。

for chunk in client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="Gemini APIを説明して",
):
    print(chunk.text, end="", flush=True)
print()

送り先は :streamGenerateContent?alt=sse に変わります（SSE＝サーバーから順に送られてくる形式）。3つに分けて返したとき、受け取った断片は次のとおりでした。最後の断片だけに finish_reason が入ります。

POST /v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse

'Geminiは'          None
'Googleの'          None
'生成AIモデルです。'  FinishReason.STOP

チャットでは chat.send_message_stream("...") です。手元では、ストリームで受けた返答は断片ごとに別の model メッセージとして履歴に入っていました（get_history() で model が3件）。次の send_message ではそのまま送られます。

JSON で出力させる

response_mime_type="application/json" と response_schema に Pydantic のクラスを渡すと、response.parsed にそのクラスのオブジェクトが入ります。

from google import genai
from google.genai import types
from pydantic import BaseModel

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="金曜に佐藤さんと鈴木さんと定例会議",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=CalendarEvent,
    ),
)
event = response.parsed          # CalendarEvent のオブジェクト
print(event.name, event.participants)

SDK はクラスを Gemini のスキーマ形式（型名が大文字の STRING・ARRAY など）に変え、property_ordering（キーの順番）も付けて送っていました。

"generationConfig": {"responseMimeType": "application/json", "responseSchema": {"properties": {"name": {"title": "Name", "type": "STRING"}, "date": {"title": "Date", "type": "STRING"}, "participants": {"items": {"type": "STRING"}, "title": "Participants", "type": "ARRAY"}}, "property_ordering": ["name", "date", "participants"], "required": ["name", "date", "participants"], "title": "CalendarEvent", "type": "OBJECT"}}

ふつうの JSON Schema で渡すなら response_json_schema を使います。

構造化出力のページでは、「JSON として正しくても値が正しいとは限らないので、アプリで値を検証する」ことを勧めています。dict で受けたときは CalendarEvent.model_validate(response.parsed) で検証できます。方式ごとの違いは、関連記事「LLMの構造化出力とJSON｜4方式の違いとPydantic検証の実行結果」で扱っています。

関数呼び出し

Python の SDK は、関数そのものを tools に渡すと、呼び出しから結果の返送までを自動で行います。 型ヒントと docstring（関数の説明文）から、関数の定義を作ります。

自動で呼ばせる

from google import genai
from google.genai import types

def get_weather(city: str) -> dict:
    """都市名を受け取り、今日の天気を返す。

    Args:
        city: 都市名
    """
    return {"city": city, "weather": "晴れ"}   # 本当は天気APIを呼ぶ

client = genai.Client()
chat = client.chats.create(
    model="gemini-3.8-flash",
    config=types.GenerateContentConfig(tools=[get_weather]),
)
print(chat.send_message("東京の天気は？").text)

擬似エンドポイントで functionCall を返すと、SDK が get_weather("東京") を実行し、結果を付けてもう一度送り、最後の文字（東京は晴れです。）を返しました。automatic_function_calling_history には往復の3件が残っていました。

generate_content() に関数を渡したときは、次の注意が表示されました（チャットで使うことを勧める内容）。

Direct use of automatic function calling (AFC) in Models.generate_content is not recommended. Instead, we recommend to use AFC in Chat.send_message.

自動の往復は、SDK の既定で最大10回です（_DEFAULT_MAX_REMOTE_CALLS_AFC = 10）。止めるときは automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True) を config に入れます。

自分で往復させる

実行の前に確認を挟みたい、ログを取りたいときは、定義だけを渡して自分で返します。

from google import genai
from google.genai import types

client = genai.Client()

def get_weather(city: str) -> dict:
    return {"city": city, "weather": "晴れ"}

get_weather_decl = {
    "name": "get_weather",
    "description": "都市名を受け取り、今日の天気を返す",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string", "description": "都市名"}},
        "required": ["city"],
    },
}
config = types.GenerateContentConfig(tools=[types.Tool(function_declarations=[get_weather_decl])])
contents = [types.Content(role="user", parts=[types.Part(text="東京の天気は？")])]

response = client.models.generate_content(model="gemini-3.8-flash", contents=contents, config=config)
if response.function_calls:
    contents.append(response.candidates[0].content)   # 返答をそのまま履歴に入れる
    parts = []
    for fc in response.function_calls:
        result = get_weather(**fc.args)                # args は dict
        parts.append(types.Part(function_response=types.FunctionResponse(
            id=fc.id, name=fc.name, response={"result": result})))
    contents.append(types.Content(role="user", parts=parts))
    response = client.models.generate_content(model="gemini-3.8-flash", contents=contents, config=config)
print(response.text)

仕組みの全体は、関連記事「Function Calling（tool use）の仕組みとPython実装」で扱っています。

画像入力

画像は types.Part.from_bytes() でバイト列のまま渡せます。 文字と画像を contents のリストに並べます。

from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_bytes(data=Path("screen.png").read_bytes(), mime_type="image/png"),
        "この画面のエラーの原因を推測して",
    ],
)
print(response.text)

SDK は base64 に変えて inlineData で送っていました。手元では、+ / の代わりに - _ を使う URL セーフな base64 でした。

{"contents": [{"parts": [{"inlineData": {"data": "iVBORw0KGgo...J_pLvAAAAAElFTkSuQmCC", "mime_type": "image/png"}}, {"text": "この画像は？"}], "role": "user"}]}

google-generativeai からの移行表

以前のライブラリ google-generativeai（PyPI の最終版は 0.8.6）は、GitHub のリポジトリに「すべてのサポートは 2025年11月30日に終了した」と書かれています。移行ガイドに沿った対応表です。

いちばん大きな違いは、モデルのオブジェクトを作らず、Client から呼ぶ形になったことです。 引数名も content → contents、stream=True → _stream 付きのメソッド、と変わっています。

エラーと再試行

例外の種類

SDK の例外は google.genai.errors.APIError で、4xx は ClientError、5xx は ServerError です。e.code（HTTP の番号）・e.status・e.message を持ちます。

from google import genai
from google.genai import errors

client = genai.Client()
try:
    response = client.models.generate_content(model="gemini-3.8-flash", contents="こんにちは")
except errors.ClientError as e:
    print("リクエスト側の問題:", e.code, e.status, e.message)
except errors.ServerError as e:
    print("サーバー側の問題。あとで再試行:", e.code, e.status)

擬似エンドポイントで返したときの例外です。

API キーが漏れたと報告されたキーは止められ、トラブルシューティングのページでは「Your API key was reported as leaked.」という文になるとされています。新しいキーを作り直します。漏らしたときの手順は、関連記事「APIキーをGitHubにpushしてしまった時の対処手順」で扱っています。

再試行は既定で「しない」

google-genai 2.29.0 は、何も設定しないと再試行しません。 SDK のソースでは、retry_options が無いと「1回で止める」設定になっていました。擬似エンドポイントで試した結果です。

HttpRetryOptions の値を省略したときの既定値は、ソースの _RETRY_* の定数です。

from google import genai
from google.genai import types

client = genai.Client(
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(attempts=5, initial_delay=1.0, max_delay=30.0),
        timeout=120_000,   # ミリ秒
    )
)

429 の考え方と自前の再試行は、関連記事「LLM APIの429・529エラー対処｜リトライ実装とエラー一覧」で扱っています。待ち時間の決め方は、関連記事「指数バックオフとは？リトライ間隔の決め方とジッターの実装」で扱っています。

Vertex AI で使う切り替え

Google Cloud の Vertex AI（README では「Agent Platform（旧 Vertex AI）」）で使うときは、Client に enterprise=True とプロジェクト・リージョンを渡すだけです。 generate_content などの書き方はそのまま使えます。認証は API キーではなく、Google Cloud の認証情報（gcloud auth application-default login やサービスアカウント）です。

from google import genai

client = genai.Client(enterprise=True, project="my-project", location="global")
response = client.models.generate_content(model="gemini-3.8-flash", contents="こんにちは")

環境変数で切り替えることもできます。

export GOOGLE_GENAI_USE_ENTERPRISE=true
export GOOGLE_CLOUD_PROJECT=my-project
export GOOGLE_CLOUD_LOCATION=global

手元で送り先を確かめると、URL にプロジェクトとリージョンが入っていました。

POST /v1beta1/projects/my-project/locations/global/publishers/google/models/gemini-3.8-flash:generateContent
POST /v1beta1/projects/my-project/locations/asia-northeast1/publishers/google/models/gemini-3.8-flash:generateContent

以前からある vertexai=True と GOOGLE_GENAI_USE_VERTEXAI も、2.29.0 では enterprise の「以前の名前（Legacy flag）」として使えます。両方に違う値を入れるとエラーになります。安定版の API を使うときは http_options=types.HttpOptions(api_version="v1") で、手元でも POST /v1/models/... に変わりました。Vertex AI で使えるモデルとリージョンは、Google Cloud のドキュメントで確かめます。

新しい Interactions API について

ドキュメントでは、2026年6月に一般提供（GA）になった Interactions API を「新しいプロジェクトに勧める」としています。generateContent は「legacy」と呼ばれていますが、「引き続きフルサポートされる」とも書かれています。同じ SDK で次のように呼びます。

interaction = client.interactions.create(model="gemini-3.8-flash", input="こんにちは")
print(interaction.output_text)

手元では POST /v1beta/interactions に {"model":"gemini-3.8-flash","input":"こんにちは"} が送られていました。ドキュメントによると、previous_interaction_id で前のやり取りの続きにでき、保存期間は無料枠で1日・有料枠で55日です。ネットの記事やサンプルの多くは generate_content で書かれているため、本記事はこちらを中心にしています。

Claude・OpenAI との書き方の対応

OpenAI は、関連記事「OpenAI API Python入門｜Responses APIのコピペ集」で扱っています。Claude は、関連記事「Claude API Python入門｜Anthropic SDKコピペレシピ集」で扱っています。AWS から Claude を呼ぶ方法は、関連記事「Bedrock Python入門｜Converse APIでClaudeを呼ぶ」で扱っています。ターミナルで Gemini を使うツールは、関連記事「Gemini CLI 使い方｜コマンド一覧・設定・GEMINI.md・無料枠」で扱っています。手元の PC で動かすモデルは、関連記事「Ollamaの使い方｜ローカルLLMのコマンド一覧とAPIの呼び方」で扱っています。

よくある質問

Q. 非同期（async）で呼べますか。 A. client.aio.models.generate_content(...) を await します。README では、async with Client().aio as aclient: の形で閉じ忘れを防ぐ例も載っています。

Q. クライアントは閉じたほうがよいですか。 A. README では、HTTP の接続などを確実に片付けるために client.close()（非同期は await aclient.aclose()）か、with genai.Client() as client: を使う書き方を示しています。

Q. トークン数を先に知りたいです。 A. client.models.count_tokens(model="gemini-3.8-flash", contents="...") で数えられます。

Q. OpenAI のライブラリで Gemini を呼べますか。 A. Gemini API には OpenAI 互換の窓口もあります。ドキュメントの例では、openai ライブラリの base_url を https://generativelanguage.googleapis.com/v1beta/openai/ にしています。同じページには「OpenAI のライブラリをまだ使っていないなら、Gemini API を直接呼ぶことを勧める」とあります。

まとめ

• pip install google-genai → from google import genai → client.models.generate_content() → response.text
• system_instruction・temperature などは config にまとめる
• 会話は client.chats.create()。SDK が履歴を持ち、毎回全部送る
• JSON は response_mime_type と response_schema=Pydanticのクラス → response.parsed
• 関数は tools=[関数] で自動実行（既定で最大10回）。自分で回すなら candidates[0].content を丸ごと履歴へ
• 再試行は既定でしない。HttpRetryOptions で回数を決める
• Vertex AI は enterprise=True, project=..., location=...（以前の vertexai=True も使える）
• google-generativeai は 2025年11月30日にサポート終了。移行表で置き換える

参考・出典

確認日はいずれも 2026年10月12日です。

• Gemini API ドキュメント「Getting started（generateContent）」：https://ai.google.dev/gemini-api/docs/generate-content/get-started
• Gemini API ドキュメント「Models」：https://ai.google.dev/gemini-api/docs/models
• Gemini API ドキュメント「Pricing」：https://ai.google.dev/gemini-api/docs/pricing
• Gemini API ドキュメント「Rate limits」：https://ai.google.dev/gemini-api/docs/rate-limits
• Gemini API ドキュメント「Migrate to the Google GenAI SDK」：https://ai.google.dev/gemini-api/docs/migrate
• Gemini API ドキュメント「Structured output（generateContent）」：https://ai.google.dev/gemini-api/docs/generate-content/structured-output
• Gemini API ドキュメント「Function calling（generateContent）」：https://ai.google.dev/gemini-api/docs/generate-content/function-calling
• Gemini API ドキュメント「Image understanding」：https://ai.google.dev/gemini-api/docs/image-understanding
• Gemini API ドキュメント「Troubleshooting guide」：https://ai.google.dev/gemini-api/docs/troubleshooting
• Gemini API ドキュメント「API errors」：https://ai.google.dev/gemini-api/docs/api-errors
• Gemini API ドキュメント「OpenAI compatibility」：https://ai.google.dev/gemini-api/docs/openai
• Gemini API ドキュメント「Interactions API」：https://ai.google.dev/gemini-api/docs/interactions
• GitHub「googleapis/python-genai」：https://github.com/googleapis/python-genai
• GitHub「google-gemini/deprecated-generative-ai-python」：https://github.com/google-gemini/deprecated-generative-ai-python
• PyPI「google-genai」：https://pypi.org/project/google-genai/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。