Anthropic API完全ガイド — モデル選択・料金・実装まで

自分のアプリからClaudeを呼ぶ入口は、1本のエンドポイントです。Anthropic APIは、Claudeのモデル群(Fable 5.1・Opus 5.5・Sonnet 5.5・Haiku 4.5)へ直接アクセスする公式APIです。開発者はトークン単位の従量課金で、自分のアプリケーションに組み込めます。

モデル選びと料金、Messages APIの構造から始めます。続いてTool use・Prompt caching・Batchなどの機能を扱います。最後にレート制限とエラーの見分け方、Agent SDKやManaged Agentsとの関係を見ます。

Anthropic API(アンソロピックAPI)とは

アンソロピックAPIとも呼ばれるAnthropic APIは、HTTPS・JSONベースのRESTful APIです。ベースURLはhttps://api.anthropic.comで、各機能のパスは/v1の下に並びます。中核はMessages API(POST /v1/messages)で、モデル名・メッセージ列・システムプロンプト・ツール定義を渡すとClaudeが応答を返します。

主要なエンドポイントは次の8つです。

Claude.aiのチャットUIと違い、Anthropic APIは次の特徴を持ちます。

• 自前のアプリケーションから直接呼べる(公式SDK・ant CLI・任意のHTTPクライアント)
• トークン単位の従量課金で、input・output・キャッシュ書き込み・読み取りごとに単価が分かれる
• Tool use・ストリーミング・Prompt caching・Structured outputs・Batch・Visionなど、Claude.aiでは触れない開発向け機能を持つ
• レート制限がStart・Build・Scaleのティア制で、利用実績に応じて自動的に引き上がる

Claude Codeは内部でAnthropic APIを呼んでおり、「APIの上に乗ったアプリケーション層」です。詳細は本記事後半の「Agent SDK・Managed Agentsとの関係」で扱います。

最初のAPIリクエスト — キー取得から動作確認まで

APIキーはClaude Consoleで発行します。Claude Consoleにサインインし、Settings → API keysのCreate keyで発行します。発行時にキーの種類(個人キー・サービスアカウントキー)と有効期限を選びます。コードを書く前にリクエストを試したい場合は、Claude ConsoleのPlaygroundでAPIリクエストを試す使い方で紹介するPlaygroundが使えます。

最小構成のリクエストは次のとおりです。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "こんにちは"}
    ]
  }'

必須ヘッダーは次の3つです。公式SDKを使えばこれらは自動で付与されます。複数のワークスペースにまたがるAPIキーでは、anthropic-workspace-idも指定します。

Python SDKでの最小例です。

import anthropic
 
client = anthropic.Anthropic()  # ANTHROPIC_API_KEY 環境変数を自動で読む
 
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "こんにちは"}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)

インストールはpip install anthropic(Python)またはnpm install @anthropic-ai/sdk(TypeScript)です。リクエストサイズの上限はMessages APIとToken Counting APIが32MB、Batch APIが256MB、Files APIが500MBで、超えると413 request_too_largeが返ります。

モデル選択 — 4モデルの使い分け早見表

Anthropic APIの現行モデルは4系統で、表にはレガシー扱いのOpus 5も載せています。知能の深さ・速度・コストのトレードオフがそれぞれ異なります。

モデルIDは正確な文字列で指定します。Fable 5.1はclaude-fable-5-1、Opus 5.5はclaude-opus-5-5、Sonnet 5.5はclaude-sonnet-5-5です。Haiku 4.5はclaude-haiku-4-5で、内部的にはclaude-haiku-4-5-20251001に解決します。日付サフィックスを勝手に付け足すと404になります。旧世代のFable 5(claude-fable-5)もレガシーとして引き続き呼び出せます。

