Claude Messages API 申請及び使用

Anthropic Claude は非常に強力な AI 対話システムで、プロンプトを入力するだけで、数秒以内に流暢で自然な返信を生成できます。Claude Messages API は Anthropic の公式ネイティブ API フォーマットで、OpenAI の互換フォーマット（Chat Completion）とは異なり、Anthropic 独自のリクエストとレスポンス構造を採用しており、Claude の独自の能力（マルチモーダルコンテンツ入力、ツール呼び出し、深い思考（Extended Thinking）などの高度な機能）をより良く活用できます。この文書では、Claude Messages API 操作の使用フローを主に紹介します。これを利用することで、Anthropic 公式と一致するネイティブインターフェースを使用して Claude の対話機能を呼び出すことができます。

申請フロー

Claude Messages API を使用するには、まず Claude Messages API ページにアクセスし、「Acquire」ボタンをクリックして、リクエストに必要な資格情報を取得します：

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。初回申請時には無料のクレジットが付与され、この API を無料で使用できます。

基本使用

Claude Messages API のリクエストパスは /v1/messages で、Anthropic 公式 API と一致しています。少なくとも3つの必須パラメータを提供する必要があります：

model：使用する Claude モデルを選択します。例：claude-opus-4-20250514、claude-sonnet-4-20250514 など。
messages：入力メッセージの配列で、各メッセージには role（役割）と content（内容）が含まれ、role は user と assistant をサポートします。
max_tokens：最大出力トークン数で、単一の返信の長さを制限します。

一般的なオプションパラメータ：

system：システムプロンプトで、モデルの動作と役割を設定します。
temperature：生成のランダム性で、0-1 の間で値が大きいほど返信が散発的になります。
stream：ストリーミングレスポンスを使用するかどうか、true に設定すると逐次的に返されます。
stop_sequences：カスタム停止シーケンスで、モデルがこれらのテキストに遭遇したときに生成を停止します。
top_p：核サンプリングパラメータで、temperature と組み合わせて生成のランダム性を制御します。
top_k：確率が最も高い K 個のオプションからのみサンプリングします。
tools：ツール定義で、モデルが外部関数を呼び出すために使用します。
tool_choice：モデルが提供されたツールをどのように使用するかを制御します。

cURL の例

curl -X POST 'https://api.xhuoapi.ai/v1/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Python の例

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

呼び出し後、返される結果は以下の通りです：

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

返される結果のフィールド説明：

id：今回のメッセージのユニーク識別子。
type：常に message。
role：常に assistant。
content：返信内容の配列で、各要素には type（例：text）と対応する内容が含まれます。
model：リクエストを処理したモデル名。
stop_reason：停止理由で、可能な値には end_turn（正常終了）、max_tokens（最大長に達した）、stop_sequence（停止シーケンスに遭遇）、tool_use（ツール呼び出し）があります。
stop_sequence：カスタム停止シーケンスによって停止した場合、マッチした停止シーケンスのテキストが表示されます。
usage：トークン使用統計で、input_tokens（入力トークン数）と output_tokens（出力トークン数）が含まれます。

システムプロンプト

Claude Messages API は system フィールドを通じてシステムプロンプトを設定することをサポートしており、モデルの動作、役割、コンテキストを定義するために使用されます。

Python の例

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "あなたは専門的な中国語翻訳アシスタントです。ユーザーが入力した英語を中国語に翻訳してください。",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

system プロンプトを設定することで、Claude の役割と動作を正確に制御できます。

ストリーミングレスポンス

このインターフェースはストリーミングレスポンスもサポートしており、stream パラメータを true に設定することで、逐次的に返される効果を得ることができ、ウェブページで逐字表示を実現するのに非常に適しています。

Python の例

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

ストリーミングレスポンスは Server-Sent Events (SSE) フォーマットで返され、各行は event: と data: で始まります。ストリーミングイベントのタイプには以下が含まれます：

