# 创建 Message

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volces.com/api/compatible/v1/messages`

根据输入的消息列表创建一条新的 Message，返回模型生成的下一条消息。本接口为无状态接口，多轮对话时每次请求都需传入完整的消息历史。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。

---

<span id="request-parameters"></span>
## 请求参数

### 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，请参见 [模型列表](/docs/model-list)。
> - 若需要多个应用分别调用模型服务或做更细粒度的权限管理，可改传 Endpoint ID（在线推理接入点的 ID），详细请参考 [获取 Endpoint ID](https://ark.volcengine.com/region:cn-beijing/docs/create-standard-inference-endpoint)。

**max_tokens** `integer` | 最大输出 token 数

**output_config** `object` | 输出配置

**effort** `string` | 思考深度

`output_config.effort`

限制思考的工作量。减少思考深度可提升速度，思考花费的 token 更少。

* `none`：关闭思考。
* `minimal`：关闭思考，直接回答。
* `low`：轻量思考，侧重快速响应。
* `medium`：均衡模式，兼顾速度与深度。
* `high`：深度分析，处理复杂问题。
* `xhigh`：更高程度思考。
* `max`：最高程度思考，适配高难度推理任务。

> **注意：说明**
>
> 支持该字段的模型、默认取值、参数兼容映射规则，以及与 `thinking.type` 字段的关系，详见 [文档](/docs/deep-thinking)。

**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` 时传入。

**service_tier** `string` `默认值 default` | 推理模式

控制使用的在线推理模式。

- `default`：使用 [在线推理（常规）](/docs/online-inference-standard)。
- `flex`：使用 [在线推理（低优）](/docs/online-inference-flex)。

**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 工具文档](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)。

**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`。


## 代码示例

## 基础文本对话

### cURL


#### Request

```bash
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
  }
}
```

## 流式输出

### cURL


#### Request

```bash
curl -N 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,
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "请用一句中文介绍什么是向量数据库。"
      }
    ]
  }'
```

#### Response

```
event: message_start
data: {"type":"message_start","message":{"id":"msg_0217****","type":"message","role":"assistant","content":[],"model":"doubao-seed-2-1-pro-260915","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":31,"output_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":139}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"向量数据库是一类用于存储、索引和检索向量嵌入的数据系统。"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":31,"output_tokens":30,"cache_creation_input_tokens":0,"cache_read_input_tokens":139}}

event: message_stop
data: {"type":"message_stop"}
```

## 深度思考

### cURL


#### Request

```bash
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": 512,
    "thinking": {
      "type": "enabled"
    },
    "output_config": {
      "effort": "medium"
    },
    "messages": [
      {
        "role": "user",
        "content": "请比较向量数据库和关系型数据库各自更适合哪些场景。"
      }
    ]
  }'
```

#### Response

```
{
  "id": "msg_0217****",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "用户在比较两类数据库的适用场景，需要先从数据结构、查询方式和典型用途几个维度来拆解。",
      "signature": "sig_0217****"
    },
    {
      "type": "text",
      "text": "向量数据库更适合语义检索、RAG 和相似度匹配；关系型数据库更适合结构化数据存储、事务处理和精确条件查询。"
    }
  ],
  "model": "doubao-seed-2-1-pro-260915",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 48,
    "output_tokens": 82,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 139
  }
}
```

## 图片理解

### cURL


#### Request

```bash
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": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://arkdocs.tos-cn-beijing.volces.com/images/advanced-usage/view.jpeg"
            }
          },
          {
            "type": "text",
            "text": "请描述这张图片中的主要内容。"
          }
        ]
      }
    ]
  }'
```

#### Response

```
{
  "id": "msg_0217****",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "图片展示了一名划着橙色皮划艇的人，周围是平静的湖面、树林和远处覆雪的山峰，整体是安静的自然风景。"
    }
  ],
  "model": "doubao-seed-2-1-pro-260915",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 521,
    "output_tokens": 47,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 139
  }
}
```

## Function Calling

### cURL


#### Request

```bash
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": 512,
    "tool_choice": {
      "type": "auto"
    },
    "tools": [
      {
        "name": "get_weather",
        "description": "查询指定城市的天气信息",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市名称，例如北京"
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ]
            }
          },
          "required": [
            "location"
          ],
          "additionalProperties": false
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "请帮我查询北京今天的天气。"
      }
    ]
  }'
```

#### Response

```
{
  "id": "msg_0217****",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_0217****",
      "name": "get_weather",
      "input": {
        "location": "北京",
        "unit": "celsius"
      }
    }
  ],
  "model": "doubao-seed-2-1-pro-260915",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 146,
    "output_tokens": 28,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 139
  }
}
```

## 结构化输出

### cURL


#### Request

```bash
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,
    "output_format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "书名"
          },
          "author": {
            "type": "string",
            "description": "作者"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "标签"
          }
        },
        "required": [
          "name",
          "author",
          "tags"
        ],
        "additionalProperties": false
      }
    },
    "messages": [
      {
        "role": "user",
        "content": "请将《三体》整理为 JSON，包含 name、author、tags 三个字段。"
      }
    ]
  }'
```

#### Response

```
{
  "id": "msg_0217****",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "{\"name\":\"三体\",\"author\":\"刘慈欣\",\"tags\":[\"科幻\",\"长篇小说\"]}"
    }
  ],
  "model": "doubao-seed-2-1-pro-260915",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 58,
    "output_tokens": 25,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 139
  }
}
```