思考の挙動はモデルごとに違います。Fable 5.1は常にAdaptive thinkingがオンで、thinkingの指定は不要です。{"type": "disabled"}と{"type": "enabled", "budget_tokens": N}はどちらも400になり、思考をオフにはできません。思考の要約を見たいときは{"type": "adaptive", "display": "summarized"}を指定します。Opus 5.5も常にオンで、disabledとbudget_tokens指定はどちらも400になります。Opus 5もデフォルトでオン(Opus 4.8・4.7からの変更点)で、thinking: {"type": "disabled"}はeffortがhigh以下のときだけ受け付けられます。Sonnet 5は{"type": "adaptive"}だけがオンモードで、thinkingを省略してもAdaptive thinkingで走ります。Sonnet 5.5は{"type": "disabled"}が400になり、思考の代わりにbetween_tools(effortはhigh以下)を使います。現行の4モデルのうちHaiku 4.5だけがAdaptive thinkingに対応せず、旧来のbudget_tokens指定によるExtended thinkingのみ使えます。

Fable 5.1・Fable 5・Mythos 5.1・Mythos 5は、30日間のデータ保持が必須です。Zero Data Retention(ZDR)は、Anthropicが明示的に認めた場合を除いて選べません。Claude APIでは、保持設定が要件を満たさない組織のリクエストが400 invalid_request_errorで拒否されます。メッセージはIn order to access this model, your organization or workspace must have data retention enabled.で、公式の例はFable 5です。仕様の詳細はClaude Fable 5.1の仕様解説にまとめています。

モデルIDと機能差の一覧はClaudeモデル一覧、性能面の詳細な比較はClaudeモデル比較にまとめています。旧モデルからの移行手順はClaudeモデル移行ガイドを参照してください。

料金体系 — トークン単価とコスト最適化

Anthropic APIは入力・出力トークンに加えて、Prompt cachingの書き込み・読み取り、Batch APIの割引が別単価で設定されています。

Prompt cachingの読み取り割引とBatch APIの50%割引は重ね掛けできます。ただしBatchは非同期で並行処理されるため、キャッシュヒットはベストエフォートです。Fable 5.1・Mythos 5.1は読み取りが0.025倍なので、1時間TTLでも読み取り1回でほぼ相殺し、2回目から黒字に転じます。損益分岐の詳しい試算はClaude Fable 5.1の仕様解説の料金の節にまとめています。

Opus 5.5は2026年9月22日、Sonnet 5.5は9月28日に公開されました。Sonnet 5.5はclaude-sonnet-5-5で呼び出せ、単価はSonnet 5と同じinput $2 / output $10です。詳細はClaude Sonnet 5.5の仕様解説にあります。

Sonnet 5のinput $2 / output $10は、当初「2026年8月31日までの導入価格」として発表されました。その後、9月1日に予定していたinput $3 / output $15への値上げは実施しないと告知されています。この単価が正式な通常価格です。

Claude.aiの月額プラン(Pro・Team・Max)とAPIの従量課金は別会計です。プラン比較はClaudeの料金プラン、Claude CodeでAPIとMaxプランのどちらが得かはClaude Codeの料金試算ガイドで扱っています。

Messages APIのリクエスト構造

Messages APIの必須パラメータは3つだけです。model(モデルID)、max_tokens(出力トークンの上限)、messages(会話履歴の配列)。

応答はcontentフィールドにブロックの配列で返ります。ブロックタイプはtext・tool_use・thinkingなどが混在します。stop_reasonは終了理由を示します。値はend_turn / max_tokens / stop_sequence / tool_use / pause_turn / refusal / model_context_window_exceededのいずれかです。refusalのときはstop_detailsにカテゴリ(cyber・bioなど)が入るので、contentを読む前にstop_reasonを確認する実装にします。

max_tokensを大きく取るときはストリーミングが実質必須です。SDKは非ストリーミングリクエストが10分のタイムアウトを超えない見込みかを検証します。Haiku 4.5だけが最大出力64kで、他の現行モデルは128kまで伸ばせます。

思考の深さの制御 — Adaptive thinking

