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

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_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：內部伺服器錯誤，伺服器出現問題。

錯誤響應示例

{
  "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 支持基本對話、系統提示詞、流式響應、多輪對話、深度思考、視覺理解和工具調用等豐富功能。如有任何問題，請隨時聯繫我們的技術支持團隊。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

代理

進階

Claude Messages API 申請及使用

申請流程

基本使用

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 的區別

​錯誤處理

​錯誤響應示例

​結論

申請流程

基本使用

cURL 示例

Python 示例

系統提示詞

Python 示例

流式響應

Python 示例

JavaScript 示例

多輪對話

Python 示例

深度思考模型

Python 示例

視覺模型

使用 Base64 編碼圖像

使用 URL 圖像

cURL 示例

工具調用（Tool Use）

Python 示例

與 Chat Completion API 的區別

錯誤處理

錯誤響應示例

結論