Gemini 3.8 Flash APIチュートリアル：思考レベル、PDF抽出、Pythonでの関数呼び出し

Gemini 3.8 Flashとは？

Gemini 3.8 FlashはGoogleの実用モデルで、2026年9月2日から一般提供されています。モデルIDはgemini-3.8-flashです。3.7 Flashから3週間で登場し、長期的なコーディング、エージェント的なワークフロー、金融や法務など専門領域でのマルチステップ推論を想定しています。

API呼び出しに関わる仕様は3.7から不変です。

• 100万トークンのコンテキストウィンドウ
• 最大出力64kトークン
• マルチモーダル入力（テキスト、画像、動画、音声、PDF）に対してテキスト出力
• 同じ導入価格：2026年12月31日まで入力100万トークン$0.75、出力100万トークン$3.75（2027年1月1日以降は$1.50/$7.50）

変わったのは表面ではなく挙動です。Googleによれば、3.8は複雑なタスクでより多くの推論ステップを取り、ツール呼び出しも反復的に行うため、高い努力レベルではトークン使用量が増える可能性があります。効率重視なら3.7 Flashは引き続き完全サポートです。

ベンチマークや詳細な価格はGemini 3.8 Flashガイド、プラットフォーム全体の概観はWhat is Google Gemini?をご覧ください。

Gemini 3.8 Flash と 3.8 Flash Cyber の違い

今回の提供には2つのバリアントが含まれますが、モデルIDを入力できるのは1つだけです。

• Gemini 3.8 Flash は汎用モデルで、Google AI StudioおよびGemini APIで利用可能です。
• Gemini 3.8 Flash Cyber は、脆弱性発見と自動パッチ適用に特化したサイバーセキュリティ向けバリアントです。

CyberバリアントはパブリックAPIでは利用できません。アクセスはGoogleのFairwind Programを通じ、承認された政府当局、重要インフラ事業者、ソフトウェアメンテナに限定されています。

本チュートリアルに従う場合、使用するモデルIDはgemini-3.8-flashです。以降の内容でCyberバリアントは必要ありません。

Interactions API と generateContent の比較

Gemini 3.8 Flashを呼び出すには、google-genai SDKのclient.interactions.create()を使います。Googleは2026年6月にInteractions APIをGAにし、新規開発にはこれを推奨しています。generateContentは動作しますがレガシーです。サーバーサイドの履歴、バックグラウンド実行、実行ステップの可視化など新機能はまずInteractionsに入ります。

実務での最大の変化は状態管理です。マルチターン呼び出しはサーバー側のprevious_interaction_idを使います。直前のインタラクションIDを渡すと、サーバーが状態を復元します。クライアント側で履歴を手動連結・再送する必要はありません。モデルターンを事前入力するのも避けてください。これはレガシーのgenerateContentパターンで、Gemini 3.xでは壊れます。

ほとんどの人が引っかかる点が1つあり、PDFの節でも再登場します。previous_interaction_idが復元するのは会話履歴のみです。tools、system_instruction、generation_config、response_formatはインタラクション単位なので、必要なターンでは毎回渡す必要があります。

thinking_level はサンプリングノブの代替

旧来のGeminiでは、出力のランダム性を制御するためにtemperature、top_p、top_kを使っていました。Gemini 3.xではこれらのサンプリングノブを廃止し、thinking_levelに統一しました。

有効な値は3つです。

• low：推論トークン最小で最速・最安。抽出・分類・自分で検証する前提の用途に適合。

• medium：デフォルト。コードとエージェント作業にGoogle推奨。

• high：最大の推論予算。難しい多段ロジックやツール多用タスク向け。

minimalは送らないでください。Gemini Flash 3.7以降は無効で、400のバリデーションエラーになります。

3.7から引き継がれるもう1つのルールとして、frequency_penalty、presence_penalty、candidate_countは現在はアクティブなAPIエラーを返します。レガシー設定からも削除してください。

Gemini 3.8 Flash APIをどうセットアップするか？

環境構築は約2分で完了します。Google AI StudioのAPIキーと、更新されたgoogle-genai Pythonライブラリが必要です。

Google AI StudioでAPIキーを取得

ブラウザでGoogle AI Studioにアクセスし、Googleアカウントでログインします。Create API Keyをクリックし、Google Cloudプロジェクトを選択または作成し、シークレットキー文字列をコピーします。

ターミナルを開き、export GEMINI_API_KEY=<your-key>で環境変数として保存します。

