Claude API で temperature が 400 になる理由と代替 — Opus 5 / Sonnet 5 で消えたパラメータ

2025 年に書いた Claude API のコードを model="claude-opus-5" や claude-sonnet-5 に変えると、最初に当たるのがこのエラーです。

400 invalid_request_error: temperature is not supported ...

何が起きているか

Claude Opus 4.7 以降（4.8、Opus 5、Fable 5 系）は、temperature、top_p、top_k を受け付けません。渡すと 400 です。Claude Sonnet 5 は少し緩く、非既定の値を渡すと 400、省略か既定値なら通ります。

Claude 3 系では「temperature と top_p の同時指定が不可」でしたが、いまは両方とも消すのが正解です。

なぜ消えたのか

現行モデルは adaptive thinking（課題に応じて考える量を自分で決める仕組み）を前提に設計されていて、サンプリング温度で出力分布をいじるより、プロンプトと effort で振る舞いを決める方向に API が整理されました。budget_tokens（固定予算の拡張思考）やアシスタント・プリフィルが同じ時期に消えたのも同じ理由です。

決定性が目的だった場合

temperature=0 に「同じ入力で同じ出力」を期待していたコードは多いですが、もともと同一出力は保証されていませんでした。安定させたいなら次の 2 つです。

1. output_config={"effort": "low"} で推論のゆらぎを減らす
2. 出力形式を具体的に指定する。JSON なら構造化出力で形を保証する

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    output_config={
        "effort": "low",
        "format": {"type": "json_schema", "schema": {
            "type": "object",
            "properties": {"label": {"type": "string", "enum": ["positive", "negative", "neutral"]}},
            "required": ["label"],
            "additionalProperties": False,
        }},
    },
    messages=[{"role": "user", "content": "次のレビューを分類して: ..."}],
)

分類ラベルの固定には enum を持つスキーマが一番確実です。

多様性が目的だった場合

文章の言い回しやデザインの振れ幅を temperature で出していた場合は、プロンプトで誘導します。

• 文章: "Vary your phrasing and structure across responses."
• デザイン: "Before building, propose 4 distinct visual directions tailored to this brief (bg hex / accent hex / typeface, one-line rationale). Ask the user to pick one, then implement only that direction."

デザインについては、「クリーム色を使うな」のような否定の指示は別の固定パレットに移るだけで多様性は出ない、と公式ガイドが注意しています。具体的に指定するか、提案させてから選ぶかのどちらかです。

同時に消えたもの

パラメータ	状態	置き換え
temperature / top_p / top_k	4.7 以降と Sonnet 5 で 400	削除。effort とプロンプト
thinking: {type: "enabled", budget_tokens: N}	4.7 以降と Sonnet 5 で 400	thinking: {type: "adaptive"} ＋ output_config.effort
末尾アシスタント・プリフィル	4.6 以降で 400	構造化出力、またはシステムプロンプト
output_format（トップレベル）	非推奨	output_config.format
effort-2025-11-24 等のベータヘッダ	GA	削除して client.messages.create に戻す

黙って変わるもの

エラーにならないが挙動が変わる点が、実は厄介です。

• 思考が既定でオン: Opus 5 と Sonnet 5 は thinking を省略すると adaptive thinking が走ります。max_tokens は思考＋本文の合計上限なので、小さく絞っていた経路は本文が途中で切れます（stop_reason: "max_tokens"）
• 思考の本文が空: thinking.display の既定が omitted になり、thinking ブロックは返るが本文が空。見せるなら display: "summarized"
• トークン数が増える: Sonnet 5 は新トークナイザで約 1.3 倍。count_tokens で再計測

既存コードを一括で調べる

どこに temperature や budget_tokens が残っているかを手で探すのは大変です。静的に走査して file:line で列挙するツールを公開しています。

git clone https://github.com/volvox-ltd/claude5-migration-kit
python claude5-migration-kit/scan.py path/to/your/app --target opus-5

400 になる箇所（BLOCKS）と黙って変わる箇所（TUNE）を分けて出し、--fail-on-blocks で CI にも入れられます。

モデル別の変更点、プロンプトの再調整、キャッシュと履歴の設計までを 12 章にまとめた本を Zenn で公開しています。冒頭の 2 章は無料です。

• Claude 5 世代 移行ガイド ― Opus 5.5 / Sonnet 5.5 / Fable 5.1 で変わった API とプロンプト