Skip to main content
文本產生

Anthropic相容-Messages

通過相容 Anthropic 格式的 Messages API 呼叫模型,查看輸入輸出參數說明及調用樣本。

通過修改以下配置,即可將原有的 Anthropic 應用遷移至阿里雲百鍊:
  • api_key:替換為百鍊 API Key
  • base_url:替換為百鍊的相容端點地址(見下方接入資訊)。
  • model:替換為百鍊支援的模型名稱(例如 qwen3.7-plus)。
阿里雲百鍊為華北2(北京)、新加坡、中國香港地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
  • 華北2(北京)地區:從 https://dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區:從 https://dashscope-intl.aliyuncs.com 遷移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
  • 中國香港地區:從 https://cn-hongkong.dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com
其中 {WorkspaceId} 為您的業務空間 ID,可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。
  • 新加坡
  • 華北2(北京)
  • 美國(維吉尼亞)
  • 德國(法蘭克福)
  • 日本(東京)
SDK 調用配置的 base_urlhttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropicHTTP 要求地址:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1/messages
調用時請將{WorkspaceId}替換為真實的業務空間ID 認證方式:通過 x-api-key 要求標頭或 Authorization: Bearer 要求標頭傳入百鍊 API Key,二者選其一即可。

與 Anthropic 官方 API 的主要差異

以下差異點匯總自本文本文,從 Anthropic 官方遷移時請重點確認:

差異項

說明

接入地址(Base URL)

base_url 需替換為百鍊相容端點(形如 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic,各地區地址見上方接入資訊),其中 {WorkspaceId} 需替換為真實的業務空間 ID。

鑒權方式

api_key 需替換為百鍊 API Key;支援通過 x-api-keyAuthorization: Bearer 要求標頭傳入,二者選其一即可。

模型名稱

model 需替換為百鍊支援的模型名稱(例如 qwen3.7-plus),完整列表見下方 model 參數說明。

temperature 取值範圍

百鍊取值範圍為 [0, 2),與 Anthropic 官方的 [0.0, 1.0] 不同,遷移時請確認該參數取值。

介面範圍

僅提供 Messages 介面(/v1/messages),不提供模型列表介面(/v1/models);用戶端的模型發現請求會返回 404,處理方式見下方常見問題。

擴充參數

output_config(結構化輸出與思考強度 effort)為百鍊平台擴充參數,官方 SDK 類型定義中不包含,需在請求體中透傳(見右側“結構化輸出”樣本);thinking.budget_tokens 即將廢棄,新接入建議使用 output_config.effort 控制思考強度。

請求體

model string (必選)模型名稱,支援範圍如下。
千問Max:qwen3.8-max、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.7-max-2026-06-08、qwen3.6-max-preview、qwen3-max、qwen3-max-2026-01-23、qwen3-max-preview千問Plus:qwen3.7-plus、qwen3.7-plus-2026-05-26、qwen3.6-plus、qwen3.6-plus-2026-04-02、qwen3.5-plus、qwen3.5-plus-2026-04-20、qwen3.5-plus-2026-02-15、qwen-plus、qwen-plus-latest、qwen-plus-2025-09-11千問Flash:qwen3.8-flash、qwen3.7-flash、qwen3.7-flash-2026-07-15、qwen3.6-flash、qwen3.6-flash-2026-04-16、qwen3.5-flash、qwen3.5-flash-2026-02-23、qwen-flash、qwen-flash-2025-07-28千問Turbo:qwen-turbo千問Coder:qwen3-coder-next、qwen3-coder-plus、qwen3-coder-plus-2025-09-23、qwen3-coder-flash千問VL:qwen3-vl-plus、qwen3-vl-flash、qwen-vl-max、qwen-vl-plus千問開源模型:qwen3.6-27b、qwen3.5-397b-a17b、qwen3.5-122b-a10b、qwen3.5-27b、qwen3.5-35b-a3b、qwen3.8-2.4t-a95b、qwen3.8-27b第三方模型deepseek-v4-pro、deepseek-v4-pro-0813、deepseek-v4-flash、deepseek-v4-flash-0731、deepseek-v3.2、kimi-k3、kimi-k2.7-code、kimi-k2.6、kimi-k2.5、kimi-k2-thinking、glm-5.2、glm-5.1、glm-5、glm-4.7、glm-4.6、MiniMax-M2.5、MiniMax-M2.1
max_tokens integer (必選)
  • deepseek-v4-pro、deepseek-v4-pro-0813、deepseek-v4-flash、deepseek-v4-flash-0731、qwen3.8-max:模型回複內容和思維鏈內容之和的最大Token數,模型輸出超過此值時產生將提前停止,stop_reasonmax_tokens
    max_tokens 限制模型回複內容+思考過程的長度。開啟深度思考時,max_tokens > thinking.budget_tokens
  • glm-5.2:不傳入 thinking.budget_tokens 參數時,max_tokens 為模型回複內容和思維鏈內容之和的最大Token數,模型輸出超過此值時產生將提前停止,stop_reasonmax_tokens;傳入 thinking.budget_tokens 參數時,max_tokens 僅為模型回複內容的最大Token數,思考部分的 Token 數由 thinking.budget_tokens 單獨控制。
  • 其他模型:模型回複內容的最大 Token 數。若產生內容超過此值,產生將提前停止,stop_reasonmax_tokens
    max_tokens 不限制思考過程的長度。開啟深度思考時,思考部分的 Token 數由 thinking.budget_tokens 單獨控制。