Claudeは応答の前に内部で「思考」フェーズを挟めます。旧来のExtended thinking(thinking: {"type": "enabled", "budget_tokens": N})は、思考に使うトークン数の上限を明示する方式でした。Fable 5.1・Opus 5.5・Opus 5・Sonnet 5.5・Sonnet 5ではこの方式が廃止されています。代わりにAdaptive thinking({"type": "adaptive"})とoutput_config.effortの組み合わせで制御します。

effortはlow / medium / high / xhigh / maxの5段階(Haiku 4.5は非対応)で、深さとコストのトレードオフを制御します。APIの既定はhighです。ただしOpus 5.5だけはmediumで、省略するとOpus 5より1段低い設定で動きます。既定値を明示した場合は省略と同じ挙動です。出発点は、Fable 5.1が既定のhigh、Sonnet 5.5はhigh(仕様の明確なエージェント作業はmedium)で、xhigh以上は評価で効果が出た場面だけに絞ります。モデルごとに水準が違うため、旧モデルの設定は持ち越さず、自分の評価で確かめ直します。抽出・分類のような決まったパターン処理はlow〜mediumで足ります。

thinking.displayはデフォルトで"omitted"(思考ブロックは返るが中身は空文字列)です。ユーザーに思考の要約を見せたい場合はdisplay: "summarized"を明示します。生の思考過程がそのまま返ることはどのモデルでもありません。表示される思考の要約が実際の推論をどこまで忠実に反映しているかはClaudeの拡張思考は本音を話しているかで扱っています。

旧モデルのbudget_tokens指定コードをFable 5.1・Opus 5.5・Opus 5・Sonnet 5.5・Sonnet 5にそのまま持ち込むと400エラーになります。移行手順はClaudeモデル移行ガイドにまとめています。

thinkingブロックは、それを生成したモデルに紐づきます。2026年8月31日以降に作られたアカウントでは、Fable 5.1・Opus 5.5・Sonnet 5.5のthinkingブロックより前の履歴(system・tools・過去のメッセージ)を書き換えて再送すると400になります。会話は追記だけにするのが安全です。

長時間タスクを支えるコンテキスト運用

エージェント的なタスクが長く続くと、会話履歴がコンテキストウィンドウを圧迫し、応答品質が落ちていきます。長いコンテキストが安全策の効きを弱める現象はMany-shot Jailbreakingでコンテキストウィンドウの安全策が崩れる仕組みで扱っています。AnthropicはこれをClaude側の設定で緩和する仕組みを段階的に増やしていて、現行は4つあります(いずれもベータです)。

Compactionは「まずこれを使う」位置づけの標準機能で、オンデマンド方式が優先とされています。要約による管理を望まないときだけContext editingで細かく制御します。Task budgetsはeffort(前節)と役割が違い、effortが「1ステップの思考の深さ」を制御するのに対し、Task budgetsは「エージェントループ全体の総消費量」の目安を渡す点が異なります。厳密な上限ではなく、モデルが自分で使い方を調整するための助言です。Fast modeはAnthropic直APIのみが対象で、Claude Platform on AWSを含む他の経路(Amazon Bedrock・Google Cloud・Microsoft Foundry)では使えません。

Tool use(Function calling)の実装

Tool useは、ツールの仕様をClaudeに渡し、Claudeが「このツールをこの引数で呼びたい」と判断してリクエストを返す仕組みです。ツールには2種類あります。クライアントツール(ユーザー定義ツールと、bash・text editorなどAnthropic定義ツール)はアプリケーション側が実行します。サーバーツール(web_search・web_fetch・code_execution・tool_searchなど)はAnthropicのインフラ上で実行され、結果がそのまま返ります。

{
  "model": "claude-opus-5-5",
  "tools": [
    {
      "name": "get_weather",
      "description": "指定された都市の現在の天気を返す",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "都市名"}
        },
        "required": ["city"]
      }
    }
  ],
  "messages": [
    {"role": "user", "content": "東京の天気は?"}
  ]
}

