短い答え
max_tokens は、モデルが 1 回のレスポンスで生成できる Token 数を制限します。API とモデルによって、項目名、必須設定、デフォルト動作が異なります。
安定した出力のために、長い回答、コード生成、ドキュメントタスクでは明示的な出力上限を設定します。Claude / Anthropic 互換 API 呼び出しでは、通常 max_tokens を明示的に送信する必要があります。
基本概念
出力上限が小さすぎると、レスポンスが途中で切れる場合があります。非常に大きくしても、モデルが必ずその数の Token を生成するわけではありませんが、長い出力のタスクではコストが増える場合があります。
異なるパラメーター名
Codex CLI または Responses API ベースの別のツールを使用する場合は、そのツールまたはプロバイダーが現在サポートする項目に従ってください。すべてのモデルに同じパラメーター名を固定しないでください。
設定しないとどうなるか
動作はプロバイダーと API によって異なります。
同じコードでも、モデルを切り替えると出力の長さが変わる場合があります。本番での想定外を減らすため、明示的な出力上限を設定してください。
推奨範囲
実際の最大値は、モデル広場と上流のモデルドキュメントで確認してください。モデル出力上限はバージョンによって変わる場合があります。
出力が途中で切れたときの対処
レスポンスにfinish_reason: "length" が含まれる場合、通常はモデルが出力上限に達しています。
次の順番でトラブルシューティングします。
- 現在の API がサポートする出力上限項目を増やします。
- 正しいパラメーター名を使用しているか確認します。
- 不要な出力を減らすため、プロンプトをより具体的にします。
- より大きい出力ウィンドウのモデルを使用します。
- タスクを複数の手順に分割します。
よくある間違い
- より大きい
max_tokens値を指定すれば、モデルが常により多く書くと考えること。 finish_reasonを確認せず、出力が途中で切れた後に再試行すること。- 推論モデルで古い項目名を使用すること。
- コンテキストとコストの見積もりで非表示の Reasoning Token を無視すること。
- モデル自体の最大出力上限を無視すること。