AI と連携する

このプロジェクトでは HopBase 経由で Claude モデルのみを接続し、以下の契約に厳密に従ってください。メーカー公式 API ドキュメントと異なる場合は、この契約が優先されます。

対象範囲
- Claude API(Anthropic Messages)または Claude Code に必要な範囲だけを実装してください。他のモデルファミリーを追加・設定・テストしないでください。
- 既存のフレームワーク、SDK、コードスタイルを維持し、動作に必要な最小限の変更だけを行ってください。
- まず、ローカルのシングルユーザーツール、社内サービス、下流の顧客やテナントにサービスを提供するアプリケーションのどれに当たるかを判断し、それに応じてキーの配置とアーキテクチャを決めてください。

キー
- Claude 系のキーのみを使用してください。キーはコンソールのグループ 1 つに紐づき、そのグループのモデルにしか届きません:
  - SDK、HTTP、エディター、Claude Code:「Claude Max(公式フル枠)」または「Claude Max(公式フル枠)- 期間限定特価」。
  - 「Claude Max（ccmax）」は Claude Code クライアント内でのみ動作します。このキーで SDK や HTTP から呼ぶと失敗します。
- 複数モデルを扱うプロジェクトでは HOPBASE_CLAUDE_API_KEY または既存のシークレットマネージャーを読み取ってください。HOPBASE_API_KEY の再利用は、単一モデルのプロジェクトであることが明確な場合に限ります。
- キーを新規作成したり、他のモデルファミリーのキーを読み取ったり、実際のキーを会話に貼り付けるよう私に求めたりしないでください。キーがない場合は作業を止め、コンソールの「APIキー」で該当グループのキーを作成し、ローカルまたはシークレットマネージャーに設定するよう私に依頼してください。

モデル
- まずこのキーで GET https://api.hop-base.com/v1/models を呼び出し、レスポンスに含まれる claude- で始まる ID だけをそのままコピーして使用してください。
- 販売中: claude-fable-5-1、claude-sonnet-5、claude-sonnet-5-5、claude-opus-5-5、claude-fable-5、claude-opus-5、claude-opus-4-8、claude-opus-4-7、claude-opus-4-6、claude-sonnet-4-6、claude-haiku-4-5-20251001。
- 404 model_not_found は、その ID がこのキーのグループにないことを意味します。/v1/models を取得し直して返された ID を使い、モデル名を推測・短縮・書き換えしないでください。

接続
- Base URL は https://api.hop-base.com で、/v1 は付けません(SDK が /v1/messages を付加します)。/v1 で終わる Base URL は /v1/v1/messages になり 404 になります。
- 認証: SDK の api_key オプション、または生の HTTP では x-api-key ヘッダー。SDK ネイティブの認証方式を維持してください。
- エンドポイント: POST /v1/messages と POST /v1/messages/count_tokens。Claude のキーで OpenAI のパス(/v1/chat/completions、/v1/responses)を呼ぶと 404 です。Messages の呼び出しを Chat Completions に変換しないでください。
- Claude Code: ANTHROPIC_BASE_URL=https://api.hop-base.com、ANTHROPIC_AUTH_TOKEN=<Claude のキー>。ワンクリック設定は両方を ~/.claude/settings.json の env ブロックに書き込み、シェルの環境変数より優先されます。

リクエストのルール
- max_tokens は必ず送ってください。省略すると 4096 が補われ、長い出力は stop_reason "max_tokens" で打ち切られます。
- claude-opus-5-5: 思考は常時オンです。thinking {"type":"disabled"} や budget_tokens を送ると 400 になり、深さは output_config.effort(既定 medium)で調整します。tool_choice の any / tool は 400(auto を使用)。アシスタントのプレフィルは非対応です。
- 過去の thinking ブロックは受け取ったとおり(signature を含めて)返してください。書き換え・結合・モデル間での再利用は 400 "Invalid signature in thinking block" になります。
- 非ストリーミング呼び出しは 300 秒が上限です(超えると 504)。長い出力はストリーミングにし、Anthropic の SSE をそのまま中継してください。count_tokens の呼び出しも同時実行数を消費します。

エラーと再試行
- HTTP ステータスと error.code で分岐し、message の文言では判定しないでください。問い合わせ用にレスポンスヘッダー x-request-id を記録してください。
- 間隔を空けて再試行するもの(2 秒、5 秒、15 秒、最大 3 回、Retry-After に従う): 429、502、503、504、途中で切れたストリーム。
- そのまま再試行しないもの: 400、401、402、403、404、413、422。先にリクエスト、キー、グループ、残高を直してください。
- Anthropic 形式のエラーには code フィールドがありません。キーのエラー(401、402、403)は /v1/messages でも OpenAI 形式 {"error":{"code":…}} です。
- 404 "This API path is not supported by the current platform" は、プロトコルの誤りか Base URL の余分な /v1 です。設定を直し、再試行しないでください。
- ストリーム開始後の失敗は HTTP 200 のまま event: error 行で届きます。読み取りループで処理し、リクエスト全体を送り直してください。

実装
- Base URL、キーの変数名、デフォルトモデルは既存の設定の仕組みに入れ、.env.example は実際のキーを含めずに更新してください。
- 下流やマルチテナント向けの呼び出しでは、キーをサーバー側に保持し、呼び出し元の認証を再利用したうえで、モデルのアローリスト、リクエスト制限、タイムアウト、レート制限、利用状況の帰属管理、マスキングしたログを追加してください。ローカルのシングルユーザーツールにはこの層を追加しないでください。
- アカウントの既定の同時実行数は 5 リクエストです。超えた分はキューに入らず、Retry-After: 1 付きの 429 で即座に拒否されるため、クライアント側で流量を制御してください。

検証と引き渡し
- 設定後に最小限の実リクエストを 1 回送信してください。ストリーミングのテストは、プロジェクトが実際にストリーミングを使う場合のみ追加してください。
- 返された claude- モデルに max_tokens 1024 で「ok とだけ返信」を求める Messages リクエストを 1 回送り、content[0].text を確認してください。
- 変更したファイル、キーの変数名、モデル ID、エンドポイント、HTTP ステータス、マスキングしたレスポンスの要約を報告し、起動・検証・ロールバックの各コマンドを添えてください。