Anthropic Messages

Messages API 使用 user、assistant 訊息和 Content Blocks 建立模型回應，支援文字、圖片、工具呼叫、串流輸出與擴充思考。不同模型可使用的內容區塊、工具和進階參數可能不同，請以目前 API Key 可見模型及實際 API 功能為準。

POST/v1/messages

根據 user 與 assistant 訊息生成下一條 assistant 回應。訊息內容可以使用字串，也可以使用文字、圖片、工具和文件 Content Blocks。

API 支援一般 JSON 回應和 SSE 串流事件；圖片、工具呼叫與擴充思考能力取決於所選模型。

授權

anthropicApiKey

x-api-key<token>

在 x-api-key Header 中傳遞 API Key。

傳遞位置: header

Header 參數

anthropic-version*string

指定要使用的 API 版本。

預設值"2023-06-01"

anthropic-beta?string

指定要使用的 beta 版本。可以使用逗號分隔多個值，或多次傳送該 Header。

請求主體

Messages 使用 Content Blocks 表達文字、圖片、工具和擴充思考。請依任務選擇檢視模式。

application/json

文字對話

使用 user 和 assistant 訊息組織單輪或多輪對話；系統指令請放在頂層欄位。

model: 目前 API Key 可見且支援 Messages 的模型 ID。
max_tokens: 本次回應最多可生成的 Token 數量。
messages[]: 依時間順序排列的 user 和 assistant 訊息。

application/json

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "你好！請介紹一下自己。"
    }
  ]
}

基礎文字對話。messages 可以包含字串或 text Content Blocks。

model*string

要使用的模型 ID。請選擇目前 API Key 可見且支援 Messages 的模型。

長度1 <= length <= 256

max_tokens*integer

允許生成的最大 token 數量。不同模型具有不同限制；設定為 0 可用於只填充提示快取而不生成回應。

範圍0 <= value

messages*array<>

依時間順序排列的文字對話訊息。content 可以是字串或 text Content Blocks 陣列。

項目數1 <= items

metadata?

與請求關聯的中繼資料。

cache_control?|null

頂層快取控制，會自動套用至請求中最後一個可快取內容區塊。是否可用取決於模型與供應管道。

container?||null

跨請求重複使用容器，或指定要載入到容器中的 Skills。是否可用取決於模型、供應管道與帳戶。

inference_geo?string|null

指定執行推理的地理區域；未設定時使用帳戶的預設區域。是否可用取決於帳戶與供應管道。

output_config?

模型輸出設定。欄位可用性取決於所選模型與供應管道。

service_tier?string

請求使用的服務層級。auto 可在可用時使用優先容量，standard_only 僅使用標準容量；實際支援範圍取決於帳戶與供應管道。

可用值

"auto"
"standard_only"

stop_sequences?array<string>

自訂的停止生成文字序列。

stream?boolean

是否使用伺服器傳送事件逐步傳回回應。

預設值false

system?|array<>

頂層系統提示。Messages 清單中沒有 system 角色。

temperature?number

已棄用

已棄用。Claude Opus 4.6 之後發布的模型不支援自訂 temperature；為相容舊請求可接受 1.0，其他值可能傳回 400。建議新版模型省略該欄位。

範圍0 <= value <= 1

thinking?||

擴充思考設定。新版模型優先使用 adaptive；舊模型可能繼續使用 enabled 與 budget_tokens。

tool_choice?||

tools?array<|||||||>

模型可以使用的自訂工具或內建工具。

top_k?integer

已棄用

已棄用。Claude Opus 4.6 之後發布的模型可能拒絕任何 top_k 值並傳回 400。建議新版模型省略該欄位。

範圍1 <= value

top_p?number

已棄用

已棄用。Claude Opus 4.6 之後發布的模型僅對接近預設值的設定保留有限相容行為，其他值可能傳回 400。建議新版模型省略該欄位。

範圍0 < value < 1

圖片、工具和擴充思考的支援情況可能因模型與供應管道而異。請先完成最小文字請求，再逐項啟用進階欄位。

回應主體

`application/json`

curl -X POST "https://example.com/v1/messages" \  -H "anthropic-version: 2023-06-01" \  -H "Content-Type: application/json" \  -d '{    "model": "MODEL_ID",    "max_tokens": 1024,    "messages": [      {        "role": "user",        "content": "你好！請介紹一下自己。"      }    ]  }'

{
  "content": [
    {
      "type": "text",
      "text": "你好！我是一個 AI 助手。"
    }
  ],
  "id": "msg_example",
  "model": "MODEL_ID",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 16,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Anthropic Messages 官方文件檢視上游協議定義與最新欄位變更。

授權

Header 參數

請求主體

回應主體

200application/json

400application/json

401application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`