Claudeがtool_useブロックを返したら、アプリケーション側でツールを実行し、結果をtool_resultとして次のリクエストのmessagesに含めます。並列ツール呼び出し(1ターンで複数のtool_useブロックを返す)がデフォルトで有効で、独立した処理を1往復で片付けられます。並列で呼ばれたツールの結果は、必ず1つのuserメッセージにまとめて送り返します。分割して送ると、以降の並列呼び出しが減ります。

ツール呼び出しには、モデルごとに固有のシステムプロンプトトークンが加算されます。Opus 5はtool_choice: "auto"で286トークン、"any" / "tool"で406トークン。Sonnet 5はそれぞれ354・474トークンです。Opus 5.5とSonnet 5.5はautoで286トークンで、any / toolは400になるため対象外です。ツールを1つも渡さなければこの加算はありません。tool_choiceにはauto / any / tool(特定ツール指定)/ noneの4種類があります。any / toolを指定するとAPIがassistantメッセージをプリフィルするため、ツール呼び出しの前に説明文は出ません。Fable 5.1・Opus 5.5・Sonnet 5.5ではany / toolが400になるので、autoとStrict tool use(strict: true)で入力の形を保証します。違いはClaudeのtool_choiceの使い方とauto/any/tool/noneの違いにまとめています。

自分でループを書く代わりに、SDKのTool Runner(client.beta.messages.tool_runner、ベータ)を使うと、リクエスト→実行→ループの往復を自動化できます。ツールのエラー傍受や、結果へのcache_controlの付与もできます。一方、人手による承認や条件付き実行が要る場面は、手書きのループが勧められています。Python/TypeScript双方の実装とAgent SDKとの使い分けはTool RunnerでAnthropic APIのツール呼び出しループを自動化するで扱っています。

サーバーツールのweb searchは1,000検索あたり$10で、トークン費用は別にかかります。code executionは最新版のweb search・web fetchと同時に使えば無料です。単独で使う場合は組織あたり月1,550時間まで無料で、超えた分は1時間・1コンテナあたり$0.05です。MCPサーバーへの接続や高度なツール構成はコード実行×MCPの設計と高度なTool useで深掘りしています。

ツールが増えたときに効く4つの拡張

ツールを何十個も渡すエージェント運用向けに、Tool useを補う機能が増えています。

ストリーミング(SSE)の実装

stream: trueを指定すると、Server-Sent Events形式で応答がチャンク単位で返ります。イベントの流れは固定です。

const stream = client.messages.stream({
  model: "claude-sonnet-5-5",
  max_tokens: 64000,
  messages: [{ role: "user", content: "..." }],
});
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

イベント単位で処理する必要がなければ、SDKの.get_final_message()(Python)/.finalMessage()(TypeScript)が使えます。内部ではストリーミングしつつ、.create()と同じ完成したMessageオブジェクトを受け取れます。max_tokensが大きいリクエストではこの方式が推奨です。HTTPのタイムアウトを避けられます。

Tool useのストリーミングでは、tool_useブロックのinputが部分的なJSON文字列(input_json_delta)として分割送信されます。content_block_stopが来るまで蓄積してからパースします。中断からの復旧は、Claude 4.6以降のモデルでは中断された応答をassistantメッセージへ入れず、ユーザーメッセージとして「続きから」と指示する方式に変わっています。

Prompt caching — コストを1桁下げる設計

Prompt cachingは、システムプロンプト・ツール定義・長いRAGコンテキストなど変わらない部分をキャッシュし、後続リクエストで再利用する機能です。キャッシュ読込はinputの0.1倍(90%割引。Fable 5.1・Mythos 5.1は0.025倍、Opus 5.5とSonnet 5.5は0.05倍)で、頻繁な再利用がある構成ではコストへの効き目が最も大きい仕組みです。

{
  "model": "claude-sonnet-5-5",
  "system": [
    {
      "type": "text",
      "text": "あなたは...(長いシステムプロンプト)",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "..."}]
}

