Gemini 2.5 Flash で thinking_level not supported エラーが発生する3つの根本原因

gemini-2.5-flash を呼び出す際に Thinking level is not supported for this model というエラーに遭遇した一方で、gemini-3-flash-preview に切り替えると正常に動作したことはありませんか？これは、Google Gemini API がモデルの世代交代に伴って導入したパラメータ設計の変更によるものです。本記事では、Gemini 2.5 と 3.0 における思考モードパラメータのサポートに関する根本的な違いを体系的に解説します。

コアバリュー: 本記事を読むことで、Gemini 2.5 および 3.0 シリーズにおける思考モードパラメータ設計の本質的な違いを理解し、正しいパラメータ設定方法をマスターすることで、パラメータの混用による API 呼び出しの失敗を回避できるようになります。

Gemini 思考モード パラメータ進化の要点

Gemini 2.5 vs 3.0 思考モードパラメータ設計の違い

主な違い: Gemini 2.5 シリーズは thinking_budget (トークン予算制) を使用し、Gemini 3.0 シリーズは thinking_level (意味論的なレベル制) を使用します。これら 2 つのパラメータは完全に互換性がなく、誤ったモデルバージョンで使用すると 400 Bad Request エラーが発生します。

Google が Gemini 3.0 で thinking_level を導入した主な理由は、設定の複雑さを簡素化し、推論効率を向上させることです。Gemini 2.5 のトークン予算制では、開発者が思考トークン数を正確に見積もる必要がありましたが、Gemini 3.0 のレベル制では、この複雑さを 4 つの意味論的なレベルに抽象化しました。モデル内部で最適なトークン予算が自動的に割り当てられるようになり、推論速度が 2 倍に向上しています。

💡 技術的なアドバイス: 実際の開発では、APIYI (apiyi.com) プラットフォームを通じてモデルの切り替えテストを行うことをお勧めします。このプラットフォームは統一された API インターフェースを提供しており、Gemini 2.5 および 3.0 の全シリーズをサポートしているため、異なる思考モードパラメータの互換性や実際の効果を素早く検証するのに便利です。

根本原因1：Gemini 2.5シリーズはthinking_levelパラメータをサポートしていない

APIパラメータ設計における世代間の断絶

Gemini 2.5シリーズのモデル（Pro、Flash、Flash-Liteを含む）は、API設計においてthinking_levelパラメータを一切認識しません。gemini-2.5-flashを呼び出す際にthinking_levelパラメータを渡すと、APIは以下のエラーを返します。

{
  "error": {
    "message": "Thinking level is not supported for this model.",
    "type": "upstream_error",
    "code": 400
  }
}

エラー発生のメカニズム:

• Gemini 2.5モデルのAPI検証レイヤーには、thinking_levelパラメータの定義が含まれていません。
• thinking_levelを含むリクエストは直ちに拒否され、thinking_budgetへのマッピングも試行されません。
• これはハードコードされたパラメータの分離であり、自動変換や後方互換性は存在しません。

Gemini 2.5シリーズの正しいパラメータ：thinking_budget

Gemini 2.5 Flashのパラメータ仕様:

# 正しい設定例
extra_body = {
    "thinking_budget": -1  # 動的思考モード
}

# または思考を無効化
extra_body = {
    "thinking_budget": 0  # 完全に無効
}

# または精密に制御
extra_body = {
    "thinking_budget": 2048  # 正確に 2048 トークンの予算
}

Gemini 2.5 Flashにおけるthinking_budgetの値の範囲:

🎯 選定のアドバイス: Gemini 2.5 Flashに切り替える際は、まずAPIYI (apiyi.com) プラットフォームを利用して、thinking_budgetの異なる値がレスポンスの質やレイテンシに与える影響をテストすることをお勧めします。このプラットフォームではパラメータ設定を素早く切り替えられるため、ビジネスシーンに最適な予算値を簡単に見つけることができます。

根本原因2：Gemini 3.0シリーズはthinking_budgetパラメータをサポートしていない

パラメータ設計の前方不整合

Googleの公式ドキュメントでは、Gemini 3.0は後方互換性のために引き続きthinking_budgetパラメータを受け入れるとされていますが、実際のテストでは以下のことが判明しています。

• thinking_budgetを使用するとパフォーマンスが低下する場合がある
• 公式ドキュメントではthinking_levelの使用が明示的に推奨されている
• 一部のAPI実装ではthinking_budgetを完全に拒否する場合がある

