火山方舟
火山方舟
API参考
请输入
- 文档首页
火山方舟Messages API创建 Message
复制全文
下载 pdf创建 Message
文档反馈
问问助手POST https://ark.cn-beijing.volces.com/api/compatible/v1/messages
根据输入的消息列表创建一条新的 Message，返回模型生成的下一条消息。本接口为无状态接口，多轮对话时每次请求都需传入完整的消息历史。
鉴权
- 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），用于指定处理输入内容的模型。
说明
- 开通模型服务并查询 Model ID，请参见 模型列表。
- 若需要多个应用分别调用模型服务或做更细粒度的权限管理，可改传 Endpoint ID（在线推理接入点的 ID），详细请参考 获取 Endpoint 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。
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。
说明
当前仅 deepseek-v4-1-flash-261017、deepseek-v4-1-flash-economy-261017 模型支持返回该字段。
request_id string | 请求 ID
MessagesErrorResponse.request_id
错误响应对应请求的唯一标识。
说明
当前仅 deepseek-v4-1-flash-261017、deepseek-v4-1-flash-economy-261017 模型支持返回该字段。
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。
基础文本对话
流式输出
深度思考
图片理解
Function Calling
结构化输出
发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！
Request
cURL
curl https://ark.cn-beijing.volces.com/api/compatible/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $ARK_API_KEY" \
-d '{
"model": "doubao-seed-2-1-pro-260915",
"max_tokens": 256,
"messages": [
{
"role": "user",
"content": "请用一句中文解释什么是向量数据库。"
}
]
}'Response
{
"id": "msg_0217****",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "向量数据库是一类专门存储、索引并检索向量嵌入的数据系统，常用于语义检索、RAG 和相似度匹配。"
}
],
"model": "doubao-seed-2-1-pro-260915",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 31,
"output_tokens": 33,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 139
}
}最近更新时间：2026.10.19 23:25:34
这个页面对您有帮助吗？
有用
有用
无用
无用