はじめに
Gemini 3のAPI一般提供にあわせて、応答前の推論の深さを4段階（minimal / low / medium / high）で指定できる thinking_level パラメータが追加されました。対象読者は、Gemini APIをすでに使っていて thinking_level への移行を検討しているエンジニアです。
公式ブログには「厳密なトークン保証ではなく相対的なガイドライン」としか書かれておらず、実際にどれだけ差が出るのか、そして手元の既存コードがそのまま動くのかは触ってみるまでわかりません。そこで4段階すべてを同一の質問で実行し、レイテンシとトークン消費を比較したうえで、手元にあった gemini-2.5-flash にも同じリクエストを投げて後方互換性を確認しました。
比較表（実測サマリー）
同一の複利計算問題（「月100万円が毎月8%増えると12月はいくらか」）を gemini-3-flash-preview に4段階で投げた結果です。
| thinking_level | レイテンシ | 思考トークン | 出力トークン | 合計トークン | 正答 |
|---|---|---|---|---|---|
minimal |
17.2秒 | 0（記録なし） | 448 | 486 | ○（233万1,639円） |
low |
19.6秒 | 642 | 607 | 1,287 | ○ |
medium |
24.2秒 | 965 | 481 | 1,484 | ○ |
high |
32.9秒 | 717 | 548 | 1,303 | ○ |
gemini-2.5-flash に同じ thinking_level 付きリクエストを投げると、以下のエラーで即座に弾かれました。
{
"error": {
"code": 400,
"message": "Thinking level is not supported for this model.",
"status": "INVALID_ARGUMENT"
}
}
thinking_levelとは何か
Google Developers Blogの発表によれば、thinking_level はモデルが応答前に行う推論の深さを制御するパラメータです。
Gemini 3はこれらのレベルを厳密なトークン保証ではなく、相対的なガイドラインとして扱う
出典: Gemini API updates for Gemini 3 | Google Developers Blog
公式ドキュメントでは4段階が以下のように説明されています（出典: Gemini 3 Developer Guide | Google AI for Developers）。
-
minimal: ほぼ思考なし。チャットやバッチ処理向け -
low: レイテンシとコストを最小化。シンプルな指示向け -
medium: バランス型の推論 -
high: 推論の深さを最大化。gemini-3.1-pro-previewとgemini-3-flash-preview（本記事の実測対象）ではデフォルト値（gemini-3.1-flash-liteのデフォルトはminimal）
対応モデルは gemini-3.1-pro-preview / gemini-3-flash-preview / gemini-3.1-flash-lite などGemini 3系のみで、gemini-2.5-flash を含む旧世代には存在しないパラメータです。
実測フロー
処理の流れは次のとおりです。同一の質問文を4段階の thinkingLevel で切り替えて generateContent に投げ、usageMetadata からトークン内訳を、time コマンドから所要時間を取得しました。
実際のリクエストは以下の形です（GEMINI_API_KEY は環境変数から取得）。
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [{"parts": [{"text": "（質問文）"}]}],
"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
}'
generationConfig.thinkingConfig.thinkingLevel に minimal / low / medium / high を指定するだけで、モデル名やエンドポイントの変更は不要でした。
結果の詳細
4段階すべてで正答（約233万1,639円）に到達しましたが、内訳には明確な差がありました。
-
minimalはusageMetadataにthoughtsTokenCountが現れず、実質的に思考トークンを消費していません。それでも今回の複利計算では正しい途中式を再現できており、レイテンシも4段階中最速（17.2秒）でした。 -
low→medium→highの順で思考トークンとレイテンシが増える傾向はありますが、トークン数自体は単調増加ではありませんでした（mediumの965が最大で、highは717）。公式が「厳密なトークン保証ではない」と明記している通り、レベルは思考量の上限指定ではなく傾向の指定に近い挙動です。 - レイテンシは
minimalの17.2秒からhighの32.9秒まで、約1.9倍の開きが出ました。
料金表（Gemini API Pricing）の gemini-3-flash-preview（入力$0.50/1M・出力$3/1M）で概算すると、思考トークンは出力側の単価で課金されるため、minimal は1リクエストあたり約$0.0014、high は約$0.0038と、同じ質問でも約2.7倍のコスト差になります。今回の問題は複利計算という比較的単純なタスクだったため、正答率では差が出ませんでしたが、コストとレイテンシには実測できる差が明確にありました。
旧モデルとの非互換
筆者が実際に手を動かして気づいたのは、thinking_level が完全に新規追加のパラメータであり、既存の gemini-2.5-flash 向けコードに generationConfig.thinkingConfig.thinkingLevel を足しただけでは動かないという点です。エラーメッセージは INVALID_ARGUMENT で、パラメータ名の誤りやクォータ超過とは異なる原因であることが明示されるため、切り分け自体は容易でした。ただし、モデルを gemini-3-flash-preview 等のGemini 3系に切り替えない限り、このパラメータは無視されるのではなく明確なエラーで弾かれる点は、移行時に見落としやすいポイントだと感じました。
また、gemini-3.1-pro-preview は無料枠（Free Tier）のクォータが0に設定されており、RESOURCE_EXHAUSTED エラーで即座に弾かれました。無料枠で試すなら gemini-3-flash-preview か gemini-3.1-flash-lite を使う必要があります。
まとめ
thinking_level はGemini 3系専用のパラメータで、旧世代モデルに追加しても動きません。4段階の実測では、単純なタスクでは正答率に差が出ない一方、レイテンシとコストには実測できる差（レイテンシ約1.9倍・概算コスト約2.7倍）がありました。レイテンシとコストを優先する用途では minimal から試し、複雑な多段推論が必要なタスクでのみ high に上げる、という使い分けが妥当そうです。
移行を検討している場合は、まずモデル名をGemini 3系に切り替えたうえで thinking_level を追加し、想定タスクでレイテンシとトークン消費を計測してから本番投入することをおすすめします。