Gemini 3.0 Flashの正しいパラメータ：thinking_level

# 正しい設定例
extra_body = {
    "thinking_level": "medium"  # 中程度の推論強度
}

# または最小限の思考 (無効に近い状態)
extra_body = {
    "thinking_level": "minimal"  # 最小思考モード
}

# または高強度の推論 (デフォルト)
extra_body = {
    "thinking_level": "high"  # 深い推論
}

Gemini 3.0 Flashにおけるthinking_levelのレベル説明:

Gemini 3.0 Proの特別な制限

重要: Gemini 3.0 Proは思考モードを完全に無効化することはできません。thinking_level: "low"に設定しても、一定の推論能力が保持されます。最高速度を得るために思考をゼロにしたレスポンスが必要な場合は、Gemini 2.5 Flashでthinking_budget: 0を使用するしかありません。

# Gemini 3.0 Pro で利用可能なレベル (2種類のみ)
extra_body = {
    "thinking_level": "low"   # 最低レベル (推論は行われる)
}

# または
extra_body = {
    "thinking_level": "high"  # デフォルトの高強度推論
}

💰 コスト最適化: 予算に敏感なプロジェクトで、コストを抑えるために思考モードを完全に無効化する必要がある場合は、APIYI (apiyi.com) プラットフォーム経由でGemini 2.5 Flash APIを呼び出すことを検討してください。柔軟な課金体系とよりお得な価格設定により、正確なコスト管理が必要なシーンに最適です。

根本原因 3: 画像モデルと特殊バリアントにおけるパラメータの制限

Gemini 2.5 Flash Image モデルは思考モード非対応

重要な発見: gemini-2.5-flash-image などのビジョンモデルは、thinking_budget や thinking_level を問わず、思考モードのパラメータに一切対応していません。

エラー例:

# 调用 gemini-2.5-flash-image 时
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{"role": "user", "content": "分析这张图片"}],
    extra_body={
        "thinking_budget": -1  # ❌ 错误: 图像模型不支持
    }
)
# 返回错误: "This model doesn't support thinking"

正しい方法:

# 调用图像模型时,不传递任何思考参数
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{"role": "user", "content": "分析这张图片"}],
    # ✅ 不传递 thinking_budget 或 thinking_level
)

Gemini 2.5 Flash-Lite の特殊なデフォルト値

Gemini 2.5 Flash-Lite と標準 Flash バージョンの主な違いは以下の通りです:

• 思考モードがデフォルトで無効 (thinking_budget: 0)
• 思考を有効にするには、thinking_budget にゼロ以外の値を明示的に設定する必要がある
• サポートされている予算範囲: 512〜24576 トークン

# Gemini 2.5 Flash-Lite 启用思考模式
extra_body = {
    "thinking_budget": 512  # 最小非零值,启用轻量思考
}

🚀 クイックスタート: APIYI (apiyi.com) プラットフォームを使用して、さまざまなモデルの思考パラメータの互換性をすばやくテストすることをお勧めします。このプラットフォームは、Gemini シリーズ全モデルのインターフェースをすぐに利用できる状態で提供しており、複雑な設定なしで、わずか 5 分で統合とパラメータの検証を完了できます。

ソリューション 1: モデルバージョンに基づいたパラメータ適応関数

スマートパラメータセレクター（全シリーズのモデルをサポート）

