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
其中 {WorkspaceId} 为您的业务空间 ID,可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。
  • 华北2(北京)
  • 新加坡
  • 美国(弗吉尼亚)
  • 德国(法兰克福)
  • 日本(东京)
SDK 调用配置的 base_urlhttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropicHTTP 请求地址:POST https://{WorkspaceId}.cn-beijing.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、qwen3.8-flash:模型回复内容和思维链内容之和的最大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(Base64 编码)。url string图片的公网地址。当 typeurl 时必填。media_type string图片的 MIME 类型,如 image/jpeg。当 typebase64 时必填。data stringBase64 编码的图片数据。当 typebase64 时必填。
视频信息(需使用视觉模型)
type string (必选)固定为 videosource object (必选)视频数据来源。
type string (必选)取值:url(公网视频地址)、base64(Base64 编码)。url string视频的公网地址。当 typeurl 时必填。media_type string视频的 MIME 类型,如 video/mp4。当 typebase64 时必填。data stringBase64 编码的视频数据。当 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、qwen3.8-flash、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/qwen3.8-flash(默认值为 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"),
    base_url="https://{WorkspaceId}.cn-beijing.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)以跳过自动发现。