キーをURLの?key=クエリパラメータで渡してはいけません。クエリ文字列はサーバーログ、ブラウザ履歴、プロキシキャッシュに残ります。コードを書く前にプレイグラウンドでモデルを試したい場合は、Google AI StudioチュートリアルでChat、Build、Streamモードを解説しています。本記事はAPIに専念します。

プロダクション環境では認証の扱いが変わります。Vertex AI（現在はGemini Enterprise Agent Platformの一部）を使うと、素のAPIキーではなくOAuth、IAMロール、リージョンエンドポイントを利用できます。本チュートリアルは学習の最短経路としてAI Studioキーを使用しますが、実ユーザーデータに触れる前にVertexへの移行計画を立ててください。

google-genaiをインストールしてクライアントを作成

未だにgoogle-generativeaiのインストールを案内するチュートリアルがありますが、これは旧SDKでInteractions APIがありません。google-genai（バージョン2.3.0以降）をインストールしてください。

pip install -U google-genai

インストール後、Pythonがライブラリを読み込み、クライアントをエラーなく初期化できることを確認します。

from google import genai # reads GEMINI_API_KEY from the environment
client = genai.Client() 
print("Client initialized successfully.")

最初のInteractions API呼び出し

Interactions APIへの各リクエストはInteractionリソースを作成し、入力、モデルの思考、ツール呼び出し、最終出力を完全に記録します。SDKは最終テキストをoutput_textプロパティで提供するため、通常は手動でステップを辿る必要はありません。

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        "Write a pandas one-liner that adds a 7-day rolling average "
        "revenue column per store_id to a DataFrame with columns "
        "date, store_id, revenue. Reply with only the code, no explanation."
    ),
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
    f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
    f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)

筆者の環境では、連結したpandasのワンライナーが返り、使用状況は次のように表示されました。

この数値には3.7からの最初の実質的な差が隠れています。同じタスクを、より長いプロンプトかつ出力制約なしで再実行すると、3.8は推論トークンを1,436、出力トークンを870消費しました。制約ありでは、推論1,515に対して出力42でした。推論予算はほとんど動かず、これは3.7とは逆の挙動です。3.7では同じ2つのプロンプトで推論が838から1,530へ大きく揺れました。

つまり3.8は、タスクの表現方法ではなくタスク自体に基づいてどれだけ考えるかを決めているようで、Googleの「意図的に推論・検証を増やす」という説明に一致します。推論は出力レートで課金されるため、制約ありの呼び出しでは課金トークンの約97%が見えない推論でした。次節がある理由はこれです。

レスポンスをストリームする

チャットUIなど人が見ているインターフェースでは、数秒待たされるだけでも遅く感じます。client.interactions.create()にstream=Trueを渡し、到着したチャンクを逐次表示します。

	from google import genai

	client = genai.Client()

	stream = client.interactions.create(
	   model="gemini-3.8-flash",
	   input="Explain the difference between a JOIN and a correlated subquery in SQL.",
	   generation_config={"thinking_level": "low"},
	   stream=True,
	)

	for event in stream:
	   if event.event_type == "step.delta" and event.delta.type == "text":
	       print(event.delta.text, end="", flush=True)
	print() 

これを実行すると、thinking_level: "low"でも、概念比較、サマリーテーブル、そして各顧客の最新注文を求める2つのSQL例（派生テーブルのJOIN版とSELECTリスト内の相関サブクエリ版）まで揃った長文の整理された回答が返りました。先頭の文字はほぼ即時に表示され、これがストリーミングの狙いです。

最後のprint()には意味があります。これがないと最後のチャンクが行中で終わり、zshのプロンプト前に余計な%が出ることがあります。ストリームはモデルのテキストが終わった場所でちょうど止まるためです。また、トークン数をリクエスト単位で記録するなら、デルタを積み上げずに最終完了イベントから読み取ってください。

thinking_levelはコストと品質をどう変えるか？

thinking_levelは、Gemini 3.8 Flashが回答を書く前にどれだけ推論するかを決めます。推論トークンは出力レート（100万あたり$3.75）で課金されます。3.8は意図的にこれを活用し、複雑なタスクでは追加の推論ステップを取り、高い努力レベルでは3.7より多くのトークンを消費する可能性があります。

同一プロンプトをlow/medium/highで実行

テストは、同一プロンプトで3段階すべてに送る支払い再試行関数のレースコンディションです。同時実行バグは斜め読みを罰するので、レベル差が出るならここで顕在化します。この記事から1つだけ実行するならこのコードにしてください。数字ほど雄弁なものはありません。

import time

from google import genai

client = genai.Client()

