Anthropic 提供兩種使用 Claude 進行建構的方式,各自適用於不同的使用情境:
| Messages API | Claude Managed Agents | |
|---|---|---|
| 說明 | 直接存取模型提示功能 | 預先建構、可配置的代理框架,在託管基礎架構中執行 |
| 最適合 | 自訂代理迴圈與細粒度控制 | 長時間執行的任務與非同步工作 |
| 了解更多 | Messages API 文件 | Claude Managed Agents 文件 |
本指南涵蓋使用 Messages API 的常見模式,包括基本請求、多輪對話、預填技巧以及視覺功能。如需完整的 API 規格,請參閱 Messages API 參考文件。
此功能符合「Zero Data Retention」(零資料保留),即 ZDR 的資格。當您的組織具有 ZDR 安排時,透過此功能傳送的資料在 API 回應返回後不會被儲存。
Claude Opus 4.7 及更新版本的模型(包括 Claude Opus 4.8)不支援 temperature、top_p 和 top_k 取樣參數。若將這些參數設定為非預設值,將會回傳 400 錯誤。請從請求內容中省略這些參數,並改用提示來引導模型的行為。請參閱遷移指南。
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello!"
}
],
"model": "claude-opus-4-8",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}在 Claude Opus 4.7 及更新版本的模型上,拒絕回應(stop_reason: "refusal")也會包含一個 stop_details 物件,用於識別觸發拒絕的政策類別。請參閱處理停止原因以取得欄位參考和範例處理程式碼。
Messages API 是無狀態的,這表示您每次都需要將完整的對話歷史傳送給 API。您可以使用此模式隨時間建立對話。較早的對話輪次不一定需要實際來自 Claude,您可以使用合成的 assistant 訊息。
{
"id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Sure, I'd be happy to provide..."
}
],
"model": "claude-opus-4-8",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 30,
"output_tokens": 309
}
}在 Claude Opus 4.8 上,您可以在使用者輪次之後加入 "role": "system" 的訊息(須遵守放置規則),以便在對話進行到一半時新增系統指令。system 訊息不能是 messages 中的第一個項目;對於從一開始就應套用的指令,請使用頂層的 system 欄位。
對話中途的系統訊息與頂層 system 欄位具有相同的權限,但由於它被附加在訊息歷史的末尾,因此不會使其之前的任何快取前綴失效。對於應從第一輪就套用的指令,請使用頂層 system 欄位;對於稍後才變得相關的指令,請使用對話中途的系統訊息。
請參閱對話中途的系統訊息以取得完整指南,包括如何將其與提示快取結合使用。
您可以在輸入訊息清單的最後一個位置預先填入 Claude 回應的一部分。這可用於塑造 Claude 的回應。以下範例使用 "max_tokens": 1 從 Claude 取得單一選擇題答案。
Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 不支援預填功能。對這些模型使用預填的請求會回傳 400 錯誤。請改用支援此功能之模型上的結構化輸出,或使用系統提示指令。請參閱遷移指南以了解遷移模式。
{
"id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "C"
}
],
"model": "claude-sonnet-4-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 42,
"output_tokens": 1
}
}Claude 可以在請求中讀取文字和圖片。圖片可以使用 base64、url 或 file 來源類型提供。file 來源類型參照透過 Files API 上傳的圖片。支援的媒體類型為 image/jpeg、image/png、image/gif 和 image/webp。請參閱視覺指南以取得更多詳細資訊。
{
"id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
}
],
"model": "claude-opus-4-8",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 1551,
"output_tokens": 71
}
}處理每個 stop_reason 值,並決定當回應結束時該採取什麼行動。
為 Claude 提供工具,以便在 Messages API 中呼叫外部服務和 API。
使用 Messages API 控制桌面電腦環境。
從 Claude 取得保證符合結構描述驗證的 JSON 輸出。
Was this page helpful?
message = anthropic.Anthropic().messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)message = anthropic.Anthropic().messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"},
{"role": "assistant", "content": "Hello!"},
{"role": "user", "content": "Can you describe LLMs to me?"},
],
)
print(message)message = anthropic.Anthropic().messages.create(
model="claude-sonnet-4-5",
max_tokens=1,
messages=[
{
"role": "user",
"content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
},
{"role": "assistant", "content": "The answer is ("},
],
)
print(message)import base64
import httpx
# 選項 1:Base64 編碼的圖片
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")
message = anthropic.Anthropic().messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": image_media_type,
"data": image_data,
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(message)
# 選項 2:URL 參照的圖片
message_from_url = anthropic.Anthropic().messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(message_from_url)