POST https://ark.cn-beijing.volces.com/api/compatible/v1/messages
根据输入的消息列表创建一条新的 Message，返回模型生成的下一条消息。本接口为无状态接口，多轮对话时每次请求都需传入完整的消息历史。
鉴权#
本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数#
Body 参数#
messages object[] 必选 | 消息列表
content string / object[] 必选 | 消息内容
messages.content
纯文本消息内容 string
结构化消息内容 object[]
文本内容块 object
text string 必选 | 文本内容
messages.content.text
type string 必选 | 内容块类型
messages.content.type
取值固定为 text。
思考内容块 object
type string 必选 | 内容块类型
messages.content.type
取值固定为 thinking。
signature string | 用于回放思考内容的不透明签名
messages.content.signature
当 type=thinking 时必填，用于标识并校验该思考内容块。需将该字段与 thinking 字段一起完整回传，并保持字段值及内容块顺序不变。
thinking string | 模型的思考内容
messages.content.thinking
图片内容块 object
source object 必选 | 图片来源
messages.content.source
type string 必选 | 图片传入方式
messages.content.source.type
type=url：url为必填。type=base64：data和media_type为必填。
data string | 图片数据
messages.content.source.data
当 type=base64 时传入。
media_type string | 媒体类型
messages.content.source.media_type
当 type=base64 时，与 data 一起传入。
url string | 图片 URL
messages.content.source.url
当 type=url 时传入。
type string 必选 | 内容块类型
messages.content.type
取值固定为 image。
文档内容块 object
source object 必选 | 文档来源
messages.content.source
type string 必选 | 文档传入方式
messages.content.source.type
支持通过 url、base64、text 或 content 四种方式传入文档。
type=url：url为必填。type=base64或type=text：data为必填。type=content：content为必填。
content string / object[] | 文档内容
messages.content.source.content
当 type=content 时传入。
该字段支持递归嵌套。为避免重复展示，此处不再继续展开。
data string | 文档数据
messages.content.source.data
当 type 为 base64 或 text 时传入。
url string | 文档 URL
messages.content.source.url
当 type=url 时传入。
type string 必选 | 内容块类型
messages.content.type
取值固定为 document。
工具调用内容块 object
id string 必选 | 工具调用的 ID
messages.content.id
input object 必选 | 模型为该工具生成的输入参数
messages.content.input
name string 必选 | 被调用的工具名称
messages.content.name
type string 必选 | 内容块类型
messages.content.type
取值固定为 tool_use。
工具结果内容块 object
content string / object[] 必选 | 工具返回的内容
messages.content.content
纯文本工具结果 string
结构化工具结果 object[]
文本内容块 object
text string 必选 | 文本内容
messages.content.content.text
type string 必选 | 内容块类型
messages.content.content.type
取值固定为 text。
图片内容块 object
source object 必选 | 图片来源
messages.content.content.source
type string 必选 | 图片传入方式
messages.content.content.source.type
type=url：url为必填。type=base64：data和media_type为必填。
data string | 图片数据
messages.content.content.source.data
当 type=base64 时传入。
media_type string | 媒体类型
messages.content.content.source.media_type
当 type=base64 时，与 data 一起传入。
url string | 图片 URL
messages.content.content.source.url
当 type=url 时传入。
type string 必选 | 内容块类型
messages.content.content.type
取值固定为 image。
工具引用内容块 object
tool_name string 必选 | 引用的工具名称
messages.content.content.tool_name
type string 必选 | 内容块类型
messages.content.content.type
取值固定为 tool_reference。
tool_use_id string 必选 | 该结果所对应的工具调用 ID
messages.content.tool_use_id
type string 必选 | 内容块类型
messages.content.type
取值固定为 tool_result。
服务端工具调用内容块 object
id string 必选 | 服务端托管工具调用的公开 ID
messages.content.id
input object 必选 | 模型为该工具生成的输入参数
messages.content.input
name string 必选 | 被调用的服务端托管工具名称
messages.content.name
type string 必选 | 内容块类型
messages.content.type
取值固定为 server_tool_use。
联网搜索结果内容块 object
content object[] / object 必选 | 联网搜索结果内容
messages.content.content
联网搜索结果列表 object[]
encrypted_content string 必选 | 加密内容
messages.content.content.encrypted_content
title string 必选 | 结果标题
messages.content.content.title
type string 必选 | 结果类型
messages.content.content.type
取值固定为 web_search_result。
url string 必选 | 结果 URL
messages.content.content.url
page_age string | 页面时效
messages.content.content.page_age
联网搜索错误结果 object
error_code string 必选 | 错误码
messages.content.content.error_code
type string 必选 | 结果类型
messages.content.content.type
取值固定为 web_search_tool_result_error。
tool_use_id string 必选 | 该结果所对应的服务端工具调用 ID
messages.content.tool_use_id
type string 必选 | 内容块类型
messages.content.type
取值固定为 web_search_tool_result。
caller object | 服务端调用方
messages.content.caller
type string 必选 | 标识生成该结果的服务端调用方
messages.content.caller.type
role string 必选 | 角色
messages.role
输入消息的角色，决定指令的优先级层级。可选值：user、system、assistant、developer。
model string 必选 | 模型 ID
本次请求调用的模型 ID（Model ID），用于指定处理输入内容的模型。
max_tokens integer | 最大输出 token 数
output_config object | 输出配置
effort string | 思考深度
output_config.effort
限制思考的工作量。减少思考深度可提升速度，思考花费的 token 更少。
none：关闭思考。minimal：关闭思考，直接回答。low：轻量思考，侧重快速响应。medium：均衡模式，兼顾速度与深度。high：深度分析，处理复杂问题。xhigh：更高程度思考。max：最高程度思考，适配高难度推理任务。
output_format object | 输出格式
type string 必选 | 输出格式类型
output_format.type
支持 text、json_object 和 json_schema 三种输出格式。
text：返回文本格式结果。json_object：返回 JSON 对象格式结果。json_schema：按 JSON Schema 约束返回结果，此时schema为必填。
schema object | JSON Schema
output_format.schema
当 type=json_schema 时传入。
stop_sequences string / string[] | 停止序列
支持传入单个字符串，或最多 4 个停止序列。
stream boolean | 响应内容是否流式返回
true：按 SSE 协议逐块返回模型生成内容。false：模型生成完成后一次性返回结果。
system string / object[] | 系统提示词
支持直接传字符串，或传由 text 内容块组成的数组。
纯文本系统提示词 string
结构化系统提示词 object[]
text string 必选 | 文本内容
system.text
type string 必选 | 内容块类型
system.type
取值固定为 text。
temperature number | 采样温度
取值范围：[0, 2]
thinking object | 深度思考配置
type string 必选 | 思考模式
thinking.type
disabled：关闭深度思考。enabled：开启深度思考。adaptive：由模型自动决定是否开启深度思考。
tool_choice object | 工具调用策略
配置 tools 后再设置该参数。
自动选择是否调用工具 object
type string 必选 | 策略类型
tool_choice.type
取值固定为 auto。
disable_parallel_tool_use boolean | 是否禁用并行工具调用
tool_choice.disable_parallel_tool_use
true：模型在同一轮中不会并行调用多个工具。false：模型可在同一轮中并行调用多个工具。
当前不保证一定会调用工具，不同模型的保障效果不同 object
type string 必选 | 策略类型
tool_choice.type
取值固定为 any。
disable_parallel_tool_use boolean | 是否禁用并行工具调用
tool_choice.disable_parallel_tool_use
true：模型在同一轮中不会并行调用多个工具。false：模型可在同一轮中并行调用多个工具。
不调用工具 object
type string 必选 | 策略类型
tool_choice.type
取值固定为 none。
强制调用指定工具 object
name string 必选 | 模型必须调用的工具名称
tool_choice.name
type string 必选 | 策略类型
tool_choice.type
取值固定为 tool。
disable_parallel_tool_use boolean | 是否禁用并行工具调用
tool_choice.disable_parallel_tool_use
true：模型在同一轮中不会并行调用多个工具。false：模型可在同一轮中并行调用多个工具。
tools object[] | 工具列表
用户自定义工具 object
name string 必选 | 工具名称
tools.name
description string | 工具说明
tools.description
描述工具的用途以及模型应在何时调用。
input_schema object | 工具输入 Schema
tools.input_schema
服务端工具 object
当前仅支持原生联网搜索 web_search。
type string 必选 | 工具类型
tools.type
兼容 Anthropic 原生 Web Search 工具的版本化类型值。例如：web_search_20250305。
具体可用版本请参见 Anthropic Web Search 工具文档。
name string | 工具名称
tools.name
当前服务端工具可填写 web_search。
max_uses integer | 最大调用次数
tools.max_uses
allowed_domains string[] | 允许访问的域名列表
tools.allowed_domains
blocked_domains string[] | 禁止访问的域名列表
tools.blocked_domains
user_location object | 用户位置信息
tools.user_location
当前传入该参数会被忽略，不生效。
top_p number | 核采样概率
取值范围：[0, 1]
响应参数#
非流式调用响应#
content object[] | 模型生成的内容
文本内容块 object
text string | 文本内容
content.text
type string | 内容块类型
content.type
取值固定为 text。
思考内容块 object
thinking string | 思考内容
content.thinking
type string | 内容块类型
content.type
取值固定为 thinking。
signature string | 用于回放思考内容的不透明签名
content.signature
当 type=thinking 时必填，用于标识并校验该思考内容块。需将该字段与 thinking 字段一起完整回传，并保持字段值及内容块顺序不变。
工具调用内容块 object
id string | 工具调用 ID
content.id
input object | 工具输入参数
content.input
name string | 工具名称
content.name
type string | 内容块类型
content.type
取值固定为 tool_use。
服务端工具调用内容块 object
id string | 服务端工具调用 ID
content.id
input object | 工具输入参数
content.input
name string | 工具名称
content.name
type string | 内容块类型
content.type
取值固定为 server_tool_use。
联网搜索结果内容块 object
content object[] / object | 联网搜索结果内容
content.content
联网搜索结果列表 object[]
encrypted_content string | 加密内容
content.content.encrypted_content
title string | 结果标题
content.content.title
type string | 结果类型
content.content.type
取值固定为 web_search_result。
url string | 结果 URL
content.content.url
page_age string | 页面时效
content.content.page_age
联网搜索错误结果 object
error_code string | 错误码
content.content.error_code
type string | 结果类型
content.content.type
取值固定为 web_search_tool_result_error。
tool_use_id string | 对应的工具调用 ID
content.tool_use_id
type string | 内容块类型
content.type
取值固定为 web_search_tool_result。
caller object | 服务端调用方
content.caller
type string | 标识生成该结果的服务端调用方
content.caller.type
id string | 响应对象的唯一标识
model string | 生成本次响应所使用的模型
role string | 响应角色
取值固定为 assistant。
type string | 响应对象类型
取值固定为 message。
service_status object | 服务状态信息
model_fallback object | 模型回退状态
service_status.model_fallback
fallback_triggered boolean | 本次请求是否触发了模型回退
service_status.model_fallback.fallback_triggered
true：本次请求触发了模型回退，实际使用的模型可能与原始请求不同。false：本次请求未触发模型回退，按原始请求模型处理。
original_model string | 触发回退前原始请求的模型
service_status.model_fallback.original_model
stop_reason string | 模型停止生成 token 的原因
stop_sequence string | 命中的停止序列
实际触发的自定义停止序列。若未命中，则不返回该字段。
usage object | 本次请求的用量统计信息
cache_creation_input_tokens integer | 创建缓存计费的tokens数
usage.cache_creation_input_tokens
创建缓存计费的tokens数，当前暂不支持该计费方式，因此该字段返回为0。
cache_read_input_tokens integer | 从预填充缓存中读取的提示词 token 数
usage.cache_read_input_tokens
input_tokens integer | 提示词消耗的 token 数
usage.input_tokens
iterations object[] | 每次模型迭代对应的一条 token 用量记录
usage.iterations
cache_read_input_tokens integer | 当前模型迭代命中的缓存输入 token 数
usage.iterations.cache_read_input_tokens
input_tokens integer | 当前模型迭代消耗的输入 token 数
usage.iterations.input_tokens
output_tokens integer | 当前模型迭代生成的输出 token 数
usage.iterations.output_tokens
type string | 单次迭代用量记录的类型
usage.iterations.type
output_tokens integer | 生成内容消耗的输出 token 数
usage.output_tokens
server_tool_use object | 服务端托管工具发起的请求次数统计
usage.server_tool_use
web_fetch_requests integer | 服务端托管工具发起的网页抓取请求次数
usage.server_tool_use.web_fetch_requests
web_search_requests integer | 服务端托管工具发起的联网搜索请求次数
usage.server_tool_use.web_search_requests
流式调用响应#
ContentBlockStart object | 内容块开始事件
content_block object | 内容块起始数据
ContentBlockStart.content_block
文本内容块 object
text string | 文本内容
ContentBlockStart.content_block.text
type string | 内容块类型
ContentBlockStart.content_block.type
取值固定为 text。
思考内容块 object
thinking string | 思考内容
ContentBlockStart.content_block.thinking
type string | 内容块类型
ContentBlockStart.content_block.type
取值固定为 thinking。
signature string | 用于回放思考内容的不透明签名
ContentBlockStart.content_block.signature
当 type=thinking 时必填，用于标识并校验该思考内容块。需将该字段与 thinking 字段一起完整回传，并保持字段值及内容块顺序不变。
工具调用内容块 object
id string | 工具调用 ID
ContentBlockStart.content_block.id
input object | 工具输入参数
ContentBlockStart.content_block.input
name string | 工具名称
ContentBlockStart.content_block.name
type string | 内容块类型
ContentBlockStart.content_block.type
取值固定为 tool_use。
服务端工具调用内容块 object
id string | 服务端工具调用 ID
ContentBlockStart.content_block.id
input object | 工具输入参数
ContentBlockStart.content_block.input
name string | 工具名称
ContentBlockStart.content_block.name
type string | 内容块类型
ContentBlockStart.content_block.type
取值固定为 server_tool_use。
联网搜索结果内容块 object
content object[] / object | 联网搜索结果内容
ContentBlockStart.content_block.content
联网搜索结果列表 object[]
encrypted_content string | 加密内容
ContentBlockStart.content_block.content.encrypted_content
title string | 结果标题
ContentBlockStart.content_block.content.title
type string | 结果类型
ContentBlockStart.content_block.content.type
取值固定为 web_search_result。
url string | 结果 URL
ContentBlockStart.content_block.content.url
page_age string | 页面时效
ContentBlockStart.content_block.content.page_age
联网搜索错误结果 object
error_code string | 错误码
ContentBlockStart.content_block.content.error_code
type string | 结果类型
ContentBlockStart.content_block.content.type
取值固定为 web_search_tool_result_error。
tool_use_id string | 对应的工具调用 ID
ContentBlockStart.content_block.tool_use_id
type string | 内容块类型
ContentBlockStart.content_block.type
取值固定为 web_search_tool_result。
caller object | 服务端调用方
ContentBlockStart.content_block.caller
type string | 标识生成该结果的服务端调用方
ContentBlockStart.content_block.caller.type
index integer | 内容块在消息内容数组中的下标
ContentBlockStart.index
type string | 事件类型
ContentBlockStart.type
取值固定为 content_block_start。
MessagesErrorResponse object | 错误事件
error object | 错误详情
MessagesErrorResponse.error
code string | 机器可读的错误码
MessagesErrorResponse.error.code
message string | 面向用户的错误描述
MessagesErrorResponse.error.message
param string | 触发错误的参数名；如果不适用则不返回
MessagesErrorResponse.error.param
type string | 错误类型
MessagesErrorResponse.error.type
type string | 事件类型
MessagesErrorResponse.type
取值固定为 error。
MessagesResponseContentBlock object | 内容块增量事件
delta object | 内容块增量数据
MessagesResponseContentBlock.delta
文本增量 object
text string | 本次追加的文本内容
MessagesResponseContentBlock.delta.text
type string | 增量类型
MessagesResponseContentBlock.delta.type
取值固定为 text_delta。
思考内容增量 object
thinking string | 本次追加的思考内容
MessagesResponseContentBlock.delta.thinking
type string | 增量类型
MessagesResponseContentBlock.delta.type
取值固定为 thinking_delta。
思考签名增量 object
signature string | 本次追加的签名内容
MessagesResponseContentBlock.delta.signature
type string | 增量类型
MessagesResponseContentBlock.delta.type
取值固定为 signature_delta。
工具输入 JSON 增量 object
partial_json string | 本次追加的 JSON 片段
MessagesResponseContentBlock.delta.partial_json
type string | 增量类型
MessagesResponseContentBlock.delta.type
取值固定为 input_json_delta。
index integer | 内容块在消息内容数组中的下标
MessagesResponseContentBlock.index
type string | 事件类型
MessagesResponseContentBlock.type
取值固定为 content_block_delta。
MessagesResponseContentBlockStop object | 内容块结束事件
index integer | 内容块在消息内容数组中的下标
MessagesResponseContentBlockStop.index
type string | 事件类型
MessagesResponseContentBlockStop.type
取值固定为 content_block_stop。
MessagesResponseStreamMessageDelta object | 消息增量事件
delta object | 消息增量内容
MessagesResponseStreamMessageDelta.delta
stop_reason string | 停止原因
MessagesResponseStreamMessageDelta.delta.stop_reason
stop_sequence object | 命中的停止序列
MessagesResponseStreamMessageDelta.delta.stop_sequence
type string | 事件类型
MessagesResponseStreamMessageDelta.type
取值固定为 message_delta。
usage object | 当前增量对应的用量信息
MessagesResponseStreamMessageDelta.usage
MessagesResponseStreamMessageStart object | 消息开始事件
message object | 初始消息对象
MessagesResponseStreamMessageStart.message
content string[] | 消息内容块列表
MessagesResponseStreamMessageStart.message.content
id string | 消息 ID
MessagesResponseStreamMessageStart.message.id
model string | 实际使用的模型
MessagesResponseStreamMessageStart.message.model
role string | 响应角色
MessagesResponseStreamMessageStart.message.role
取值固定为 assistant。
stop_reason object | 停止原因
MessagesResponseStreamMessageStart.message.stop_reason
stop_sequence object | 命中的停止序列
MessagesResponseStreamMessageStart.message.stop_sequence
type string | 对象类型
MessagesResponseStreamMessageStart.message.type
取值固定为 message。
usage object | 当前消息的用量统计
MessagesResponseStreamMessageStart.message.usage
service_status object | 服务状态
MessagesResponseStreamMessageStart.message.service_status
model_fallback object | 模型回退状态
MessagesResponseStreamMessageStart.message.service_status.model_fallback
fallback_triggered boolean | 本次请求是否触发了模型回退
MessagesResponseStreamMessageStart.message.service_status.model_fallback.fallback_triggered
true：本次请求触发了模型回退，实际使用的模型可能与原始请求不同。false：本次请求未触发模型回退，按原始请求模型处理。
original_model string | 触发回退前原始请求的模型
MessagesResponseStreamMessageStart.message.service_status.model_fallback.original_model
type string | 事件类型
MessagesResponseStreamMessageStart.type
取值固定为 message_start。
MessagesResponseStreamMessageStop object | 消息结束事件
type string | 事件类型
MessagesResponseStreamMessageStop.type
取值固定为 message_stop。