message_start：メッセージの開始で、メッセージの基本情報とモデル名が含まれます。
content_block_start：コンテンツブロックの開始。
content_block_delta：コンテンツブロックの増分更新で、新しく生成されたテキストの断片が含まれます。
content_block_stop：コンテンツブロックの終了。
message_delta：メッセージレベルの増分更新で、stop_reason と最終的な usage 情報が含まれます。
message_stop：メッセージの終了。

出力効果は以下の通りです：

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"こんにちは"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! 私の名前は"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"クロードです。今日はどのようにお手伝いできますか？"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":15}}

event: message_stop
data: {"type":"message_stop"}

見ると、ストリーミングレスポンスの content_block_delta イベントには、段階的に生成されたテキストコンテンツが含まれており、すべての text_delta を結合することで完全な返信を得ることができます。

JavaScript の例

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "こんにちは、クロード" }],
  }),
};

const response = await fetch("https://api.xhuoapi.ai/v1/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

多輪対話

もし多輪対話機能を接続したい場合は、messages 配列に user と assistant の役割のメッセージを交互に配置し、以前の対話履歴を一緒に渡す必要があります。

Python の例

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "こんにちは、私の名前はアリスです。"},
        {"role": "assistant", "content": "こんにちはアリス！お会いできて嬉しいです。今日はどのようにお手伝いできますか？"},
        {"role": "user", "content": "私の名前は何ですか？"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

返された結果は以下の通りです：

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "あなたの名前はアリスです。先ほど教えてくれました！"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

messages に完全な対話履歴を渡すことで、クロードは文脈を考慮して正確な回答を行うことができます。

深い思考モデル

クロードは Extended Thinking（深い思考）機能をサポートしており、モデルが返信する前に内部推論を行うことで、複雑な問題の処理精度を向上させることができます。この機能を使用する際は、thinking パラメータを渡す必要があります。

Python の例

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "30度のサインは何ですか？推論を示してください。"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

返された結果は以下の通りです：

{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "ユーザーは30度のサインを尋ねています。これは基本的な三角法の質問です。\n\n30-60-90の三角形では、辺の比率は1:√3:2です。\n\n30°の角度の場合：\n- 対辺は1\n- 斜辺は2\n- したがって、sin(30°) = 対辺/斜辺 = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "30度のサインは**1/2**または**0.5**です。\n\nこれは基本的な三角関数の値の一つです。30-60-90の三角形では、辺の比率は1:√3:2であり、30°の角度に対する辺の長さは1、斜辺の長さは2であるため、sin(30°) = 1/2となります。"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}

content 配列には2つのコンテンツブロックが含まれています：

type: "thinking"：モデルの内部思考過程を示し、推論ステップを示しています。
type: "text"：最終的な回答結果です。

注意事項：

thinking を使用する際は、max_tokens が budget_tokens より大きくする必要があります。なぜなら、budget_tokens は思考プロセスに割り当てられるトークン予算だからです。
budget_tokens が大きいほど、モデルがより深い推論を行うためのスペースが増え、複雑な問題の処理に適しています。

視覚モデル

クロードは多モーダル入力をサポートしており、テキストと画像を同時に処理できます。Messages API では、content を配列形式に設定し、画像コンテンツブロックを渡すことで視覚能力を使用できます。

Base64 エンコードされた画像を使用する

import base64
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# 画像を読み込み、エンコードする
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "この画像には何がありますか？"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

URL 画像を使用する

```python
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.xhuoapi.ai/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "この画像には何が写っていますか？"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

cURL の例

curl -X POST 'https://api.xhuoapi.ai/v1/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.xhuoapi.ai/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "この画像には何が写っていますか？"
          }
        ]
      }
    ]
  }'

サポートされている画像フォーマットには、image/jpeg、image/png、image/gif、image/webp が含まれます。返される結果の例：

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "この画像は、AIチャット完了サービスのAPIリクエスト設定インターフェースを示しています。このインターフェースには、モデル選択、メッセージ、ストリームモード、最大トークン設定のためのパラメータが含まれています。"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

ツール呼び出し（Tool Use）

Claude Messages API は、モデルが必要に応じて事前定義されたツール/関数を呼び出す機能をネイティブにサポートしています。

Python の例

import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "指定された場所の現在の天気を取得します",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "都市と州、例：サンフランシスコ、CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "サンフランシスコの天気はどうですか？"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

モデルがツールを呼び出すことを決定した場合、返される結果の content には tool_use タイプの内容ブロックが含まれます：

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "サンフランシスコの天気を確認します。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "サンフランシスコ、CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}

stop_reason が tool_use であることに注意してください。これはモデルがツールを呼び出す必要があることを示しています。この結果を受け取った後、ツール関数を実行し、その結果を tool_result の形式でモデルに返す必要があります：

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "指定された場所の現在の天気を取得します",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "都市と州、例：サンフランシスコ、CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "サンフランシスコの天気はどうですか？"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "サンフランシスコの天気を確認します。"},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "サンフランシスコ、CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "晴れ、72°F"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

モデルはツールから返された結果に基づいて、最終的な自然言語の返信を生成します。

Chat Completion API との違い

XHuoAPI は、同時に二つの Claude API フォーマットを提供しており、両者の主な違いは以下の通りです：

特性	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
フォーマット	Anthropic ネイティブフォーマット	OpenAI 互換フォーマット
システムプロンプト	独立した `system` フィールド	`messages` 中の `role: "system"` で渡される
応答構造	`content` 配列（多様なタイプをサポート）	`choices` 配列（`message` を含む）
ストリーミングフォーマット	SSE イベント（多様なイベントタイプ）	SSE `data` 行
深い思考	ネイティブ `thinking` パラメータ	特殊モデル名をトリガー（例：`-thinking` サフィックス）
ツール呼び出し	ネイティブ `tools` + `input_schema`	OpenAI 互換の `functions` フォーマット
トークン統計	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_tokens`

もしあなたのシステムがすでに OpenAI フォーマットの API に接続されている場合、Chat Completion API を使用してシームレスに切り替えることができます。Claude の全てのネイティブ機能を使用する必要がある場合は、Messages API の使用をお勧めします。

エラーハンドリング

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

400 token_mismatched：不正なリクエスト、パラメータが不足または無効である可能性があります。
400 api_not_implemented：不正なリクエスト、パラメータが不足または無効である可能性があります。
401 invalid_token：未認証、無効または不足している認証トークン。
429 too_many_requests：リクエストが多すぎます、レート制限を超えました。
500 api_error：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

エラー応答の例

{
  "error": {
    "code": "400",
    "message": "不正なリクエスト"
  }
}

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "取得に失敗しました"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

この文書を通じて、あなたはClaude Messages APIを使用してAnthropicのネイティブ形式でClaudeの対話機能を呼び出す方法を理解しました。Messages APIは基本的な対話、システムプロンプト、ストリーミングレスポンス、マルチターン対話、深い思考、視覚理解、ツール呼び出しなどの豊富な機能をサポートしています。ご不明な点がございましたら、いつでも当社の技術サポートチームにお問い合わせください。

Documentation Index

​申請フロー

​基本使用

​cURL の例

​Python の例

​システムプロンプト

​Python の例

​ストリーミングレスポンス

​Python の例

​JavaScript の例

​多輪対話

​Python の例

​深い思考モデル

​Python の例

​視覚モデル

​Base64 エンコードされた画像を使用する

​URL 画像を使用する

​cURL の例

​ツール呼び出し（Tool Use）

​Python の例

​Chat Completion API との違い

​エラーハンドリング

​エラー応答の例

​結論

申請フロー

基本使用

cURL の例

Python の例

システムプロンプト

Python の例

ストリーミングレスポンス

Python の例

JavaScript の例

多輪対話

Python の例

深い思考モデル

Python の例

視覚モデル

Base64 エンコードされた画像を使用する

URL 画像を使用する

cURL の例

ツール呼び出し（Tool Use）

Python の例

Chat Completion API との違い

エラーハンドリング

エラー応答の例

結論