Anthropic 對話格式（Messages）

官方文件

Anthropic Messages - Anthropic Streaming Messages

📝 簡介

給定一組包含文字和/或影象內容的結構化輸入訊息列表，模型將生成對話中的下一條訊息。Messages API 可用於單次查詢或無狀態的多輪對話。

💡 請求示例

基礎文字對話 ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

響應示例:

{
  "content": [
    {
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2095,
    "output_tokens": 503
  }
}

影象分析對話 ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": "/9j/4AAQSkZJRg..."
                    }
                },
                {
                    "type": "text",
                    "text": "這張圖片裡有什麼?"
                }
            ]
        }
    ]
}'

響應示例:

{
  "content": [
    {
      "text": "這張圖片顯示了一隻橙色的貓咪正在窗臺上曬太陽。貓咪看起來很放鬆，眯著眼睛享受陽光。窗外可以看到一些綠色的植物。",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 3050,
    "output_tokens": 892
  }
}

工具呼叫 ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": "今天北京的天氣怎麼樣?"
        }
    ],
    "tools": [
        {
            "name": "get_weather",
            "description": "獲取指定位置的當前天氣",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "城市名稱,如:北京"
                    }
                },
                "required": ["location"]
            }
        }
    ]
}'

響應示例:

{
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "get_weather",
      "input": { "location": "北京" }
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2156,
    "output_tokens": 468
  }
}

流式響應 ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": "講個故事"
        }
    ],
    "stream": true
}'

響應示例:

{
  "type": "message_start",
  "message": {
    "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
    "model": "claude-3-5-sonnet-20241022",
    "role": "assistant",
    "type": "message"
  }
}
{
  "type": "content_block_start",
  "index": 0,
  "content_block": {
    "type": "text"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "從前"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "有一隻"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "小兔子..."
  }
}
{
  "type": "content_block_stop",
  "index": 0
}
{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 2045,
      "output_tokens": 628
    }
  }
}
{
  "type": "message_stop"
}

📮 請求

端點

POST /v1/messages

鑑權方法

在請求頭中包含以下內容進行 API 金鑰認證：

x-api-key: $API_KEY

其中 $API_KEY 是您的 API 金鑰。您可以透過控制檯獲取 API 金鑰，每個金鑰僅限於一個工作區使用。

請求頭引數

`anthropic-beta`

型別：字串
必需：否

指定要使用的 beta 版本，支援用逗號分隔的列表如 beta1,beta2，或多次指定該請求頭。

`anthropic-version`

型別：字串
必需：是

指定要使用的 API 版本。

請求體引數

`max_tokens`

型別：整數
必需：是

生成的最大 token 數量。不同模型有不同的限制，詳見模型文件。範圍 x > 1。

`messages`

型別：物件陣列
必需：是

輸入訊息列表。模型被訓練為在使用者和助手之間交替進行對話。建立新訊息時，您可以使用 messages 引數指定之前的對話輪次，模型將生成對話中的下一條訊息。連續的使用者或助手訊息會被合併為單個輪次。

每個訊息必須包含 role 和 content 欄位。您可以指定單個使用者角色訊息，或包含多個使用者和助手訊息。如果最後一條訊息使用助手角色，響應內容將直接從該訊息的內容繼續，這可以用來約束模型的響應。

單條使用者訊息示例:

[{ "role": "user", "content": "Hello, Claude" }]

多輪對話示例:

[
  { "role": "user", "content": "你好。" },
  { "role": "assistant", "content": "你好！我是 Claude。有什麼可以幫你的嗎？" },
  { "role": "user", "content": "請用簡單的話解釋什麼是 LLM？" }
]

部分填充的響應示例:

[
  {
    "role": "user",
    "content": "太陽的希臘語名字是什麼? (A) Sol (B) Helios (C) Sun"
  },
  { "role": "assistant", "content": "正確答案是 (" }
]

每個訊息的 content 可以是字串或內容塊陣列。使用字串相當於一個 "text" 型別的內容塊陣列的簡寫。以下兩種寫法等效：

{ "role": "user", "content": "Hello, Claude" }

{
  "role": "user",
  "content": [{ "type": "text", "text": "Hello, Claude" }]
}

從 Claude 3 模型開始，您還可以傳送圖片內容塊：

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "/9j/4AAQSkZJRg..."
      }
    },
    {
      "type": "text",
      "text": "這張圖片裡有什麼?"
    }
  ]
}

