# Models APIのcapabilitiesで機能検出ルーティング

> Claude Models APIのcapabilitiesとlifecycleを起動時に取得し、モデルID直書きの400エラーをなくす。thinking種別・effort・retires_atを使うルーティング設計を解説する。

- Canonical: https://kuucorp.com/blog/claude-models-api-capabilities-discovery-routing-design/
- Date: 2026-10-26
- Last modified: 2026-10-26
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
LLMゲートウェイの設定ファイルに「このモデルはthinkingが使える」「このモデルはPDFを受けられる」と手書きしていると、新モデルの追加や退役のたびに設定が実態からずれる。ずれた設定は本番で400エラーとして表面化する。

Claude Models APIは、モデルごとの対応機能と提供状態を機械可読な形で返す。複数チームが共有するプラットフォームでは、この情報を設定の正本にする設計が有効だ。ルーティング全体の考え方は[LLMゲートウェイのルーティング設計](/blog/llm-gateway-routing-rate-limiting/)を参照してほしい。

## Models APIのcapabilitiesは何を返すのか

> `GET /v1/models`と`GET /v1/models/{model_id}`は、モデルごとに`capabilities`と`lifecycle`を返す。キーは既知の機能すべてについて常に存在する。

`capabilities`には、`batch`・`citations`・`image_input`・`pdf_input`・`structured_outputs`・`effort`・`thinking`・`context_management`・`server_tools`などが並び、各項目は`supported`の真偽値を持つ。`effort`は`low`から`max`までのレベル別に、`thinking.types`は`adaptive`・`enabled`・`disabled`・`between_tools`の4種別ごとに対応可否を返す。`context_management`には`compact_20260112`などの戦略別フラグがある。

モデル本体のメタ情報として、`max_input_tokens`、`max_tokens`、`line`（`haiku`・`sonnet`・`opus`・`fable`・`mythos`）も取得できる。`line`が`null`のモデルもあり、公式ドキュメントはIDから系列を推測しないよう求めている。

## lifecycleとretires_atはどう扱うべきか

> `lifecycle`は`active`・`deprecated`・`retired`の3値で、退役の判定に使えるのは`lifecycle`だけだ。`retires_at`は予定日で、改定されうる。

`deprecated`のモデルは既存の利用組織には呼び出せるが、新規採用は閉じられている。`retires_at`の日付が過ぎても`lifecycle`が`deprecated`のままなら、それは退役の遅延を意味し、退役済みではない。一覧の既定では`active`と`deprecated`だけが返り、`retired`は`lifecycle`パラメータで明示的に要求したときだけ現れる。

運用上の判断材料は次の3点に絞れる。

1. `lifecycle: deprecated`を検知したら、ルーティング候補から外す前に警告をチームへ通知する
2. `retires_at`までの残日数を、移行計画のチケット期限に紐づける
3. 退役判定そのものは`retires_at`の日付ではなく`lifecycle`の値で行う

退役ポリシーの全体像は[モデル非推奨化の移行計画](/blog/claude-model-deprecation-lifecycle-migration-smb/)に整理してある。

## ルーティングにcapabilitiesをどう組み込むか

> 要求機能のセットを宣言し、`capabilities`と突き合わせて候補モデルを絞る。これでモデルID直書きの条件分岐が消える。

設計の核は、リクエスト側が必要な機能を宣言し、ゲートウェイが候補モデルをフィルタすることだ。

- 画像添付があるリクエストは`image_input.supported`が真のモデルだけを残す
- 厳密なスキーマ出力が必要な呼び出しは`structured_outputs.supported`で絞る
- `between_tools`のthinking種別を使うエージェント経路は`thinking.types.between_tools.supported`で判定する。この種別はthinkingを無効にしたうえで、ツール呼び出しの合間に書かれる短い進捗を返す仕組みで、非対応モデルに送ると400になる
- 長大な入力は`max_input_tokens`、出力量は`max_tokens`の上限で候補を切る

`between_tools`の移行詳細は[between_toolsへの移行設計](/blog/claude-sonnet-5-5-between-tools-migration-enterprise/)に、effortをメッセージ単位で切り替える設計は[per-message effortのルーティング設計](/blog/claude-per-message-effort-cache-preserving-routing-design/)にある。

## 運用で何に注意すべきか

> `capabilities`は「モデルの能力」であり、組織で許可された利用可否ではない。ポリシーや組織設定による拒否は別途ありうる。

公式ドキュメントには、2つの前提が明記されている。1つ目は、`server_tools`が対応でも、管理者がWeb検索を無効にしていれば組織としては拒否される点だ。2つ目は、`between_tools`が対応でも、thinkingを切った状態では許されないeffortレベルなど、別の理由でリクエストが拒否される点だ。したがってcapabilitiesは「送ってよい候補」を絞る一次フィルタに過ぎず、実行時のエラーハンドリングとフォールバックは残す必要がある。

実装上のポイントは次のとおりだ。

- 起動時と一定間隔でModels APIを取得し、ゲートウェイ内のカタログを更新する
- 複数Workspaceを扱う認証情報では`anthropic-workspace-id`ヘッダーで対象を明示する
- 取得失敗時は直近のカタログを保持し、取得失敗をアラート対象にする
- カタログの差分（機能の追加・`lifecycle`の変化）を変更履歴として監査ログに残す

### 規模別の留意点（SMB / エンタープライズ）

数十チームがモデルを共有する環境では、カタログ取得をゲートウェイに一元化し、各チームの設定にはモデルIDではなく「必要機能」と「系列（`line`）」だけを書かせる。これにより、モデル追加や退役の影響が個別アプリの改修を要さなくなる。組織横断のモデル統制は[Kuuの大企業向けAI変革プログラム（RDE）](https://kuucorp.com/services/rde/)で設計から支援している。

## 参考

- [List Models（公式API リファレンス）](https://platform.claude.com/docs/en/api/models/list)
- [Get a Model（公式API リファレンス）](https://platform.claude.com/docs/en/api/models/retrieve)
- [Release notes（公式ドキュメント）](https://platform.claude.com/docs/en/release-notes/overview)

## まとめ

Models APIの`capabilities`と`lifecycle`を設定の正本にすると、モデルの追加・退役に追随する作業をカタログ更新に集約できる。ただし組織設定による拒否は別に起こるため、実行時のフォールバックは残す。まずはゲートウェイで取得と差分監査を始めるのが現実的な一歩だ。ルーティング統制の設計は[Kuu株式会社のRDE](https://kuucorp.com/services/rde/)にご相談ください。