BUGGY_CODE = '''
import threading

payment_attempts = {}

def retry_payment(order_id, charge_fn, max_retries=3):
    """Retry a failed payment up to max_retries times."""
    if order_id not in payment_attempts:
        payment_attempts[order_id] = 0

    while payment_attempts[order_id] < max_retries:
        success = charge_fn(order_id)
        if success:
            del payment_attempts[order_id]
            return True
        payment_attempts[order_id] += 1
    return False
'''

PROMPT = (
    "Two worker threads can call retry_payment() with the same order_id "
    "at the same time. Identify the concurrency bug that can double-charge "
    "a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)

for level in ["low", "medium", "high"]:
    start = time.perf_counter()
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=PROMPT,
        generation_config={"thinking_level": level},
    )
    elapsed = time.perf_counter() - start
    usage = interaction.usage
    print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
    print(interaction.output_text)
    print(
        f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
        f"thinking={usage.total_thought_tokens}"
    )

参考として、脆弱性はpayment_attempts[order_id]に対する非アトミックな「チェックしてから実行」です。同時実行下で、2つのスレッドが両方ともwhile条件を通過し、どちらもカウンタを増やす前にcharge_fn()を呼び得ます。修正は、読み取り→チェック→課金→インクリメントの流れを注文ごとのロックで包むか、ゲートウェイで冪等性キーを使うことです。

結果の比較

筆者の実行結果：

3つのレベルすべてが二重課金を発見し、いずれも注文ごとのロックを導入したため、無関係な注文は並行して処理できます。3.7と比較すると、ここが見出し級の違いです。3.7ではlowがネットワーク呼び出し中も保持されるグローバルロックで全体を包み、注文ごとのロックはmediumからでした。3.8ではlowが推論トークン0、7.8秒、1/3セント未満でより良い設計を書きます。

ではレベル差が今何をもたらすのか。監査の深さです。このコードには4つの独立した失敗モード（ダブルチャージ、同時削除時のKeyError、成功経路で状態削除後の再課金、非アトミックなカウンタ増分）があり、すべてを挙げたのはhighだけでした。lowは再課金ケースを、mediumはカウンタを見落としました。

highは、修正の失敗経路のセマンティクス（再試行枠を使い切った後は、再課金せずFalseを返す）も唯一明確化しました。

推論トークン列は、Googleの「3.8はより頑張る」主張がターミナルに現れたものです。同一プロンプトに対し、3.7のmediumは2,343→3,158、highは2,217→4,512と概ね倍増し、追加トークンは結論を変えるのではなく分析の完全性を高めました。レイテンシは本実行では比例して増えました（7.8s、16.6s、25.5s）。ただし単発計測はぶれるため、秒数よりトークン数で比較してください。

デフォルトの選択とエスカレーションの基準

筆者の目安は次のとおりです。

• 3.8ではlowの役割がGoogleのmedium推奨より大きいと感じました。推論トークン0で正しく設計の良い修正を出すため、人が読む前提のもの（トリアージ、下書き、要約、レビュー前提のコード）ではここから始めてください。

• mediumは出力が未読で出荷される場合に維持します。追加の推論で失敗モード分析がより完全になり、未読のパイプラインでは列挙漏れの失敗モードこそが発火します。

• highは失敗経路自体がプロダクト価値となる場面（決済フロー、移行、行単位で監査する作業）に限定します。今回の実行では、4つすべてのバグを捉え、再試行枠切れ後の挙動も文書化したのはhighだけでした。

highはlowの約6.6倍のコストです。これは導入価格（出力100万あたり$3.75）の今と、2026年12月31日以降の$7.50では印象が大きく変わるため、グローバルにではなくリクエスト単位でエスカレーションしてください。

なお、Googleは3.7 Flashが効率重視のワークロード向けに引き続き完全サポートであると明言しています。3.8の追加の丁寧さがタスクに対して過剰コストなら、そのワークロードではgemini-3.7-flashを使い続けるのはハックではなくサポートされた選択です。

PDFから構造化データをどう抽出するか？

Gemini 3.8 FlashはPDFを直接入力として読み取れるため、請求書やレポートを送って質問できます。ここでは、請求書番号、日付、4つの明細、合計を含む1ページのベンダー請求書を使用しました。

プロンプトにPDFを添付する