cache_control: {"type": "ephemeral"}を付けたブロックがキャッシュ対象になります。リクエストの最上位にcache_controlを1つ置く自動キャッシュもあり、会話が伸びるにつれてブレークポイントが自動で進みます。既定のTTLは5分、ttl: "1h"を指定すれば1時間に延長できます。

キャッシュ対象になる最小トークン数はモデルによって違います。Opus 5.5・Opus 5・Sonnet 5.5・Fable 5.1・Fable 5・Mythos 5.1・Mythos 5は512トークン、Sonnet 5は1,024トークンからキャッシュできます。一方、Haiku 4.5は4,096トークンからしかキャッシュされません。最も安いモデルが最も長いプロンプトを要求するという逆転が起きているので、Haiku 4.5でキャッシュを設計するときは注意が必要です。短いプロンプトはエラーにならず、キャッシュされないまま処理されます。usageのcache_creation_input_tokensとcache_read_input_tokensが両方0なら、最小長に届いていないことが疑われます。2回目以降で読み取りだけが0なら、TTL(既定5分)切れ、プレフィックスの変化、tool_choice・画像の有無・thinking設定・effortの変更を疑います。Cache diagnostics(リクエストにdiagnosticsオブジェクトを付けて有効にします)を使うと、APIが前回のリクエストと比べて分岐した箇所を返します。

キャッシュのプレフィックスマッチは厳密です。tools → system → messagesの順でレンダリングされ、途中の1バイトでも変わると、そこから先のキャッシュはすべて無効になります。日時やUUIDをシステムプロンプトの先頭付近に埋め込むと、キャッシュが実質機能しなくなります。

実装の詳細はPrompt caching完全活用にまとめています。

Batch API — 50%割引のバルク処理

Batch APIは即時性を捨てる代わりに、input・output両方が50%割引になる非同期処理です。POST /v1/messages/batchesに送る非同期ジョブで、処理時間と上限は次のとおりです。

{
  "requests": [
    {
      "custom_id": "request-1",
      "params": {
        "model": "claude-haiku-4-5",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "..."}]
      }
    }
  ]
}

processing_statusが"ended"になるまでポーリングし、resultsエンドポイントから結果をストリームで受け取ります。結果はcustom_idで紐付け、到着順は保証されないため、配列の位置ではなくcustom_idをキーにします。用途は数千〜数万件の記事生成・採点・抽出、月次レポート、大量翻訳などです。

長文出力が必要なバッチではanthropic-beta: output-300k-2026-03-24ヘッダーを付けます。max_tokensの上限が通常の128kから300,000まで引き上がります。対象はOpus 5.5・Opus 5・Opus 4.8・Opus 4.7・Opus 4.6・Sonnet 5.5・Sonnet 5・Sonnet 4.6です。1件で30万トークンを生成するリクエストは処理に1時間を超えることもあるため、24時間の処理枠を見込んで送信します。単価は通常のBatch割引(50%)がそのまま適用されます。制限値と実装手順、つまずきどころはClaude Batch APIの使い方にまとめています。

Structured outputsで出力を固定する

output_config.formatは、Messages APIの応答を指定したJSON Schemaに強制的に一致させる機能です。旧来のoutput_formatパラメータは非推奨で、新規コードはoutput_config.formatを使います。

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "メールから情報を抽出して"}],
    "output_config": {
      "format": {
        "type": "json_schema",
        "schema": {
          "type": "object",
          "properties": {"name": {"type": "string"}, "email": {"type": "string"}},
          "required": ["name", "email"],
          "additionalProperties": false
        }
      }
    }
  }'