system string 或 array (可選)系統提示詞,用於設定模型的角色或行為。傳入字串等價於單個 type="text" 的內容塊。當需要為系統提示詞標記顯式緩衝斷點(參見右側"顯式緩衝"樣本)時,必須傳入數組形式。
type string (必選)固定為 texttext string (必選)系統提示詞文本。cache_control object (可選)在該內容塊上標記顯式緩衝斷點(參見右側"顯式緩衝"樣本),命中後第二次及之後的請求按緩衝讀取計費。僅包含欄位 type,取值固定為 ephemeral
messages array (必選)
role string (必選)訊息角色,可選值:userassistantsystemcontent string 或 array (必選)訊息內容。可以是純文字字串,也可以是結構化內容數組。content 為字串時,等價於單個 type="text" 的內容塊。
文本資訊
type string (必選)固定為 texttext string (必選)常值內容。cache_control object (可選)在該文字區塊上標記顯式緩衝斷點(參見右側"顯式緩衝"樣本)。僅包含欄位 type,取值固定為 ephemeral
圖片資訊(需使用視覺模型)
type string (必選)固定為 imagesource object (必選)圖片資料來源。
type string (必選)取值:url(公網圖片地址)、base64(Base 64 編碼)。url string圖片的公網地址。當 typeurl 時必填。media_type string圖片的 MIME 類型,如 image/jpeg。當 typebase64 時必填。data stringBase 64 編碼的圖片資料。當 typebase64 時必填。
視頻資訊(需使用視覺模型)
type string (必選)固定為 videosource object (必選)視頻資料來源。
type string (必選)取值:url(公網視頻地址)、base64(Base 64 編碼)。url string視頻的公網地址。當 typeurl 時必填。media_type string視頻的 MIME 類型,如 video/mp4。當 typebase64 時必填。data stringBase 64 編碼的視頻資料。當 typebase64 時必填。
工具調用資訊(assistant 角色,模型返回的工具調用指令)
type string (必選)固定為 tool_useid string (必選)工具調用的唯一標識,用於在後續 tool_result 中關連接果。name string (必選)被調用的工具名稱。input object (必選)工具調用的入參,結構由 tools 中對應工具的 input_schema 決定。cache_control object (可選)在該塊上標記顯式緩衝斷點(參見右側"顯式緩衝"樣本)。僅包含欄位 type,取值固定為 ephemeral。工具調用內容本身會參與緩衝首碼。
工具結果資訊(user 角色,工具執行結果回傳給模型)
type string (必選)固定為 tool_resulttool_use_id string (必選)對應 tool_use 資訊中的 idcontent string (必選)工具執行返回的內容。cache_control object (可選)在該工具結果塊上標記顯式緩衝斷點(參見右側"顯式緩衝"樣本)。僅包含欄位 type,取值固定為 ephemeral
stream boolean (可選)是否啟用流式輸出,預設為 falsetemperature number (可選)控制產生文本的多樣性,取值範圍 [0, 2)。值越大,產生結果越隨機。
該範圍與 Anthropic 官方的 [0.0, 1.0] 不同,從 Anthropic 遷移時請確認該參數取值。
top_p number (可選)核採樣的機率閾值,控制產生文本的多樣性。
temperaturetop_p 均可控制產生文本的多樣性,建議只設定其中一個值。更多說明請參見概述
top_k integer (可選)產生過程中採樣候選集的大小。stop_sequences array (可選)指定停止產生的文本序列。模型產生到該序列前會停止輸出,且不包含該序列本身。
命中後,響應的 stop_reason 仍為 end_turn,響應不會回填命中的序列。
thinking object (可選)深度思考配置。開啟後,模型會在產生回複前先進行推理,以提升回答準確度。開啟後,響應會包含 thinking 類型的內容塊。未傳入該參數時,是否進行思考由模型預設行為決定:qwen3.8-max、deepseek-v4 系列、glm 系列預設開啟思考;kimi-k2.6、kimi-k2.5 預設關閉思考;kimi-k2.7-code、kimi-k2-thinking、MiniMax-M2.5、MiniMax-M2.1 僅支援思考模式(無法關閉)。各模型對思考模式的支援情況與預設開關,請參見深度思考
type string (必選)可選值:enabled(開啟思考模式)、disabled(關閉思考模式)。budget_tokens integer (可選,即將廢棄
該參數即將廢棄,並將在後續模型中逐步停止支援,新接入建議使用 effort控制模型的思考強度。
思考過程可使用的最大 Token 數,與 max_tokens 互不重疊:本參數限制思考,max_tokens 限制最終回複。預算越大,在複雜問題上的分析越充分。當 typeenabled 時生效。
tools array (可選)工具定義數組,用於 Function Call 情境。
name string (必選)工具名稱。description string (可選)工具的功能描述。input_schema object (必選)工具輸入參數的 JSON Schema 定義。
tool_choice object (可選)工具選擇策略。支援以下值:
  • {"type": "auto"}:模型自行決定是否調用工具(預設)。
  • {"type": "any"}:強制模型調用任意一個工具。
  • {"type": "none"}:禁止模型調用工具。
  • {"type": "tool", "name": "tool_name"}:強制模型調用指定工具。
output_config object (可選)輸出參數設定。
effort string (可選)控制模型的推理力度。
  • glm-5.2、deepseek-v4-pro、deepseek-v4-flash(預設值為 max): 可選值:
    • high:高力度推理
    • max:最大力度推理
    lowmedium映射為highxhigh映射為max
  • qwen3.8-max(預設值為 xhigh): 可選值:
    • xhigh:高力度推理
    • medium:中力度推理
    • low:低力度推理
    max 、high映射為 xhigh
format object (可選)結構化輸出配置。開啟後,模型將輸出 JSON 字串。不同模型的支援力度不同:
  • 嚴格結構化輸出:適用於 qwen3.8 系列、qwen3.7 系列、deepseek 系列、glm 系列模型。模型嚴格按照傳入的 JSON Schema 進行強約束輸出,確保欄位類型與層級完全一致。
  • 普通結構化輸出:適用於上述以外的其他模型。Schema 的具體欄位約束預設不生效,API 會自動將其轉換為普通 JSON 模式(僅保證輸出為合法的 JSON 字串)。觸發普通 JSON 模式時,請求必須同時滿足以下兩點約束:1、顯式傳入 output_config 參數;2、systemmessages 的內容中必須包含不區分大小寫 "JSON" 關鍵詞。若提示詞中未包含 "JSON" 關鍵詞,API將拋出異常:'messages' must contain the word 'json' in some form
type string (必選)取值固定為 json_schemaschema object (必選)JSON Schema 對象,遵循標準 JSON Schema 規範。需包含 type(資料類型)、properties(欄位定義)、required(必要欄位名數組)、additionalProperties(必須設為 false)等欄位。
  • 基礎調用
  • 流式輸出
  • 深度思考
  • 圖片理解
  • 視頻理解
  • Function Call
  • 顯式緩衝
  • 結構化輸出
Python
import anthropic
import os

client = anthropic.Anthropic(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 請將{WorkspaceId}替換為真實的業務空間ID,各地區URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
)

message = client.messages.create(
    model="qwen3.8-max",
    max_tokens=1024,
    system="You are a helpful assistant",
    messages=[
        {
            "role": "user",
            "content": "你是誰?"
        }
    ],
    thinking={"type": "disabled"},
)

print(message.content[0].text)

非流式響應

id string訊息的唯一標識。type string固定為 messagerole string固定為 assistantmodel string使用的模型名稱。content array內容數組。
文本資訊
type string固定為 texttext string模型產生的文本回複。
思考資訊(開啟深度思考時返回)
type string固定為 thinkingthinking string模型在產生最終回複前的思考過程。signature string當前固定為空白字串。
工具調用資訊(Function Call 情境)
type string固定為 tool_useid string工具調用的唯一標識,用於在後續 tool_result 中關連接果。name string被調用的工具名稱。input object工具調用的入參。
stop_reason string停止原因。可選值:end_turn(正常結束)、max_tokens(達到 Token 上限)、tool_use(工具調用)。stop_sequence string固定為 nullusage objectToken 用量統計。
流式調用中,message_start 事件的 usage 僅包含 input_tokensoutput_tokens;完整 4 個欄位在 message_delta 事件中返回。
input_tokens integer輸入 Token 數量。output_tokens integer輸出 Token 數量。cache_creation_input_tokens integer緩衝建立消耗的輸入 Token 數量。cache_read_input_tokens integer緩衝讀取消耗的輸入 Token 數量。
響應樣本
{
  "id": "msg_e2898f19-fc0e-4cb3-bd9b-5b7dc4ea3bc9",
  "type": "message",
  "role": "assistant",
  "model": "qwen3.8-max",
  "content": [
    {
      "type": "thinking",
      "thinking": "讓我分析一下這個問題...",
      "signature": ""
    },
    {
      "type": "text",
      "text": "你好!我是通義千問..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 22,
    "output_tokens": 223,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

流式響應

message_start流的第一個事件,標記訊息開始。
type string固定為 message_startmessage object初始訊息對象,content 為空白數組,usage 僅含 input_tokensoutput_tokens
content_block_start每個內容塊開始時發送,標記新內容塊的索引和類型。
type string固定為 content_block_startindex integer內容塊索引,從 0 開始,對應該訊息 content 數組中的位置。content_block object內容塊的初始對象。type 取值為 textthinkingtool_usetool_use 類型在此事件中 input 為空白對象,完整入參由後續 content_block_delta 增量拼接。
content_block_delta內容塊的累加式更新事件。同一內容塊會發送多個該事件。
type string固定為 content_block_deltaindex integer所屬內容塊索引。delta object增量對象,type 取值:
  • text_delta:文本增量,含 text 欄位。
  • thinking_delta:思考增量,含 thinking 欄位。
  • signature_delta:簽名增量,含 signature 欄位(當前固定為空白字串)。
  • input_json_delta:工具調用入參增量,含 partial_json 欄位。
content_block_stop內容塊結束事件。
type string固定為 content_block_stopindex integer結束的內容塊索引。
message_delta訊息級更新事件,在所有內容塊結束後發送,包含停止原因和完整的 Token 用量統計。
type string固定為 message_deltadelta object包含 stop_reasonstop_sequence,取值參見上方非流式響應表格。usage object完整的 Token 用量統計,包含 input_tokensoutput_tokenscache_creation_input_tokenscache_read_input_tokens
message_stop流的最後一個事件,標記訊息結束。
type string固定為 message_stop此外,流式響應還會定期發送 ping 事件({"type":"ping"})用於保持串連活躍,用戶端可忽略。
流式響應樣本
{"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","model":"qwen3.8-max","content":[],"usage":{"input_tokens":15,"output_tokens":0}}}
{"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}
{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"Here's a thinking process:\n\n1. **Analyze User Input:**\n   - **Topic:** 人工智慧 (Artificial Intelligence / AI)\n   - **Request:** 請簡單介紹一下人工智慧。"}}
{"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":""}}
{"type":"content_block_stop","index":0}
{"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}
{"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"人工智慧(Artificial Intelligence,簡稱AI)是電腦科學的重要分支..."}}
{"type":"content_block_stop","index":1}
{"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":15,"output_tokens":1078,"cache_creation_input_tokens":0,"cache_read_input_tokens":0}}
{"type":"message_stop"}

常見問題

在 Claude Desktop 或 Claude Code 中配置後,串連測試報錯Model discovery — Gateway /v1/models returned HTTP 404,或請求地址出現/v1/v1/models,如何解決? Claude Desktop、Claude Code 等用戶端的模型發現(model discovery)功能會在配置的 base URL 後自動追加 /v1/models。請按以下兩點排查:
  • base URL 不要以/v1/結尾:應填寫到 /apps/anthropic 為止(例如華北2(北京)填 https://dashscope.aliyuncs.com/apps/anthropic,其餘地區的地址見上方“接入資訊”)。若誤填為 .../apps/anthropic/v1/,用戶端追加 /v1/models 後會形成 /v1/v1/models 的重複路徑,導致 HTTP 404。因此出現 404 時,請先檢查實際請求地址是否出現 /v1/v1/ 重複,若有則去掉 base URL 末尾的 /v1/
  • 手動添加模型以跳過自動探索:百鍊 Anthropic 相容端點僅提供 Messages 介面(/v1/messages),不提供模型列表介面(/v1/models),因此模型發現請求本身也會返回 404。請在用戶端的 Models 中手動添加模型(例如 qwen3.7-plus)以跳過自動探索。
Anthropic相容-Messages - Alibaba Cloud Model Studio