Files APIを使ってローカルの請求書PDFをアップロードします。Files APIはGoogleのインフラ上でのファイル保存とキャッシュを扱います。

	from google import genai
	client = genai.Client()
	print("Uploading invoice...")
	doc = client.files.upload(file="invoice_aug_2026.pdf")
	print(f"File uploaded: {doc.uri}\n")

	interaction = client.interactions.create(
	   model="gemini-3.8-flash",
	   input=[
	       {
	           "type": "text",
	           "text": "Extract the invoice number, total amount due, and due date.",
	       },
	       {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
	   ],
	)
	print(interaction.output_text)

筆者の請求書での出力：

3つの値はいずれも正解でした。アップロードは1回で、同じ文書に複数回質問する際にもファイルは再利用できます。回答はMarkdownの箇条書きで返ります。人が読むには良いですが、パイプライン投入には向きません。

レスポンススキーマでJSONを強制する

プローズではなくJSONを得るには、response_formatでスキーマを渡します。Interactions APIではトップレベルのパラメータです。古いチュートリアルで見かけるgenerationConfig内のresponseMimeTypeは、レガシーのgenerateContentエンドポイント向けです。

import json

from google import genai
from pydantic import BaseModel

client = genai.Client()


class Invoice(BaseModel):
    invoice_number: str
    total_due_usd: float
    due_date: str  # ISO 8601


doc = client.files.upload(file="invoice_aug_2026.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "text",
            "text": "Extract the invoice number, total amount due in USD, and due date.",
        },
        {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Invoice.model_json_schema(),
    },
)

invoice = json.loads(interaction.output_text)
print(invoice)

筆者が受け取った出力は次のとおりです。

Pydanticクラスが必須フィールドとデータ型を定義し、model_json_schema()がGemini APIに必要なJSONスキーマを生成します。処理後、json.loads()でモデルの出力を標準のPython辞書に変換します。ここから先は、構造化データをDataFrame行へ変換したり、データベースへコミットしたり、Googleスプレッドシートに追加する準備が整います。

previous_interaction_idで追質問する

同一文書への2つ目の質問では、最初のインタラクションのidをprevious_interaction_idとして渡します。サーバーにはすでにPDFと最初のやり取りがあるため、どちらも再送不要です。

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input="List each line item on the invoice with its amount.",
)

print(follow_up.output_text)

繰り返しのcompute行を含め、順序どおりに4項目すべてが返りました。質問に対しては正しい挙動です。異常の指摘が欲しければ、そう依頼してください。

ちなみに、ここは3.7でも同様の挙動でした。つまり3.8の追加の丁寧さはモデル自身の推論に適用され、頼んでいない監査を勝手に行うわけではありません。

この呼び出しについて知っておくべき点が2つあります。

• response_formatはインタラクション単位なので引き継がれず、このターンはプローズで返りました。

• インタラクションはデフォルトで保存されます（有料ティアで55日、無料ティアで1日、store=True）。store=Falseにするとステートレスになりますが、その場合はprevious_interaction_idで連鎖できません。

Gemini 3.8 Flashに関数呼び出しをどう追加するか？

Gemini 3.8 Flashの関数呼び出しは1つのループです。モデルがツールを要求し、コードがそれを実行し、結果を返すと、モデルが最終回答を書きます。この節では、そのループを手作業で構築します。

Googleにホスト型のマルチツールエージェントでループを回してもらいたい場合は、次にGemini APIの「Managed Agents」チュートリアルをお読みください。長期的にエージェントを目指すなら、Building AI Agents with Google ADKコースで、同じ基盤機能を使ったカスタマーサポートアシスタントの構築を学べます。

ツールを定義し、インタラクションループを実行

ツールはlookup_exchange_rate(currency, date)で、外部API不要のように小さなインメモリdictで裏打ちします。宣言はJSONスキーマです。モデルが関数を実行することはなく、function_callステップを返し、次の処理をコードに依頼します。

import json

from google import genai

client = genai.Client()

# Local "data source" standing in for a real FX API
RATES = {
    ("USD", "2026-08-03"): 87.42,
    ("USD", "2026-08-10"): 87.15,
    ("EUR", "2026-08-03"): 95.08,
}


def lookup_exchange_rate(currency: str, date: str) -> dict:
    rate = RATES.get((currency.upper(), date))
    if rate is None:
        return {"error": f"No rate for {currency} on {date}"}
    return {"currency": currency.upper(), "date": date, "inr_rate": rate}