一般提供(GA)の機能で、ベータヘッダーは不要です。対応モデルはClaude 4.5以降とMythos系です(Amazon Bedrockでは対応モデルが限られます)。additionalProperties: falseが必須で、minLengthやmultipleOfのような数値・文字列の制約はサポート外です。推奨の呼び出し方はclient.messages.parse()で、レスポンスをスキーマに沿って自動検証してくれます。ツール呼び出しのスキーマだけ厳密にしたいなら、ツール定義にstrict: trueを付けるStrict tool useのほうが軽量です。tool useとの使い分けを含めた実装手順はClaude JSONモードの使い方で扱っています。

Files API — 画像・PDF・データセットの再利用

Files APIは、ファイルを一度アップロードしてfile_idで使い回す仕組みです。ベータを終えたGAの機能で、ベータヘッダーは不要です。古いコードが送っているanthropic-beta: files-api-2025-04-14は、付けたままでも従来のレスポンス形式で動き続けます。SDKではclient.filesを使います。ベータヘッダー全般の併用ルールはClaude APIでanthropic-betaヘッダーを使う方法にまとめています。

アップロードしたファイルはワークスペース内の全員が参照できます。エンドユーザーや会話ごとには分離されないため、テナントごとにワークスペースを分けます。

PDFやテキストはdocumentブロック、画像はimageブロックで{"type": "file", "file_id": "..."}を参照します。.docxや.xlsxのようにdocumentブロックが対応しない形式は、プレーンテキストに変換して地の文に含めるか、code executionツールのcontainer_uploadブロックでデータセットとして渡します。

citations: {"enabled": true}をdocumentブロックに付けると、応答が引用付きの複数textブロックに分割され、各ブロックのcitations配列に出典位置(ページ番号や文字インデックス)が入ります。RAGで「この主張はどのページの何文字目に基づくか」を機械的に追跡したいときに使います。Structured outputs(output_config.format)とCitationsは同時に使えず、併用すると400エラーになります。アップロードからfile_idでの再利用、コスト試算までの実装手順はClaude Files APIでPDFを処理する方法にまとめています。

MCP connectorで直接繋ぐ

MCP(Model Context Protocol)connectorは、別途MCPクライアントを実装しなくても、Messages APIから直接リモートMCPサーバーへ接続できる機能です。現行のベータヘッダーはmcp-client-2025-11-20(旧mcp-client-2025-04-04は非推奨)です。ツール一覧を記録して固定できるmcp-client-2026-09-15も、Claude APIで使えます。旧ヘッダーからの書き換え手順はmcp-client-2025-04-04の移行にあります。

{
  "model": "claude-opus-5-5",
  "max_tokens": 1000,
  "messages": [{"role": "user", "content": "使えるツールを教えて"}],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}]
}

mcp_serversでサーバー接続(URL・認証トークン)、toolsのmcp_toolsetでどのツールを有効にするかを設定します。全ツール許可・allowlist・denylistのいずれもdefault_configとconfigsの組み合わせで表現できます。対応しているのはツール呼び出しのみで、MCP仕様のプロンプトやリソースは未対応です。ローカルのSTDIOサーバーは直接繋げず、公開HTTPサーバー(Streamable HTTPまたはSSE)だけが対象です。

ベータ機能として利用できるのはClaude API本体・Claude Platform on AWS・Microsoft Foundryで、Amazon BedrockとGoogle Cloudでは使えません。この対応状況はサーバーツール(web search・code execution)とは別なので、使いたい機能ごとに確認してから経路を選びます。

レート制限 — Start・Build・Scaleティア

レート制限は組織単位のティア制です。新規組織や利用履歴の浅い組織は、Evaluationティアから始まる場合があります。このティアの上限は標準ティアより低く抑えられ、不正利用を防ぎながら利用実績が積み上がると自動的に引き上がる仕組みです。実績を重ねるとStart → Build → Scaleへ自動的に上がり、ティアごとに月あたりの支出上限があります。上限を超える場合はカスタムティアとして個別に交渉します。

