> ## 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 保持一致。我們至少需要提供三個必填參數：

* `model`：選擇使用的 Claude 模型，如 `claude-opus-4-20250514`、`claude-sonnet-4-20250514` 等。
* `messages`：輸入的消息數組，每條消息包含 `role`（角色）和 `content`（內容），其中 `role` 支持 `user` 和 `assistant`。
* `max_tokens`：最大輸出 token 數，用於限制單次回覆的長度。

常用可選參數：

* `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`：token 使用統計，包含 `input_tokens`（輸入 token 數）和 `output_tokens`（輸出 token 數）。

## 系統提示詞

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":" Claude。我今天能幫助你什麼？"}}

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: "你好，Claude" }],
  }),
};

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` 中傳遞完整的對話歷史，Claude 可以結合上下文進行準確的回答。

## 深度思考模型

Claude 支持 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\n在30-60-90三角形中，邊的比例為1:√3:2。\n\n對於30°角：\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` 陣列中包含了兩個內容塊：

* `type: "thinking"`：模型的內部思考過程，展示了推理步驟。
* `type: "text"`：最終的回答結果。

注意事項：

* 使用 `thinking` 時，`max_tokens` 需要大於 `budget_tokens`，因為 `budget_tokens` 是分配給思考過程的 token 預算。
* `budget_tokens` 越大，模型進行更深入推理的空間越大，適合處理複雜問題。

## 視覺模型

Claude 支持多模態輸入，可以同時處理文本和圖像。在 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": "這張圖片顯示的是一個 API 請求配置介面，看起來像是一個 AI 聊天完成服務。介面包括模型選擇、消息、流模式和最大令牌設置的參數。"
    }
  ],
  "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": "城市和州，例如：舊金山，加州"
                    }
                },
                "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": "舊金山，加州"
      }
    }
  ],
  "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": "城市和州，例如：舊金山，加州"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "舊金山的天氣怎麼樣？"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "讓我幫你查一下舊金山的天氣。"},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "舊金山，加州"}}
            ]
        },
        {
            "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` 格式                    |
| Token 統計 | `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": "token_mismatched"
  }
}
```

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

## 結論

通過本文檔，您已經了解了如何使用 Claude Messages API 以 Anthropic 原生格式調用 Claude 的對話功能。Messages API 支持基本對話、系統提示詞、流式響應、多輪對話、深度思考、視覺理解和工具調用等豐富功能。如有任何問題，請隨時聯繫我們的技術支持團隊。