rate_tool = {
    "type": "function",
    "name": "lookup_exchange_rate",
    "description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
    "parameters": {
        "type": "object",
        "properties": {
            "currency": {"type": "string", "description": "ISO code, e.g. USD"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["currency", "date"],
    },
}

# Turn 1: the model decides to call the tool
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What was the USD to INR exchange rate on 2026-08-03?",
    tools=[rate_tool],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")

# Your code executes the function locally
result = lookup_exchange_rate(**fc_step.arguments)

# Turn 2: send the result back; tools must be re-specified (interaction-scoped)
final = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[rate_tool],
)

print(final.output_text)

出力：

ここで3つのことが起きました。

1. ターン1でfunction_callステップ（名前、構造化引数、id付き）が返りました。

2. Python側でルックアップを実行しました。

3. ターン2で、その呼び出しを参照するfunction_resultブロックを送信しました。

toolsをターン2でも再指定しているのは、PDF節でresponse_formatを再指定したのと同じ理由です。previous_interaction_idが運ぶのは履歴であって設定ではないためです。

Gemini 3.xでの関数呼び出しの落とし穴

ツールループが壊れる原因のほとんどは2つのどちらかです。

第一に、すべての結果はその呼び出しにマッピングされる必要があります。Interactions APIでは、function_resultブロックのcall_idとnameです。レガシーのgenerateContent APIでは、FunctionResponseが直前のFunctionCallのidとnameに一致する必要があります。Gemini 3.xではどちらも必須です。

第二に、Malformed_Function_Callエラーは、モデルがツール呼び出しの前に解説文を出力したときによく発生します。Googleの3.8開発者ガイドでは、ツール前の余分なテキストを除去し、インラインの指示は\n\nで整形し、作業メモは生テキストではなく専用の関数呼び出しでラップするよう勧めています。システム指示を引き締め、やみくもなリトライは避けてください。

Gemini 3.8 Flashへ切り替えると何が壊れるか？

出発点によって異なります。

• Gemini 3.7 Flashから：何も壊れません。モデル文字列をgemini-3.8-flashに変えるだけで、本記事のスニペットはすべて無変更で動きます。APIの表面は同一です。

• Gemini 3.6 Flash以前から：モデル設定は以前と同様、15分程度の監査が必要です。

移行チェックリスト（3.6 Flash以前から）

順番に対応してください。1〜3は即時に400、4と5はサイレントな品質低下を招きます。

1. モデルIDをgemini-3.8-flashに変更。

2. 廃止されたサンプリングパラメータを削除：temperature、top_p、top_kはGemini 3.xで無視または拒否され、frequency_penalty、presence_penalty、candidate_countはアクティブなAPIエラーになります。6つすべてを除去。

3. thinking_budgetをthinking_levelに置換：有効なのはlow、medium、highのみ。旧minimalはバリデーションエラー。thinking_budgetとthinking_levelを同時送信すると400。

4. 事前入力されたモデルターンを削除：組み立てた会話から除去し、最終のユーザーターンに空でないテキストがあることを確認。履歴ペイロードはモデルターンで終われません。

5. マルチターンを標準化：クライアント側の履歴リプレイではなくprevious_interaction_idに依拠。必要なターンではtools、system_instruction、generation_configを毎回再指定。

Googleは、Gemini APIモデルドキュメントに公式情報を掲載しており、エージェントがスキルをサポートしている場合の自動移行パスもあります。とはいえ一度は自分で読みましょう。自動移行は、そもそもtemperature=0.2にした理由までは教えてくれません。

本番で遭遇するエラー

このAPIでハンドラ実装の価値が高いステータスコードは4つ。典型的な原因と対処は以下のとおりです。

さらに2つ：

• thinking_level: "high"と長いツールループの組み合わせでは、明示的なクライアントタイムアウトを設定してください。ハングしたリクエストは失敗より悪く、3.8の追加の丁寧さは長時間の推論をむしろ起こしやすくします。

• 各リクエストでinteraction.idをログに残してください。保存されたインタラクションの取得・デバッグ・削除のハンドルになります。

まとめ

本記事の要点は3つの変化に帰着します。Interactions APIが呼び出し規約を変え、thinking_levelがこれまで調整していたサンプリングノブを置き換え、サーバーサイド状態（previous_interaction_id）がPDFの追質問やツールループを履歴リプレイではない1ターンにしました。Gemini 3.8 Flashはこれらの表面を変えていません。内部でどれだけ頑張るかを変えたのです。だからこそ、測定値は3.7からの持ち回りではなく3.8で取り直しました。

筆者のレベル推奨を鵜呑みにせず、比較スクリプトを自分のバックログのタスクに当ててください。決済再試行のレースで勝つレベルが、SQL生成ワークロードでは負けるかもしれません。

単発のAPI呼び出しを超えて、本格的なAIシステムを構築したい場合は、Associate AI Engineer for Developersトラックで全体像を、Associate AI Engineer for Data Scientistsトラックでデータ側からの道筋を学べます。