表のうち右の列は、Opus 5.5・Opus 5・Sonnet 5.5・Sonnet 5・Haiku 4.5で同じ値です。これらはそれぞれ独立したレート制限バケットを持ち、別々に上限まで使えます。ただしFable 5.1とレガシーのFable 5は合算の「Fable 5.x」バケットを共有します(Mythos 5.1とMythos 5も別の合算バケットです)。Opus 4.8・4.7・4.6・4.5は合算の「Opus 4.x」バケットを共有し、Sonnet 4.6・4.5も合算の「Sonnet 4.x」バケットを共有します。新モデルに切り替えても、旧モデルのバケットの空きは引き継がれません。

レート制限はトークンバケットアルゴリズムで、固定間隔でリセットされるのではなく継続的に補充されます。キャッシュ読み取りトークン(cache_read_input_tokens)は、Haiku 3.5を除く全モデルでITPMの計算に含まれません。つまりキャッシュヒット率を上げると、同じ実効スループットをより少ないレート制限消費で処理できます。ITPM消費を送信前に見積もりたい場合は、実際にメッセージを送らずに済むcount_tokensエンドポイントが使えます。Start/Build/Scaleそれぞれのレート制限と合わせた使い方はcount_tokensで送信前にトークン数を数える方法とレート制限にまとめています。

429エラーが返ったらretry-afterヘッダーの秒数だけ待ってから再試行します。ただし「上限に達した」エラーは3通りあり、見分け方と待ち方が違います。

自分で設定した上限は、組織だけでなくワークスペースにも置けます。メッセージの冒頭がspecified workspace API usage limitsになるのがワークスペース側の上限です。Claude Codeワークスペースの上限だけは検査が別扱いで、400でなくretry-after付きの429になることがあります。429を見て一律に待つ実装だと、2行目の支出上限では再試行が最後まで失敗し続けます。400を一律に「リクエスト形式の不備」として扱う実装も、3行目では原因を取り違えます。

SDKは接続エラー・429・5xxを最大2回まで自動リトライしますが、支出上限の429では何度繰り返しても通りません。具体的な対処手順は429・Overloadedエラーの対処法にまとめています。

エラーハンドリングと落とし穴

11種類のエラーコードごとの対処とリトライ設計、SDKの型付き例外までを掘り下げた内容はClaude APIのエラーハンドリング設計にまとめています。

SDK — 主要7言語の使い分け

Anthropic公式はPython・TypeScript・Go・Java・C#・PHP・Rubyの7言語でSDKを提供しています。いずれもMessages APIとストリーミング・リトライ・型付きのエラー処理を備え、リクエスト構造は本記事のMessages APIの節がそのまま当てはまります。機能ごとの対応範囲はSDKによって差があるため、使う機能は各SDKのドキュメントで確認してください。

エラーは各SDKが型付き例外を投げます。エラー文言の文字列マッチではなく、RateLimitErrorのような具体的な型を先に、汎用のAPIStatusErrorを後にキャッチします(Python SDKの例)。SDKは接続エラー・408・409・429・5xxを既定で2回まで自動リトライします。認証はAPIキー(ANTHROPIC_API_KEY)のほか、antCLIではant auth loginによるブラウザ経由のOAuthやWorkload Identity Federationにも対応しています。

SDK以外に、Anthropicはシェルからそのまま叩けるant CLI(タイプ付きフラグ、レスポンス変換に対応)と、Messages APIを直接呼ばずに他フレームワークの流儀でClaudeを使う2つの互換レイヤーを提供しています。OpenAI SDK compatibilityは、OpenAIのSDK・APIサーフェスのままClaudeを呼び出せる互換層です。Apple Foundation Modelsは、SwiftのLanguageModelSession APIからClaudeを呼ぶパッケージです。既存コードをOpenAI SDKやApple純正APIから大きく書き換えずに移行したい場面で候補になります。

Agent SDK・Managed Agentsとの関係

「Anthropic API」「Agent SDK」「Claude Code」「Claude Managed Agents」は名前が似ているために混同されがちですが、担っている層がまったく違います。