def get_gemini_thinking_config(model_name: str, intensity: str = "medium") -> dict:
    """
    Geminiモデル名に基づいて、適切な思考モードパラメータを自動的に選択します

    Args:
        model_name: Gemini モデル名
        intensity: 思考の強度 ("none", "minimal", "low", "medium", "high", "dynamic")

    Returns:
        extra_body に適用するパラメータ辞書。モデルが思考モードに対応していない場合は空の辞書を返します
    """

    # Gemini 3.0 モデルリスト
    gemini_3_models = [
        "gemini-3.0-flash-preview", "gemini-3.0-pro-preview",
        "gemini-3-flash", "gemini-3-pro"
    ]

    # Gemini 2.5 標準モデルリスト
    gemini_2_5_models = [
        "gemini-2.5-flash", "gemini-2.5-pro",
        "gemini-2.5-flash-lite", "gemini-2-flash", "gemini-2-pro"
    ]

    # 画像モデルリスト（思考モード非対応）
    image_models = [
        "gemini-2.5-flash-image", "gemini-flash-image",
        "gemini-pro-vision"
    ]

    # 画像モデルかどうかを確認
    if any(img_model in model_name for img_model in image_models):
        print(f"⚠️ 警告: {model_name} は思考モードパラメータに対応していません。空の設定を返します")
        return {}

    # Gemini 3.0 シリーズは thinking_level を使用
    if any(m in model_name for m in gemini_3_models):
        level_map = {
            "none": "minimal",      # 3.0 は完全に無効化できないため、minimal を使用
            "minimal": "minimal",
            "low": "low",
            "medium": "medium",
            "high": "high",
            "dynamic": "high"
        }

        # Gemini 3.0 Pro は low と high のみをサポート
        if "pro" in model_name.lower():
            if intensity in ["none", "minimal", "low"]:
                return {"thinking_level": "low"}
            else:
                return {"thinking_level": "high"}

        # Gemini 3.0 Flash は全4段階をサポート
        return {"thinking_level": level_map.get(intensity, "medium")}

    # Gemini 2.5 シリーズは thinking_budget を使用
    elif any(m in model_name for m in gemini_2_5_models):
        budget_map = {
            "none": 0,           # 完全に無効化
            "minimal": 512,      # 最小予算
            "low": 2048,         # 低強度
            "medium": 8192,      # 中等強度
            "high": 16384,       # 高強度
            "dynamic": -1        # 動的適応
        }

        budget = budget_map.get(intensity, -1)

        # Gemini 2.5 Pro は無効化をサポートしていません（最小 128）
        if "pro" in model_name.lower() and budget == 0:
            print(f"⚠️ 警告: {model_name} は思考モードの無効化をサポートしていません。自動的に最小値 128 に調整します")
            budget = 128

        # Gemini 2.5 Flash-Lite の最小値は 512
        if "lite" in model_name.lower() and budget > 0 and budget < 512:
            print(f"⚠️ 警告: {model_name} の最小予算は 512 です。自動調整します")
            budget = 512

        return {"thinking_budget": budget}

    else:
        print(f"⚠️ 警告: 不明なモデル {model_name} です。デフォルトで Gemini 3.0 のパラメータを使用します")
        return {"thinking_level": "medium"}


# 使用例
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

# Gemini 2.5 Flash のテスト
model_2_5 = "gemini-2.5-flash"
config_2_5 = get_gemini_thinking_config(model_2_5, intensity="dynamic")
print(f"{model_2_5} 設定: {config_2_5}")
# 出力: gemini-2.5-flash 設定: {'thinking_budget': -1}

response_2_5 = client.chat.completions.create(
    model=model_2_5,
    messages=[{"role": "user", "content": "量子もつれについて説明して"}],
    extra_body=config_2_5
)

# Gemini 3.0 Flash のテスト
model_3_0 = "gemini-3.0-flash-preview"
config_3_0 = get_gemini_thinking_config(model_3_0, intensity="medium")
print(f"{model_3_0} 設定: {config_3_0}")
# 出力: gemini-3.0-flash-preview 設定: {'thinking_level': 'medium'}

response_3_0 = client.chat.completions.create(
    model=model_3_0,
    messages=[{"role": "user", "content": "量子もつれについて説明して"}],
    extra_body=config_3_0
)

# 画像モデルのテスト
model_image = "gemini-2.5-flash-image"
config_image = get_gemini_thinking_config(model_image, intensity="high")
print(f"{model_image} 設定: {config_image}")
# 出力: ⚠️ 警告: gemini-2.5-flash-image は思考モードパラメータに対応していません。空の設定を返します
# 出力: gemini-2.5-flash-image 設定: {}

💡 ベストプラクティス: Gemini モデルを動的に切り替える必要があるシナリオでは、APIYI (apiyi.com) プラットフォームを利用してパラメータの適応テストを行うことをお勧めします。このプラットフォームは Gemini 2.5 および 3.0 シリーズの全モデルをサポートしており、異なるパラメータ設定におけるレスポンスの質やコストの差を簡単に検証できます。

ソリューション 2: Gemini 2.5 から 3.0 への移行戦略

思考モードパラメータの移行対応表

移行コードの例

