Anthropic Messages APIは、Claudeにプロンプトを送信するための主要なHTTPインターフェースです。コアとなるエンドポイントは POST /v1/messages で、モデル、型付きメッセージコンテンツブロックのリスト、トークン制限を指定すると、1つ以上の出力ブロックを含むアシスタントメッセージが返されます。
このガイドは、Anthropic API ドキュメントを実装チェックリストに変換します。リクエスト契約、マルチターン状態、ストリーミング、ビジョン、Files API、ツール使用、そしてエージェントバックエンドがAnthropicネイティブとOpenAI互換の両方のモデルプロバイダーをサポートする必要がある場合の選択肢について説明します。
Messages API エンドポイントと必須ヘッダー
Anthropic のネイティブ Messages API は次のエンドポイントを使用します:
POST https://api.anthropic.com/v1/messages
直接HTTPリクエストを行う場合、通常は次のヘッダーを含めます:
| ヘッダー | 目的 |
|---|---|
x-api-key |
Anthropic アカウントを認証する |
anthropic-version |
ドキュメント化されたAPIバージョン契約を選択する |
content-type: application/json |
JSONリクエストボディを宣言する |
APIバージョンヘッダーはモデルバージョンではありません。これはHTTP APIの動作を制御するもので、model フィールドが推論に使用するClaudeモデルを選択します。両方の値を設定ファイルに保持し、アプリケーションコードに散在させないようにしてください。
リクエストとレスポンスの構造
基本的なリクエストには3つのフィールドが含まれます:
{
"model": "YOUR_CLAUDE_MODEL_ID",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "冪等性キーについて2段落で説明してください。"
}
]
}
レスポンスは、単なる文字列ではなく、アシスタントメッセージです。その content プロパティは型付きブロックの配列であるため、本番コードでは各ブロックの type を検査してからフィールドを読み取る必要があります。
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "冪等性キーとは..."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 18,
"output_tokens": 126
}
}
このブロックベースの設計は、画像やツールを追加する際に重要になります。1回のアシスタントターンにはテキストとツールリクエストを含めることができ、ユーザーターンにはテキストに加えて画像やドキュメントブロックを含めることができます。
最小限のcurlリクエスト
認証情報を環境変数に保存し、現在のAnthropicアカウントで利用可能なモデルIDを使用します:
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "'"$ANTHROPIC_MODEL"'",
"max_tokens": 512,
"messages": [
{
"role": "user",
"content": "APIレイテンシを削減する実用的な方法を3つ挙げてください。"
}
]
}'
古いチュートリアルからコピーしたモデル名をハードコードしないでください。モデルの可用性やエイリアスは変更される可能性があるため、デプロイメント設定ではプロバイダーの最新のモデルドキュメントまたはコンソールで確認したモデルIDを使用する必要があります。
Python SDK を使用した使用方法
公式のPython SDKは認証ヘッダーを処理し、レスポンスを型付きオブジェクトに変換します:
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
message = client.messages.create(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=512,
messages=[
{
"role": "user",
"content": "UUID文字列を検証するPython関数を書いてください。",
}
],
)
for block in message.content:
if block.type == "text":
print(block.text)
コンテンツブロックを反復処理することは、message.content[0] が常にテキストであると仮定するよりも安全です。エージェントアプリケーションはツール使用ブロックを受け取る可能性があり、マルチモーダル機能は他のブロックタイプを会話に追加する可能性があります。
マルチターン会話とシステムプロンプト
Messages APIはステートレスです。アプリケーションは関連する会話履歴を毎回リクエストとともに送信します:
{
"model": "YOUR_CLAUDE_MODEL_ID",
"max_tokens": 512,
"system": "あなたは簡潔なAPIドキュメントアシスタントです。",
"messages": [
{"role": "user", "content": "HTTP 429は何を意味しますか？"},
{"role": "assistant", "content": "レート制限を示しています。"},
{"role": "user", "content": "クライアントはどのようにリトライすべきですか？"}
]
}
Anthropicはシステム指示を role: "system" のメッセージではなく、トップレベルの system フィールドに配置します。これは、リクエストをOpenAI互換スキーマから変換する際に考慮すべき重要な違いの1つです。
長時間のセッションでは、無制限のトランスクリプトを再送信しないでください。最新のターンを保持し、タスクに影響を与える決定やツール結果を保存し、プロンプトが選択したモデルのコンテキスト制限に近づく前に古いコンテキストを要約してください。
ストリーミングレスポンス
インターフェースが出力を段階的に表示する必要がある場合は、stream: true を設定します:
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with client.messages.stream(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=1024,
messages=[
{"role": "user", "content": "データベースコネクションプーリングについて説明してください。"}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
ストリーミングは知覚レイテンシを改善しますが、状態管理の作業が増えます。アプリケーションは、早期に閉じる接続、部分的なテキスト、イベントの順序、最終的な使用量メタデータを処理する必要があります。ツールを使用するエージェントの場合、ツール入力ブロック全体をバッファリングしてから解析または実行してください。
Claude Vision API リクエスト
Claude Vision API は同じ Messages エンドポイントを使用します。関連するテキスト質問の前に画像コンテンツブロックを追加します。画像は、サポートされている base64 データとして、または現在のビジョンドキュメントで説明されている許可されたソースタイプを介して提供できます。
import base64
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with open("architecture.png", "rb") as image_file:
image_data = base64.b64encode(image_file.read()).decode("utf-8")
message = client.messages.create(
model=os.environ["ANTHROPIC_VISION_MODEL"],
max_tokens=700,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
{
"type": "text",
"text": "このアーキテクチャ図における2つの信頼性リスクを特定してください。",
},
],
}
],
)
送信前にサイズの大きい画像はリサイズしてください。大きな画像は転送時間とトークン使用量を増加させ、必ずしも回答の品質を向上させるわけではありません。また、MIMEタイプを検証してください。JPEGデータをPNGとして宣言することは、リクエストが拒否される一般的な原因です。
Anthropic Files API の使用法
Anthropic Files API は、ファイルを一度アップロードし、後続のMessages API呼び出しでエンコードや再送信を繰り返す代わりに参照する場合に便利です。正確な可用性、サポートされるファイルタイプ、リクエストフィールドは機能ステータスによって異なる可能性があるため、本番環境で使用する前に現在のFiles APIドキュメントを確認してください。
一般的な統合には2つの段階があります:
- ファイルをアップロードし、返されたファイル識別子をアプリケーションのドキュメントレコードとともに保持します。
- メッセージを作成するときに、サポートされているコンテンツブロック内でその識別子を参照します。
ファイルIDはプロバイダー固有のリソースとして扱います。各IDを作成したプロバイダーとアカウントを記録し、独自のアクセス制御を適用し、削除ポリシーを定義します。ファイル識別子は、認証チェックなしに信頼できないユーザーから直接受け入れるべきではありません。
小さな画像がたまにある場合は、base64が簡単です。多くのリクエストで使用されるドキュメントの場合、プロバイダーファイルリソースを使用すると、繰り返しのアップロードを減らすことができます。アプリケーションが複数のプロバイダーで動作する必要がある場合は、元のオブジェクトを独自のストレージに保持し、プロバイダー固有のファイルIDをキャッシュとして作成します。
エージェントバックエンドのためのツール使用
ツールを使用すると、Claudeはアプリケーション定義の関数を要求できます。バックエンドは各ツールを名前、目的、JSON Schema入力契約で記述します。モデルは、操作を実行したふりをする代わりに、tool_use ブロックを返すことができます。
{
"name": "get_order_status",
"description": "顧客注文の現在のステータスを確認します。",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "顧客に表示される注文識別子。"
}
},
"required": ["order_id"]
}
}
安全な実行ループは次のとおりです:
- メッセージとツール定義をモデルに送信します。
tool_useコンテンツブロックを検出します。- 入力をスキーマと認可ルールに対して検証します。
- 制御された環境でツールを実行します。
- 次のユーザーターンで一致する
tool_resultブロックを返します。 - モデルが通常の回答を生成するか、ループ制限に達するまで続けます。
ツールの引数を信頼されたシェル、SQL、またはファイルパスとして実行しないでください。コーディングエージェントの場合は、生成されたコマンドを Novita Agent Sandbox などの分離された環境内で実行し、明示的な時間、ネットワーク、ファイルシステム、リソース制限を設定します。
Anthropic ネイティブと OpenAI 互換リクエストの比較
Anthropic ネイティブと OpenAI 互換 API は同じ一般的な問題を解決しますが、ワイヤーフォーマットは同一ではありません。
| 考慮事項 | Anthropic Messages API | OpenAI 互換チャット API |
|---|---|---|
| 共通エンドポイント | /v1/messages |
/v1/chat/completions |
| システム指示 | トップレベル system フィールド |
一般的に system または developer メッセージ |
| 出力表現 | 型付きコンテンツブロック | 一般的に choices[].message |
| ツールリクエスト | tool_use ブロック |
一般的に tool_calls |
| ツール結果 | tool_result コンテンツブロック |
一般的に tool ロールメッセージ |
OpenAI 互換エンドポイントは、アプリケーションがすでに OpenAI SDK を使用している場合、または最小限のトランスポート変更でオープンソースモデルを切り替える必要がある場合に価値があります。Novita AI は OpenAI 互換の LLM API を公開しているため、ベース URL とモデル設定を変更するだけで、同じクライアント構造で複数の利用可能なモデルをターゲットにできます。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/v3/openai",
)
response = client.chat.completions.create(
model=os.environ["NOVITA_MODEL"],
messages=[
{
"role": "user",
"content": "この障害モードに対するリトライ戦略をレビューしてください。",
}
],
)
print(response.choices[0].message.content)
これはすべての Anthropic 機能のドロップイン変換ではありません。アプリケーションが Anthropic 固有のコンテンツブロック、ツールセマンティクス、引用、またはベータ機能に依存している場合は、Anthropic ネイティブアダプターを維持してください。共通のリクエストモデルに適合するワークロードには、共有の OpenAI 互換パスを使用します。
プロバイダーに依存しないエージェントバックエンドの構築
プロバイダーに依存しないバックエンドは、すべてのプロバイダーが同一であると装うことなく、アプリケーションの概念を正規化する必要があります。実用的な設計には4つの層があります:
- 会話モデル: ロール、テキスト、画像、ツール呼び出し、ツール結果を内部スキーマに保存します。
- プロバイダーアダプター: 内部スキーマを Anthropic Messages または OpenAI 互換ペイロードに変換します。
- 機能レジストリ: 選択したモデルがビジョン、ツール、構造化出力、またはその他の必要な動作をサポートしているかどうかを追跡します。
- 実行層: 推論プロバイダーとは別にツールとコードを実行します。
この分離により、チームは Anthropic ネイティブの動作が重要な場合に Claude を使用し、互換性のあるワークロードを Novita AI を介してオープンソースモデルにルーティングできます。オープンソースパスは、コスト管理、モデル実験、データロケーション要件、または単一プロバイダー依存の回避に役立ちます。出力品質とツールの信頼性を独自のタスクでテストし、両方のモデルがチャットメッセージを受け入れるという理由だけで交換可能であると想定しないでください。
エージェントワークロードの場合、実行層にも同様の注意が必要です。モデルを切り替えても、安全でないコマンドからインフラストラクチャを保護することはできません。分離されたサンドボックスを使用し、ツールの許可リストを適用し、イテレーションに上限を設定し、秘密情報を削除した状態で各モデルの決定とツール結果をログに記録します。
一般的なエラーとデバッグ
400 Bad Request
JSON の形状、コンテンツブロックタイプ、必須フィールド、および選択したモデルが要求された機能をサポートしているかどうかを確認します。プロバイダーのリクエスト ID と構造化エラーボディをログに記録しますが、認証情報と base64 ファイルデータは編集してください。
401 認証エラー
API キーがランタイム環境に存在し、目的のプロバイダーに属していることを確認します。Anthropic は直接 HTTP リクエストに x-api-key を使用します。OpenAI 互換クライアントは通常、ベアラートークンを自動的に送信します。
404 モデルまたはリソースが見つかりません
モデル ID を現在のプロバイダードキュメントまたはコンソールと照合します。Files API リソースの場合は、ファイルがリクエストで使用されるのと同じアカウントと環境に属していることも確認します。
429 レート制限
指数バックオフとジッターでリトライしますが、試行回数に上限を設定します。バックグラウンド作業をキューに入れ、プロバイダーごとの同時実行数を制限し、すべての失敗したリクエストを同じ間隔で即座にリトライしないようにします。
コンテキストまたはトークン制限エラー
会話履歴、画像サイズ、ファイルコンテンツ、または要求された出力長を減らします。システム指示、ツールスキーマ、以前のツール結果、マルチモーダルコンテンツを含むリクエスト全体をカウントします。
おすすめ記事
- What Are Coding Agents? Architecture, Tools, and Execution Loops
- What Is MCP? A Developer’s Guide to Model Context Protocol
- Open-Source LLM Guide 2026: Models, Tradeoffs, and Deployment
実装チェックリスト
- API キー、モデル ID、ベース URL、API バージョンをランタイム設定に保持する。
- 型付きコンテンツブロックを解析し、単一のテキスト文字列を想定しない。
- 各ステートレスリクエストを再構築するために十分な会話状態を保存する。
- ツール入力を検証し、モデルプロセス外で実行する。
- タイムアウト、リトライ制限、リクエスト ID、編集された可観測性を追加する。
- 価格や名前だけでなく、モデル機能によってプロバイダールーティングを制御する。
- デプロイ前にモデル ID、機能ステータス、制限、価格を再確認する。
Messages API は HTTP レベルでは単純です。より難しいエンジニアリング作業は、アプリケーションがストリーミング、マルチモーダル入力、ツール、永続ファイル、または複数のモデルプロバイダーを追加するときに発生します。これらの懸念事項を明示的なアダプターの背後に置くことで、エージェントバックエンドはビジネスロジックを1つのリクエスト形式に結び付けることなく進化できます。
FAQ
Anthropic Messages API のエンドポイントは何ですか？
ネイティブエンドポイントは POST https://api.anthropic.com/v1/messages です。リクエストには、認証、Anthropic API バージョンヘッダー、モデル ID、トークン制限、メッセージ配列が必要です。
Anthropic Messages API は OpenAI 互換ですか？
いいえ。概念は重複していますが、システムプロンプト、コンテンツブロック、レスポンスオブジェクト、ツール使用メッセージが異なります。1つのアプリケーションで両方のフォーマットをサポートする必要がある場合は、プロバイダーアダプターを使用してください。
Claude Vision API は別のエンドポイントを使用しますか？
いいえ。ビジョンリクエストは、画像とテキストのコンテンツブロックを含む Messages API を使用します。選択した Claude モデルが画像入力をサポートしている必要があります。
Anthropic Files API はいつ使用すべきですか？
サポートされているファイルを複数のリクエストで参照する必要があり、繰り返しの base64 アップロードが無駄になる場合に使用します。プロバイダーファイル ID はアカウント固有のリソースであるため、独自のソースファイルと認可レコードを保持してください。
Claude Code はカスタム API バックエンドを使用できますか？
Claude Code の統合は、現在の Claude Code リリースでサポートされている認証とプロバイダー設定に依存します。OpenAI 互換エンドポイントが Anthropic の Messages API を実装していると想定しないでください。カスタムエージェントの場合、異なるプロトコルを同一に見せかけようとするよりも、プロバイダーに依存しないアダプターの方が通常は明確です。
Novita AI を介したオープンソースモデルはいつ選択すべきですか？
OpenAI 互換のモデル切り替え、オープンモデルの実験、または互換性のあるワークロードのセカンドプロバイダーが必要な場合に検討してください。Claude 固有の API 動作を必要とする機能には Anthropic ネイティブリクエストを維持し、両方のパスを独自のプロンプトとツールで評価してください。