Anthropic APIの手動ループは自由度が最大な代わりに、承認ゲートやコンテキスト管理を自前で書く必要があります。Tool Runnerはそのループをラップし、エラー傍受や結果の加工(cache_controlの付与など)をフックとして提供します。人手の承認が要るときは手書きのループが向きます。Claude Agent SDKはこれとは別パッケージで、Claude Codeを動かしているツール・エージェントループ・コンテキスト管理をライブラリとして切り出したものです。ファイル操作・bash・grep・Web検索といった組み込みツール、コンテキスト管理、フック、サブエージェント、パーミッションまでを一式で提供します。Claude Managed Agentsはさらにその先で、ループはAnthropicがホストし、実行環境はAnthropic管理のクラウドサンドボックスか自前インフラ上のself-hostedサンドボックスから選びます。/v1/agentsでエージェント設定を作り、/v1/sessionsでセッションを開始する構成です(全エンドポイントがmanaged-agents-2026-04-01のベータヘッダーを要求するベータ機能)。

Managed Agentsの機能面はβ期間中も拡張が続いています。

ステートフルに設計されているため、Managed AgentsはZero Data Retention(ZDR)やHIPAA BAAの対象外です。

エンタープライズ向けには、これとは別に管理機能も拡張されています。Workload Identity Federationは、静的なAPIキーの代わりに外部IdPの短期トークンで認証する仕組みです。ほかに、権限をグループ・ロール単位で管理するRBAC、利用状況を集計するAdmin API analytics、監査・データ取得のためのCompliance APIがあります。

Claude Code自身は内部でAnthropic APIを呼んでいます。デフォルトのモデルは環境によって異なりますが、/modelコマンドでSonnetやHaiku 4.5に切り替えられます(v2.1.284以降、Anthropic APIで使う場合のsonnetはSonnet 5.5を指します)。認証もAPIキーだけでなく、Claude.aiのMaxプランに紐づくOAuthでも動きます。トークン単価を直接管理したくない開発者は、この経路を選ぶことが多いです。

Agent SDKでエージェントを組み始める手順はAgent SDKクイックスタート、Slack連携などの実践例はAgent SDKでSlackボットを作るで扱っています。

マルチクラウド展開の選び方

ClaudeモデルはAnthropic直APIを含め、全部で5つの経路で利用できます。それぞれ運用元と請求が異なります。

「Claude Platform on AWS」と「Amazon Bedrock」は名前が紛らわしいですが別物です。前者はAnthropicが運用し、新モデルは通常は直APIと同日に出ます。後者はAWSが運用し、対応する機能とライフサイクルの日付は別に決まります。MCP connectorやFiles APIのように、Bedrock・Google Cloudでは使えない機能が直APIやClaude Platform on AWSにはある、という非対称も珍しくありません。Foundryは、Message Batches APIとManaged Agentsが対象外です。使う機能ごとに対応状況を確認してから経路を選びます。

AUP — 利用規約上の留意点

Anthropic Acceptable Use Policy(AUP)はAPI利用時の禁止行為を定めています。

• 高リスク用途: 法律・医療・保険・金融・雇用や住宅の審査といった、消費者に直接届く助言・判断では、資格のある専門家による確認(Human-in-the-loop)と、AIを使っている旨の開示が求められます
• 禁止: 重要インフラの破壊や妨害、武器の開発、児童性的虐待コンテンツ、自傷の助長、マルウェアの作成は禁止です
• 政治: 有権者を欺く内容や、虚偽の情報による選挙・政治への介入は禁止です

商用利用時の権利関係やデータの扱いはClaudeの商用利用とデータ権利で整理しています。

まとめ

迷ったときの順序は、モデルを用途で決め、変わらない部分にcache_controlを付け、即時性の要らない処理をBatchへ逃がすことです。実装で最初に当たる壁は、400と429が「上限到達」を意味する場合があることなので、エラーのerror_codeとメッセージ冒頭で原因を切り分けます。