目前支援的圖片格式包括: base64, image/jpeg、image/png、image/gif 和 image/webp。

`messages.role`

型別：列舉字串
必需：是
可選值：user, assistant

注意：Messages API 中沒有 "system" 角色，如果需要系統提示，請使用頂層的 system 引數。

`messages.content`

型別：字串或物件陣列
必需：是

訊息內容可以是以下幾種型別之一：

文字內容 (Text)

{
  "type": "text", // 必需，列舉值: "text"
  "text": "Hello, Claude", // 必需，最小長度: 1
  "cache_control": {
    "type": "ephemeral" // 可選，列舉值: "ephemeral"
  }
}

圖片內容 (Image)

{
  "type": "image", // 必需，列舉值: "image"
  "source": {
    // 必需
    "type": "base64", // 必需，列舉值: "base64"
    "media_type": "image/jpeg", // 必需，支援: image/jpeg, image/png, image/gif, image/webp
    "data": "/9j/4AAQSkZJRg..." // 必需，base64 編碼的圖片資料
  },
  "cache_control": {
    "type": "ephemeral" // 可選，列舉值: "ephemeral"
  }
}

工具使用 (Tool Use)

{
  "type": "tool_use", // 必需，列舉值: "tool_use"，預設值
  "id": "toolu_xyz...", // 必需，工具使用的唯一識別符號
  "name": "get_weather", // 必需，工具名稱，最小長度: 1
  "input": {
    // 必需，工具的輸入引數物件
    // 工具輸入引數，具體格式由工具的 input_schema 定義
  },
  "cache_control": {
    "type": "ephemeral" // 可選，列舉值: "ephemeral"
  }
}

工具結果 (Tool Result)

{
  "type": "tool_result", // 必需，列舉值: "tool_result"
  "tool_use_id": "toolu_xyz...", // 必需
  "content": "結果內容", // 必需，可以是字串或內容塊陣列
  "is_error": false, // 可選，布林值
  "cache_control": {
    "type": "ephemeral" // 可選，列舉值: "ephemeral"
  }
}

當 content 為內容塊陣列時，每個內容塊可以是文字或圖片：