def migrate_to_gemini_3(old_model: str, old_config: dict) -> tuple[str, dict]:
    """
    Gemini 2.5 から Gemini 3.0 へ移行します

    Args:
        old_model: Gemini 2.5 モデル名
        old_config: Gemini 2.5 の extra_body 設定

    Returns:
        (新しいモデル名, 新しい設定辞書)
    """
    # モデル名のマッピング
    model_map = {
        "gemini-2.5-flash": "gemini-3.0-flash-preview",
        "gemini-2.5-pro": "gemini-3.0-pro-preview",
        "gemini-2-flash": "gemini-3-flash",
        "gemini-2-pro": "gemini-3-pro"
    }

    new_model = model_map.get(old_model, "gemini-3.0-flash-preview")

    # パラメータの変換
    if "thinking_budget" in old_config:
        budget = old_config["thinking_budget"]

        # thinking_level へ変換
        if budget == 0:
            new_level = "minimal"
        elif budget <= 2048:
            new_level = "low"
        elif budget <= 8192:
            new_level = "medium"
        else:
            new_level = "high"

        # Gemini 3.0 Pro は low/high のみをサポート
        if "pro" in new_model and new_level in ["minimal", "medium"]:
            new_level = "low" if new_level == "minimal" else "high"

        new_config = {"thinking_level": new_level}
    else:
        # デフォルト設定
        new_config = {"thinking_level": "medium"}

    return new_model, new_config


# 移行の例
old_model = "gemini-2.5-flash"
old_config = {"thinking_budget": -1}

new_model, new_config = migrate_to_gemini_3(old_model, old_config)
print(f"移行前: {old_model} {old_config}")
print(f"移行後: {new_model} {new_config}")
# 出力:
# 移行前: gemini-2.5-flash {'thinking_budget': -1}
# 移行後: gemini-3.0-flash-preview {'thinking_level': 'high'}

# 新しい設定で呼び出し
response = client.chat.completions.create(
    model=new_model,
    messages=[{"role": "user", "content": "あなたの質問"}],
    extra_body=new_config
)

🎯 移行のアドバイス: Gemini 2.5 から 3.0 へ移行する際は、まず APIYI (apiyi.com) プラットフォームで A/B テストを行うことをお勧めします。このプラットフォームではモデルのバージョンを素早く切り替えられるため、移行前後のレスポンス品質、レイテンシ、コストの差を比較しやすく、スムーズな移行を実現できます。

よくある質問

# エラーコード (3.0 専用)
extra_body = {
    "thinking_level": "medium"  # ❌ 2.5 は認識しません
}

# 正しいコード (2.5 用)
extra_body = {
    "thinking_budget": 8192  # ✅ 2.5 は budget を使用します
}

# Gemini 2.5 Flash のみが完全な無効化をサポートしています
model = "gemini-2.5-flash"
extra_body = {
    "thinking_budget": 0  # 思考を完全に無効化
}

# ❌ 画像モデルは思考パラメータを一切サポートしていません
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[...],
    extra_body={
        "thinking_budget": -1  # エラーが発生します
    }
)

# ✅ 画像モデルを呼び出す際は思考パラメータを渡さない
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[...],
    # extra_body を渡さない、または思考以外のパラメータを渡す
)

まとめ

Gemini 2.5 Flash で thinking_level not supported というエラーが出る際の核心的なポイント：

1. パラメータの分離: Gemini 2.5 は thinking_budget のみ、3.0 は thinking_level のみをサポートしており、両者に互換性はありません。
2. モデルの識別: モデル名でバージョンを判断し、2.5 シリーズなら thinking_budget、3.0 シリーズなら thinking_level を使用してください。
3. 画像モデルの制限: すべての画像モデル（gemini-2.5-flash-image など）は思考モードパラメータをサポートしていません。
4. 無効化の違い: Gemini 2.5 Flash のみが思考の完全な無効化 (thinking_budget: 0) をサポートしています。3.0 シリーズは最小でも minimal までです。
5. 移行戦略: 2.5 から 3.0 へ移行する際は、thinking_budget を thinking_level にマッピングし、パフォーマンスとコストの変化を考慮する必要があります。

APIYI apiyi.com を利用して、異なるモデルの思考パラメータの互換性や実際の効果を素早く検証することをお勧めします。このプラットフォームは Gemini の全シリーズに対応しており、統一されたインターフェースと柔軟な課金方式を提供しているため、迅速な比較テストや本番環境へのデプロイに適しています。

著者: APIYI 技術チーム | 技術的な質問がある場合は、APIYI apiyi.com にアクセスして、より多くの AI モデル導入ソリューションをご確認ください。