Anthropic Messages API 是向 Claude 發送提示的主要 HTTP 介面。核心端點是 POST /v1/messages：您提供一個模型、一組型別化的訊息內容區塊，以及一個 token 限制，然後收到一個包含一個或多個輸出區塊的 assistant 訊息。
本指南將 Anthropic API 文件轉化為實作檢查清單。內容涵蓋請求合約、多輪狀態、串流、視覺、Files API、工具使用，以及當代理後端需要同時支援 Anthropic 原生與 OpenAI 相容模型提供者時所涉及的選擇。
Messages API 端點與必要標頭
Anthropic 原生的 Messages API 使用此端點：
POST https://api.anthropic.com/v1/messages
直接 HTTP 請求通常包含以下標頭：
| 標頭 | 用途 |
|---|---|
x-api-key |
驗證 Anthropic 帳戶 |
anthropic-version |
選擇已記錄的 API 版本合約 |
content-type: application/json |
宣告 JSON 請求主體 |
API 版本標頭並非模型版本。它控制 HTTP API 的行為，而 model 欄位則選擇用於推論的 Claude 模型。將兩者都放在設定中，而不是散落在應用程式程式碼各處。
請求與回應結構
一個基本請求包含三個欄位：
{
"model": "YOUR_CLAUDE_MODEL_ID",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Explain idempotency keys in two paragraphs."
}
]
}
回應是一個 assistant 訊息，而非單純的字串。其 content 屬性是型別化區塊的陣列，因此正式環境程式碼應在讀取區塊欄位前檢查每個區塊的 type。
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "An idempotency key..."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 18,
"output_tokens": 126
}
}
這種基於區塊的設計在加入圖片或工具後變得重要。單一 assistant 回合可以包含文字與工具請求，而使用者回合則可以包含文字以及圖片或文件區塊。
最小 curl 請求
將憑證儲存在環境變數中，並使用目前您的 Anthropic 帳戶可用的模型 ID：
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "'"$ANTHROPIC_MODEL"'",
"max_tokens": 512,
"messages": [
{
"role": "user",
"content": "Return three practical ways to reduce API latency."
}
]
}'
不要硬編碼從舊教學複製的模型名稱。模型可用性與別名可能會變更，因此部署設定應使用在提供者目前模型文件或主控台中驗證過的模型 ID。
使用 Anthropic SDK 的 Python 用法
官方 Python SDK 會處理驗證標頭，並將回應轉換成型別化物件：
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
message = client.messages.create(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=512,
messages=[
{
"role": "user",
"content": "Write a Python function that validates a UUID string.",
}
],
)
for block in message.content:
if block.type == "text":
print(block.text)
迭代內容區塊比假設 message.content[0] 永遠是文字更安全。代理應用程式可能會收到工具使用區塊，而多模態功能可能會在對話中加入其他區塊型別。
多輪對話與系統提示
Messages API 是無狀態的。您的應用程式會在每次請求時重新傳送相關的對話歷史記錄：
{
"model": "YOUR_CLAUDE_MODEL_ID",
"max_tokens": 512,
"system": "You are a concise API documentation assistant.",
"messages": [
{"role": "user", "content": "What does HTTP 429 mean?"},
{"role": "assistant", "content": "It indicates rate limiting."},
{"role": "user", "content": "How should my client retry?"}
]
}
Anthropic 將系統指令放在頂層的 system 欄位中，而不是放在 role: "system" 的訊息中。這是翻譯 OpenAI 相容架構的請求時，需要考量的重要差異之一。
對於長時間執行的會話，不要重新傳送無限制的記錄。保留最新的回合、儲存仍影響任務的決策與工具結果，並在提示接近所選模型的上下文限制之前，摘要較舊的內容。
串流回應
當介面應逐步顯示輸出時，設定 stream: true：
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with client.messages.stream(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=1024,
messages=[
{"role": "user", "content": "Explain database connection pooling."}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
串流能改善感知延遲，但會增加狀態管理的工作。您的應用程式必須處理提前關閉的連線、部分文字、事件順序以及最終的使用量中繼資料。對於使用工具的代理，請在解析或執行之前，緩衝完整的工具輸入區塊。
Claude Vision API 請求
Claude Vision API 使用相同的 Messages 端點。在相關的文字問題之前，加入一個圖片內容區塊。圖片可以透過支援的 base64 資料或目前視覺文件所述允許的來源類型提供。
import base64
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with open("architecture.png", "rb") as image_file:
image_data = base64.b64encode(image_file.read()).decode("utf-8")
message = client.messages.create(
model=os.environ["ANTHROPIC_VISION_MODEL"],
max_tokens=700,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
{
"type": "text",
"text": "Identify two reliability risks in this architecture diagram.",
},
],
}
],
)
在傳送前調整過大的圖片尺寸。大圖片會增加傳輸時間與 token 使用量，卻不一定能改善回答品質。同時驗證 MIME 類型；將 JPEG 資料宣告為 PNG 是常見的請求拒絕原因。
Anthropic Files API 用法
當檔案應上傳一次並在後續的 Messages API 呼叫中重複引用，而非重複編碼與傳輸時，Anthropic Files API 就很有用。確切的可用性、支援的檔案型別與請求欄位可能因功能狀態而異，因此在正式環境依賴它之前，請檢查目前的 Files API 文件。
典型的整合包含兩個階段：
- 上傳檔案，並將回傳的檔案識別碼與應用程式的文件記錄一起保存。
- 在建立訊息時，在支援的內容區塊中引用該識別碼。
將檔案 ID 視為提供者特定的資源。記錄每個 ID 是由哪個提供者與帳戶建立的，套用您自己的存取控制，並定義刪除策略。在未經授權檢查的情況下，不應直接從不受信任的使用者接受檔案識別碼。
對於偶爾使用的小圖片，base64 很直接。對於跨多個請求使用的文件，提供者檔案資源可以減少重複上傳。如果您的應用程式必須跨多個提供者運作，請將原始物件保留在您自己的儲存中，並將提供者特定的檔案 ID 作為快取使用。
代理後端的工具使用
工具允許 Claude 請求應用程式定義的函式。您的後端使用名稱、用途與 JSON Schema 輸入合約來描述每個工具。然後模型可以回傳 tool_use 區塊，而不是假裝執行了該操作。
{
"name": "get_order_status",
"description": "Look up the current status of a customer order.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The order identifier shown to the customer."
}
},
"required": ["order_id"]
}
}
安全的執行迴圈是：
- 將訊息與工具定義傳送給模型。
- 偵測
tool_use內容區塊。 - 根據架構與您的授權規則驗證其輸入。
- 在受控環境中執行工具。
- 在下一個使用者回合中回傳相符的
tool_result區塊。 - 持續直到模型產生正常答案或達到您的迴圈限制。
永遠不要將工具引數當作受信任的 shell、SQL 或檔案路徑來執行。對於編碼代理，請在隔離環境（例如 Novita Agent Sandbox）中執行生成的命令，並設定明確的時間、網路、檔案系統與資源限制。
Anthropic 原生 vs OpenAI 相容請求
Anthropic 原生與 OpenAI 相容的 API 解決的是相同的一般問題，但它們的線路格式並不相同。
| 關注點 | Anthropic Messages API | OpenAI 相容聊天 API |
|---|---|---|
| 常見端點 | /v1/messages |
/v1/chat/completions |
| 系統指令 | 頂層 system 欄位 |
常見為 system 或 developer 訊息 |
| 輸出表示 | 型別化內容區塊 | 常見為 choices[].message |
| 工具請求 | tool_use 區塊 |
常見為 tool_calls |
| 工具結果 | tool_result 內容區塊 |
常見為 tool 角色訊息 |
當您的應用程式已經使用 OpenAI SDK，或需要以最小的傳輸變更在多個開源模型之間切換時，OpenAI 相容端點就很有價值。Novita AI 提供了一個 OpenAI 相容的 LLM API，因此同一個客戶端結構可以透過變更基礎 URL 與模型設定來定位多個可用模型。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/v3/openai",
)
response = client.chat.completions.create(
model=os.environ["NOVITA_MODEL"],
messages=[
{
"role": "user",
"content": "Review this retry strategy for failure modes.",
}
],
)
print(response.choices[0].message.content)
這並非每個 Anthropic 功能的直接替代。如果您的應用程式依賴於 Anthropic 特定的內容區塊、工具語意、引用或 Beta 功能，請保留 Anthropic 原生的轉接器。對於符合其常見請求模型的工作負載，請使用共享的 OpenAI 相容路徑。
建立提供者中立的代理後端
提供者中立的後端應將應用程式概念正規化，而不假裝所有提供者都相同。一個實用的設計包含四個層級：
- 對話模型： 將角色、文字、圖片、工具呼叫與工具結果儲存在內部架構中。
- 提供者轉接器： 將內部架構翻譯成 Anthropic Messages 或 OpenAI 相容的負載。
- 能力註冊表： 追蹤所選模型是否支援視覺、工具、結構化輸出或其他必要行為。
- 執行層： 與推論提供者分開執行工具與程式碼。
這種分離讓團隊能夠在 Anthropic 原生行為重要時使用 Claude，同時將相容的工作負載透過 Novita AI 路由到開源模型。開源路徑對於成本控制、模型實驗、資料位置要求或避免單一提供者依賴很有用。請根據您自己的任務測試輸出品質與工具可靠性，而不是假設兩個模型因為都接受聊天訊息就可以互換。
對於代理工作負載，執行層應獲得同等關注。切換模型並不能保護您的基礎設施免受不安全命令的侵害。使用隔離沙箱、強制執行工具允許清單、限制迭代次數，並記錄每個模型決策與工具結果（移除機密資訊）。
常見錯誤與除錯
400 Bad Request
檢查 JSON 結構、內容區塊型別、必要欄位，以及所選模型是否支援請求的功能。記錄提供者的請求 ID 與結構化錯誤主體，但需移除憑證與 base64 檔案資料。
401 驗證錯誤
確認 API 金鑰存在於執行階段環境中，且屬於預期的提供者。Anthropic 在直接 HTTP 請求中使用 x-api-key；OpenAI 相容客戶端通常會自動傳送 bearer token。
404 模型或資源未找到
根據目前的提供者文件或主控台驗證模型 ID。對於 Files API 資源，也請驗證該檔案是否屬於發出請求的同一帳戶與環境。
429 速率限制
使用指數退避與抖動重試，但限制嘗試次數。對背景工作進行排隊、限制每個提供者的並行數，並避免以相同的間隔立即重試所有失敗的請求。
上下文或 Token 限制錯誤
減少對話歷史記錄、圖片大小、檔案內容或請求的輸出長度。計算整個請求，包括系統指令、工具架構、先前的工具結果以及多模態內容。
推薦文章
- What Are Coding Agents? Architecture, Tools, and Execution Loops
- What Is MCP? A Developer’s Guide to Model Context Protocol
- Open-Source LLM Guide 2026: Models, Tradeoffs, and Deployment
實作檢查清單
- 將 API 金鑰、模型 ID、基礎 URL 與 API 版本儲存在執行階段設定中。
- 解析型別化內容區塊，而非假設單一文字字串。
- 儲存足夠的對話狀態，以重建每個無狀態請求。
- 驗證工具輸入並在模型程序外部執行。
- 加入逾時、重試限制、請求 ID 與移除機密資訊的可觀測性。
- 根據模型能力（而非僅根據價格或名稱）來控制提供者路由。
- 在部署前重新檢查模型 ID、功能狀態、限制與定價。
Messages API 在 HTTP 層級很直接。當應用程式加入串流、多模態輸入、工具、持久化檔案或多個模型提供者時，更困難的工程工作才會出現。將這些關注點放在明確的轉接器後面，您的代理後端就能在不用將業務邏輯綁定到單一請求格式的情況下持續演進。
常見問題
什麼是 Anthropic Messages API 端點？
原生端點是 POST https://api.anthropic.com/v1/messages。請求需要驗證、Anthropic API 版本標頭、模型 ID、token 限制以及訊息陣列。
Anthropic Messages API 與 OpenAI 相容嗎？
不相容。概念有重疊，但系統提示、內容區塊、回應物件以及工具使用訊息都不同。如果一個應用程式需要支援兩種格式，請使用提供者轉接器。
Claude Vision API 使用單獨的端點嗎？
不。視覺請求使用包含圖片與文字內容區塊的 Messages API。所選的 Claude 模型必須支援圖片輸入。
何時應該使用 Anthropic Files API？
當支援的檔案需要跨請求引用，且重複的 base64 上傳會造成浪費時使用。請保留您自己的原始檔案與授權記錄，因為提供者檔案 ID 是帳戶特定的資源。
Claude Code 可以使用自訂 API 後端嗎？
Claude Code 的整合取決於目前 Claude Code 版本所支援的驗證與提供者設定。不要假設 OpenAI 相容端點實作了 Anthropic 的 Messages API。對於自訂代理，提供者中立的轉接器通常比試圖讓不同協定看起來相同更清晰。
何時應透過 Novita AI 選擇開源模型？
當您想要 OpenAI 相容的模型切換、開源模型實驗，或為相容的工作負載提供第二個提供者時，可以考慮。對於需要 Claude 特定 API 行為的功能，請保留 Anthropic 原生請求，並根據您自己的提示與工具來評估兩種路徑。
