跳轉到主要內容
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 保持一致。我們至少需要提供三個必填參數：
  • 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 示例

curl -X POST 'https://api.acedata.cloud/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.acedata.cloud/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：token 使用統計，包含 input_tokens（輸入 token 數）和 output_tokens（輸出 token 數）。

​
系統提示詞

Claude Messages API 支持通過 system 字段設定系統提示詞，用於定義模型的行為、角色和上下文。

​
Python 示例

import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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 示例

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

​
深度思考模型

Claude 支持 Extended Thinking（深度思考）功能，可以讓模型在回覆之前先進行內部推理，提升處理複雜問題的準確性。使用該功能時需要傳入 thinking 參數。

​
Python 示例

import requests

url = "https://api.acedata.cloud/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\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 編碼圖像

import base64
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "這張圖片裡面是什麼？"
                }
            ]
        }
    ]
}

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

​
cURL 示例

curl -X POST 'https://api.acedata.cloud/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.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "這張圖片裡面是什麼？"
          }
        ]
      }
    ]
  }'
支持的圖片格式包括：image/jpeg、image/png、image/gif、image/webp。 返回結果示例： 
{
  "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 示例

import requests

url = "https://api.acedata.cloud/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 類型的內容塊： 
{
  "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 的形式回傳給模型： 
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 的區別

Ace Data Cloud 同時提供兩種 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_schemaOpenAI 兼容的 functions 格式
Token 統計input_tokens / output_tokensprompt_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": "token_mismatched"
  }
}

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

​
結論

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