Googleは2026年9月2日にGemini 3.8 Flashをリリースしました。APIモデルIDは、プレビューサフィックスなしのプレーンな文字列gemini-3.8-flashです。これは2026年12月31日まで、3.7 Flashの導入価格である入力トークン100万あたり$0.75、出力トークン100万あたり$3.75を維持します。Googleはこれを「より熱心に働く」モデルと表現しており、複雑なタスクにおいてより多くの推論ステップを踏み、より頻繁にツールを呼び出すため、これがトークン請求に反映されます。
このガイドは、動作する統合への完全な道のりをカバーしています。AI Studioでのキーの取得、Interactions API（現在、Gemini 3.x向けのGoogleの主要API）を介した最初のリクエスト送信、既存のほとんどのコードが依然として使用しているレガシーなgenerateContentの同等機能、thinking_levelがそれぞれどこに配置されるか、ストリーミング、そして思考コストに驚かされることがないようthoughtsTokenCountを読み取る方法について説明します。すべての呼び出しはJSON形式のプレーンなHTTPであるため、アプリケーションコードに組み込む前に、Apidogでそれぞれを構築および確認できます。
モデルの概要、ベンチマーク、および変更点については、Gemini 3.8 Flashとは何かから始めてください。Googleの発表ブログ記事には公式見解が記載されています。
Gemini 3.8 Flash APIの概要
| 項目 | 値 |
|---|---|
| モデルID | gemini-3.8-flash |
| 主要エンドポイント | POST /v1beta/interactions |
| レガシーエンドポイント | POST /v1beta/models/gemini-3.8-flash:generateContent |
| 認証ヘッダー | x-goog-api-key |
| コンテキスト / 出力 | 1,048,576入力トークン / 65,536出力トークン |
| 入力 | テキスト、画像、動画、音声、PDF (テキスト出力のみ) |
| 思考レベル | low、medium (デフォルト)、high；minimalはエラーを返します |
| 価格 (2026年12月31日までの導入価格) | トークン100万あたり$0.75 / $3.75；2027年1月1日からは$1.50 / $7.50 |
コードを書き始める前に、2つの点が目につきます。デフォルトの思考レベルは、Gemini 3 Proのようにhighではなくmediumです。そして、思考トークンは公式料金ページに記載されている出力料金で課金されるため、選択するレベルは品質だけでなくコストの決定でもあります。料金の内訳では、タスクごとの数値について詳しく解説しています。
ステップ1: AI StudioでAPIキーを取得する
Google AI Studioを開き、Googleアカウントでサインインし、キーページからAPIキーを作成します。このキーは、レート制限付きで無料ティアで直ちに使用でき、Googleは無料ティアのデータが「製品の改善に使用される」と述べていることに注意してください。生産環境の制限のためにTier 1に移行するには、課金アカウントをリンクしてください。
キーをコードに貼り付ける代わりに、エクスポートしてください:
export GEMINI_API_KEY="AIza..."
公式Python SDKは環境からGEMINI_API_KEYを読み取るため、genai.Client()には引数は不要です。`pip install google-genai`でインストールしてください。
ステップ2: Interactions APIでの初回呼び出し
Googleは現在、Interactions APIをGemini 3.xモデルを呼び出す主要な方法として扱っています。リクエストは1つのJSONオブジェクトであり、モデル、input、およびthinking_levelが存在するオプションのgeneration_configで構成されます。
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.8-flash",
"input": "Explain HTTP caching in 3 sentences.",
"generation_config": {"thinking_level": "medium"}
}'
レスポンスは単一のメッセージではなく、実行ステップのリストです。モデルの思考やツール呼び出しはステップとして表示され、最終ステップはテキストを保持する`model_output`です。Pythonでは、SDKがこれを平坦化してくれます:
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Explain HTTP caching in 3 sentences.",
generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
temperature、top_p、top_kは除外してください。すべてのGemini 3モデルに対するGoogleのガイダンスは、`temperature`をデフォルトの1.0に保つことです。なぜなら、それを下げると「ループやパフォーマンスの低下を引き起こす可能性がある」からです。古いモデルから設定をコピーした場合、それが最初に削除すべき行です。
ステップ3: previous_interaction_idを使用した複数ターン
Interactions APIは、デフォルトで会話の状態をサーバーに保持します。会話を継続するには、新しいユーザー入力のみと共に、前のレスポンスの`id`を`previous_interaction_id`として送信します。履歴を再送信する必要はありません。
follow_up = client.interactions.create(
model="gemini-3.8-flash",
input="Now give one example of a Cache-Control header.",
previous_interaction_id=interaction.id,
)
print(follow_up.output_text)
コンプライアンスルールによりサーバーサイドストレージが禁止されている場合は、`store: false`を設定してください。そのトレードオフとして、モデルの思考ブロックと思考シグネチャを、受け取ったとおりに各ターンで正確に送り返すなど、状態管理を自分で行う必要があります。これは、ツール使用で問題となる同じルールであり、3.8 Flashの関数呼び出しガイドで説明されています。
ステップ4: レガシーなgenerateContentパス
本番環境のほとんどのGeminiコードは、いまだに`generateContent`を呼び出しています。Googleはこれをレガシーと呼んでいますが、廃止日はなく「完全にサポートされ続けている」ため、今日中に何かを書き直す必要はありません。私たちのGemini 3.7 Flash APIガイドではこのパスのみを扱っていましたが、3.8 Flashでも形式は同じであり、思考設定はInteractionsとは異なる場所にあります。
`generateContent`では、レベルは`generationConfig.thinkingConfig.thinkingLevel`の下にcamelCaseで配置されます:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Explain HTTP caching in 3 sentences."}]}],
"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
}'
Pythonの同等機能では、型付き設定オブジェクトを使用します:
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="Explain HTTP caching in 3 sentences.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level="low")
),
)
print(response.text)
`thinking_budget`を整数として使用していた設定から移行する場合は、それを文字列の列挙型に置き換えてください。`candidate_count`もGemini 3以降では削除されています。変更前後のJSONを含む完全なチェックリストは、3.7から3.8 Flashへの移行ガイドにあります。
ここに同じ懸念事項が並べて示されているため、両方のドキュメントを読み直すことなく、2つのAPI間で変換できます:
| 懸念事項 | Interactions API | レガシーなgenerateContent |
|---|---|---|
| 思考レベル | generation_config.thinking_level |
generationConfig.thinkingConfig.thinkingLevel |
| 会話状態 | previous_interaction_id (サーバーサイド) |
contents配列全体を再送信 |
| ツール結果 | call_id + nameを含むfunction_result |
id + nameを含むfunctionResponse (同じ値だがフィールド名が異なる) |
| 最終テキスト | model_outputステップ (SDKではoutput_text) |
candidates[0].content.parts[].text |
| 思考シグネチャ | store: falseでない限り自動で処理されます |
受け取った各パーツをそのまま返送 |
ステップ5: ストリーミングと思考コストの読み取り
チャットインターフェースの場合、メソッド名を`streamGenerateContent`に置き換え、`?alt=sse`を追加してサーバー送信イベント（各イベントごとに部分的な`candidates`チャンクが1つ）を取得します:
curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"parts":[{"text":"List three HTTP caching headers."}]}]}'
ストリーミングの有無にかかわらず、すべての`generateContent`レスポンスは`usageMetadata`オブジェクトで終了します。各呼び出しでこれを読み取ってください:
"usageMetadata": {
"promptTokenCount": 12,
"candidatesTokenCount": 84,
"thoughtsTokenCount": 310,
"totalTokenCount": 406
}
`thoughtsTokenCount`は3.8 Flashで注目すべき数値です。思考トークンは、導入期間中、100万トークンあたり$3.75で出力トークンとして課金され、Googleは「モデルはパフォーマンスを最大化するために、特に高い努力レベルではより多くのトークンを使用する可能性がある」と述べています。Artificial Analysisは、`high`でのインデックス実行において、タスクあたり約48kの出力トークンを測定しました。これは3.7 Flashより30%多く、トークンあたりの価格が変化しないまま、タスクあたりのコストを$0.40から$0.58に押し上げました。彼らの`medium`と`low`での実行は、タスクあたり$0.41と$0.24でした。思考レベルガイドは、これらの数値をルートごとの戦略に変換します。
モデルがどのように推論したかを確認するには、`thinkingConfig`内に`"includeThoughts": true`を追加します。思考の要約は`"thought": true`とフラグ付けされたパーツとして返されます。表示される回答を組み立てる際には、これらをスキップしてください。
最初の1時間で遭遇するであろうエラー
**`thinking_level: "minimal"`はバリデーションに失敗します。** Gemini 3.8 Flashは`low`、`medium`、`high`のみをサポートしています。`minimal`を送信すると、「Thinking level MINIMAL is not supported for this model. Please retry with other thinking level.（このモデルでは思考レベルMINIMALはサポートされていません。別の思考レベルで再試行してください。）」というメッセージと共に`400 INVALID_ARGUMENT`が返されます（2026年9月3日のライブコールで確認済み）。解決策は`low`への一語変更です。古い3.xの設定やコピーされたスニペットが一般的な原因です。
**429エラーは、バグではなくティアの制限に達したことを意味します。** レート制限ページにはティアが説明されています: 無料ティアはレート制限があり、Tier 1は課金アカウントをリンクすると解除され、Tier 2は$100の利用実績と3日間の期間が必要、Tier 3は$1,000の利用実績と30日間の期間が必要です。モデルごとの1分あたりのリクエスト数とトークン数は、AI Studioのあなたのアカウントのレート制限ページにのみ表示されるため、ブログ記事の数値を信頼するのではなく、そちらで確認してください。429エラーが発生した場合は、しばらく待ってから再試行してください。低ボリュームで繰り返し429エラーが発生する場合は、ティアをアップグレードしてください。オフラインジョブには、Batch APIがより良い解決策です。これは50%オフ（導入期間中は100万トークンあたり$0.375 / $1.875）で実行され、Tier 1で3M、Tier 2で400M、Tier 3で1Bのキューに入れられたトークン制限があります。Geminiバッチモードガイドには、リクエストの形式が示されています。
**関数結果における`call_id`の欠落。** ツールを使用する場合、3.8 Flashでは、すべての`function_result` (Interactions) が`call_id`と`name`の両方を保持する必要があり、すべてのレガシー`functionResponse`が対応する`id`と`name`を保持する必要があります。どちらかを省略すると、ターンが失敗します。
Apidogで両方のエンドポイントを出荷前にテストする
両方のリクエストがターミナルから動作することを確認したら、チーム全体が実行できる場所に移動します。Apidogをダウンロードし、プロジェクトを作成して、上記の2つのエンドポイントを保存されたリクエストとして追加します。以下の4つの習慣が効果を発揮します:
- **キーをリクエストから分離する。** `GEMINI_API_KEY`を環境変数として追加し、`x-goog-api-key`ヘッダーで`{{GEMINI_API_KEY}}`として参照します。保存されたリクエストには決してシークレットを含めず、無料ティアのキーと課金キーの切り替えは1つの環境変数変更で済みます。
- **ステータスとトークン使用量をアサートする。** ステータスが200であることをアサートし、次に`usageMetadata.thoughtsTokenCount`がプロンプトごとに選択した上限を下回っていることをJSONパスでアサートします。その上限はコスト回帰アラームとなります。プロンプトの更新やサイレントなモデル変更によって思考トークンが増加した場合、請求書が届く前にテストが失敗します。SSEテストガイドではストリーミングバリアントを扱っており、Apidogはこれを生のチャンクではなくマージされたイベントストリームとしてレンダリングします。
- **同じプロンプトを3つのレベルすべてで送信する。** `low`、`medium`、`high`でリクエストを複製し、`thoughtsTokenCount`と応答時間を並べて比較します。これにより、インデックスの平均値ではなく、自身のプロンプトに対する実際の数値が得られます。
- **スケジュールを設定する。** リクエストをテストシナリオに変換し、スケジュールに従って実行することで、レート制限の変更、`minimal`の削除のようなバリデーションの変更、またはトークンの急増が本番環境ではなくレポートに表示されるようになります。ApidogでAPIテストをスケジュールする方法でセットアップを順を追って説明しています。
Apidogはモデルを実行したり、SDKを置き換えたりするものではありません。それは、ほとんどのチームが何かが壊れるまでスキップする部分であるHTTP呼び出しの、保存可能で共有可能でアサート可能なバージョンを提供します。
よくある質問 (FAQ)
**新しいプロジェクトではどのエンドポイントを使用すべきですか？** Interactions APIです。Googleは`generateContent`をレガシーと呼んでおり、引き続き完全にサポートされていますが、新機能はまずInteractionsに実装され、サーバーサイドの状態管理により複数ターンのコードが短くなります。移行する理由ができるまでは、既存のサービスには`generateContent`を使用し続けてください。
**Gemini 3.8 Flashを呼び出すには有料アカウントが必要ですか？** いいえ。無料のAI Studioキーで動作し、レート制限とGoogleのデータ使用規約が適用されます。無料利用ガイドでは、無料ティアで何が可能で何が不可能か、Geminiアプリが3.8 FlashにAI ProまたはUltraプランを必要とすることを含め、詳細が記載されています。
**3.8 Flashは3.7 Flashよりも遅いですか？** トークンあたりでは、いいえ。GoogleのLogan Kilpatrick氏によると、ほぼ同じ速度であり、Artificial Analysisは1秒あたり約300の出力トークンを測定しました。タスクあたりでは、`high`の方が時間がかかります（彼らの実行では2.2分に対し2.5分）。これはより多くのトークンを生成するためです。
**Gemini 3.7 Flashを引き続き呼び出すことはできますか？** はい。Googleは3.7 Flashが「完全にサポートされ続けている」と述べており、廃止日は発表されていません。3.8 Flashでの追加トークン費用があなたのワークロードにおいて何のメリットももたらさない場合、現状維持は有効な選択肢です。
**3.8 FlashはLive APIや画像生成をサポートしていますか？** いいえ。テキスト出力のみです。このモデルでは、音声生成、画像生成、Live APIはサポートされていません。
次に進むべき場所
これで、2つの動作する呼び出しパス、複数ターンのパターン、およびトークン使用量チェックが手に入りました。ここからは、関数呼び出しガイドでツールを連携させ、思考レベルの投稿でルートごとのレベルを決定し、そもそも移行すべきかまだ悩んでいる場合は、3.8と3.7 Flashの比較でそのトレードオフが示されています。コストの変動がテストの失敗として現れるように、Apidogシナリオを実行し続けてください。