{
  "type": "tool_result",
  "tool_use_id": "toolu_xyz...",
  "content": [
    {
      "type": "text", // 必需，列舉值: "text"
      "text": "分析結果", // 必需，最小長度: 1
      "cache_control": {
        "type": "ephemeral" // 可選，列舉值: "ephemeral"
      }
    },
    {
      "type": "image", // 必需，列舉值: "image"
      "source": {
        // 必需
        "type": "base64", // 必需，列舉值: "base64"
        "media_type": "image/jpeg",
        "data": "..."
      },
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

文件 (Document)

{
  "type": "document", // 必需，列舉值: "document"
  "source": {
    // 必需
    // 文件源資料
  },
  "cache_control": {
    "type": "ephemeral" // 可選，列舉值: "ephemeral"
  }
}

注意：

每種型別都可以包含可選的 cache_control 欄位，用於控制內容的快取行為
文字內容的最小長度為 1
所有型別的 type 欄位都是必需的列舉字串
工具結果的 content 欄位支援字串或包含文字/圖片的內容塊陣列

`model`

型別：字串
必需：是

要使用的模型名稱，詳見模型文件。範圍 1 - 256 個字元。

`metadata`

型別：物件
必需：否

描述請求後設資料的物件。包含以下可選欄位：

user_id: 與請求關聯的使用者的外部識別符號。應該是 uuid、雜湊值或其他不透明識別符號。不要包含任何標識資訊如姓名、郵箱或電話號碼。最大長度：256。

`stop_sequences`

型別：字串陣列
必需：否

自定義的停止生成的文字序列。

`stream`

型別：布林值
必需：否

是否使用伺服器傳送事件 (SSE) 來增量返回響應內容。

`system`

型別：字串
必需：否

系統 prompt，為 Claude 提供背景和指令。這是一種為模型提供上下文和特定目標或角色的方式。注意這與訊息中的 role 不同，Messages API 中沒有 "system" 角色。

`temperature`

型別：數字
必需：否
預設值：1.0

控制生成隨機性，0.0 - 1.0。範圍 0 < x < 1`。建議對於分析性/選擇題類任務使用接近 0.0 的值，對於創造性和生成性任務使用接近 1.0 的值。

注意：即使 temperature 設定為 0.0，結果也不會完全確定。

🆕 `thinking`

型別：物件
必需：否

配置 Claude 的擴充套件思考功能。啟用時，響應將包含展示 Claude 在給出最終答案前的思考過程的內容塊。需要至少 1,024 個 token 的預算，並計入您的 max_tokens 限制。

可以設定為以下兩種模式之一：

1. 啟用模式

{
  "type": "enabled",
  "budget_tokens": 2048
}

type: 必需，列舉值: "enabled"
budget_tokens: 必需，整數。決定 Claude 可以用於內部推理過程的 token 數量。更大的預算可以讓模型對複雜問題進行更深入的分析，提高響應質量。必須 ≥1024 且小於 max_tokens。範圍 x > 1024`。

2. 禁用模式

{
  "type": "disabled"
}

type: 必需，列舉值: "disabled"

`tool_choice`

型別：物件
必需：否

控制模型如何使用提供的工具。可以是以下三種型別之一：

1. Auto 模式 (自動選擇)

{
  "type": "auto", // 必需，列舉值: "auto"
  "disable_parallel_tool_use": false // 可選，預設 false。如果為 true，模型最多隻會使用一個工具
}

2. Any 模式 (任意工具)

{
  "type": "any", // 必需，列舉值: "any"
  "disable_parallel_tool_use": false // 可選，預設 false。如果為 true，模型將恰好使用一個工具
}

3. Tool 模式 (指定工具)

{
  "type": "tool", // 必需，列舉值: "tool"
  "name": "get_weather", // 必需，指定要使用的工具名稱
  "disable_parallel_tool_use": false // 可選，預設 false。如果為 true，模型將恰好使用一個工具
}

注意：

Auto 模式：模型可以自行決定是否使用工具
Any 模式：模型必須使用工具，但可以選擇任何可用的工具
Tool 模式：模型必須使用指定的工具

`tools`

型別：物件陣列
必需：否

定義模型可能使用的工具。工具可以是自定義工具或內建工具型別：

1. 自定義工具（Tool）

每個自定義工具定義包含：

type: 可選，列舉值: "custom"
name: 工具名稱，必需，1-64 個字元
description: 工具描述，建議儘可能詳細
input_schema: 工具輸入的 JSON Schema 定義，必需
cache_control: 快取控制，可選，type 為 "ephemeral"

示例：

[
  {
    "type": "custom",
    "name": "get_weather",
    "description": "獲取指定位置的當前天氣",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "城市名稱,如:北京"
        }
      },
      "required": ["location"]
    }
  }
]

2. 計算機工具 (ComputerUseTool)

{
  "type": "computer_20241022", // 必需
  "name": "computer", // 必需，列舉值: "computer"
  "display_width_px": 1024, // 必需，顯示寬度(畫素)
  "display_height_px": 768, // 必需，顯示高度(畫素)
  "display_number": 0, // 可選，X11 顯示編號
  "cache_control": {
    "type": "ephemeral" // 可選
  }
}

3. Bash 工具 (BashTool)

{
  "type": "bash_20241022", // 必需
  "name": "bash", // 必需，列舉值: "bash"
  "cache_control": {
    "type": "ephemeral" // 可選
  }
}

4. 文字編輯器工具 (TextEditor)

{
  "type": "text_editor_20241022", // 必需
  "name": "str_replace_editor", // 必需，列舉值: "str_replace_editor"
  "cache_control": {
    "type": "ephemeral" // 可選
  }
}

當模型使用工具時，會返回 tool_use 內容塊：

[
  {
    "type": "tool_use",
    "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "name": "get_weather",
    "input": { "location": "北京" }
  }
]

您可以執行工具並透過 tool_result 內容塊返回結果：

[
  {
    "type": "tool_result",
    "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "content": "北京當前天氣晴朗，溫度 25°C"
  }
]

`top_k`

型別：整數
必需：否
範圍：x > 0

從 token 的前 K 個選項中取樣。用於移除低機率的"長尾"響應。建議僅在高階用例中使用，通常只需要調整 temperature。

`top_p`

