> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Messages API 申請及び使用

> Claude AI 集成指南 - XHuoAPI

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](https://api.xhuoapi.ai/documents/280928a2-2dce-419c-adb5-1ea835e8183a) ページにアクセスし、「Acquire」ボタンをクリックして、リクエストに必要な資格情報を取得します：

![](https://cdn.xhuoapi.ai/nyq0xz.png)

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。

初回申請時には無料のクレジットが付与され、この 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 の例

```bash theme={null}
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 の例

```python theme={null}
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())
```

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

```json theme={null}
{
  "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 の例

```python theme={null}
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 の例

```python theme={null}
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 の例

```javascript theme={null}
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 の例

```python theme={null}
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())
```

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

```json theme={null}
{
  "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 の例

```python theme={null}
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())
```

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

```json theme={null}
{
  "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 エンコードされた画像を使用する

```python theme={null}
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 の例

```bash theme={null}
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` が含まれます。

返される結果の例：

```json theme={null}
{
  "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 の例

```python theme={null}
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` タイプの内容ブロックが含まれます：

```json theme={null}
{
  "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` の形式でモデルに返す必要があります：

```python theme={null}
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`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```json theme={null}
{
  "error": {
    "code": "400",
    "message": "不正なリクエスト"
  }
}
```

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

## 結論

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