型別：數字
必需：否
範圍：0 `< x < 1

使用 nucleus 取樣。計算每個後續 token 按機率降序排列的累積分佈，在達到 top_p 指定的機率時截斷。建議僅調整 temperature 或 top_p 其中之一，不要同時使用。

📥 響應

成功響應

返回一個聊天補全物件，包含以下欄位：

`content`

型別：物件陣列
必需：是

模型生成的內容，由多個內容塊組成。每個內容塊都有一個確定其形狀的 type。內容塊可以是以下型別之一：

文字內容塊 (Text)

{
  "type": "text", // 必需，列舉值: "text"，預設值
  "text": "你好，我是 Claude。" // 必需，最大長度: 5000000，最小長度: 1
}

工具使用內容塊 (Tool Use)

{
  "type": "tool_use", // 必需，列舉值: "tool_use"，預設值
  "id": "toolu_xyz...", // 必需，工具使用的唯一識別符號
  "name": "get_weather", // 必需，工具名稱，最小長度: 1
  "input": {
    // 必需，工具的輸入引數物件
    // 工具輸入引數，具體格式由工具的 input_schema 定義
  }
}

示例：

// 文字內容示例
[{"type": "text", "text": "你好，我是 Claude。"}]

// 工具使用示例
[{
  "type": "tool_use",
  "id": "toolu_xyz...",
  "name": "get_weather",
  "input": { "location": "北京" }
}]

// 混合內容示例
[
  {"type": "text", "text": "根據天氣查詢結果："},
  {
    "type": "tool_use",
    "id": "toolu_xyz...",
    "name": "get_weather",
    "input": { "location": "北京" }
  }
]

如果請求的最後一條訊息是助手角色，響應內容會直接從該訊息繼續。例如：

// 請求
[
  {"role": "user", "content": "太陽的希臘語名字是什麼? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "正確答案是 ("}
]

// 響應
[{"type": "text", "text": "B)"}]

`id`

型別：字串
必需：是

響應的唯一識別符號。

`model`

型別：字串
必需：是

使用的模型名稱。

`role`

型別：列舉字串
必需：是
預設值：assistant

生成訊息的會話角色，始終為 "assistant"。

`stop_reason`

型別：列舉字串或 null
必需：是

停止生成的原因，可能的值包括：

"end_turn": 模型達到自然停止點
"max_tokens": 超過請求的 max_tokens 或模型的最大限制
"stop_sequence": 生成了自定義停止序列之一
"tool_use": 模型呼叫了一個或多個工具

在非流式模式下，此值始終非空。在流式模式下，在 message_start 事件中為 null，其他情況下非空。

`stop_sequence`

型別：字串或 null
必需：是

生成的自定義停止序列。如果模型遇到了 stop_sequences 引數中指定的某個序列，這個欄位將包含該匹配的停止序列。如果不是因為停止序列而停止，則為 null。

`type`

型別：列舉字串
必需：是
預設值：message
可選值：message

物件型別，對於 Messages 始終為 "message"。

`usage`

型別：物件
必需：是

計費和限流相關的使用量統計。包含以下欄位：

input_tokens: 使用的輸入 token 數量，必需，範圍 x >` 0
output_tokens: 使用的輸出 token 數量，必需，範圍 x > 0
cache_creation_input_tokens: 建立快取條目使用的輸入 token 數量(如果適用)，必需，範圍 x > 0
cache_read_input_tokens: 從快取讀取的輸入 token 數量(如果適用)，必需，範圍 x > 0

注意：由於 API 在內部會對請求進行轉換和解析，token 計數可能與請求和響應的實際可見內容不完全對應。例如，即使是空字串響應，output_tokens 也會是非零值。

錯誤響應

當請求出現問題時，API 將返回一個錯誤響應物件，HTTP 狀態碼在 4XX-5XX 範圍內。

常見錯誤狀態碼

401 Unauthorized: API 金鑰無效或未提供
400 Bad Request: 請求引數無效
429 Too Many Requests: 超出 API 呼叫限制
500 Internal Server Error: 伺服器內部錯誤

錯誤響應示例:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API key provided",
    "code": "invalid_api_key"
  }
}

主要錯誤型別:

invalid_request_error: 請求引數錯誤
authentication_error: 認證相關錯誤
rate_limit_error: 請求頻率超限
server_error: 伺服器內部錯誤

目錄