`POST https://ark.cn-beijing.volces.com/api/v3/batch/chat/completions` [运行](https://api.volcengine.com/api-explorer/?action=BatchChatCompletions&data=%7B%7D&groupName=%E6%89%B9%E9%87%8F%E6%8E%A8%E7%90%86&query=%7B%7D&serviceCode=ark&version=2024-01-01) 本文介绍批量推理调用模型服务的 API 的输入输出参数，供您使用接口时查阅字段含义。通过批量推理您可享受到更高的限流配额以及实惠的价格，适合进行大批量数据处理时使用。 > 推荐的调用方式请见 [示例代码](https://ark.volcengine.com/region:cn-beijing/docs/ark/batch-inference#075b8a07)。

说明

Batch Chat API 已标记为待下线。 建议您直接使用 Chat API，并在请求中设置 service_tier=flex，以在线推理（低优）的方式完成批量数据处理。接口参数一致，改造成本低。

对于动态产生的数据、后台任务或其他需要保持同步调用方式的时延不敏感业务，可以迁移至在线推理（低优）。迁移后，使用普通在线推理的预置推理接入点或自定义推理接入点，并在请求中设置 service_tier=flex。

在线推理（低优）支持 Chat API、Responses API 和 Messages API，请根据业务当前使用的 API 协议及所需能力选择迁移后的接口。

注意：doubao\-seed\-2.1 后续模型不再支持调用 Batch Chat API。

快速入口 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2abecd05ca2779567c6d32f0ddc7874d.png) [模型列表](https://ark.volcengine.com/region:cn-beijing/docs/ark/batch-inference) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a5fdd3028d35cc512a10bd71b982b6eb.png) [模型计费](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-pricing#%E6%89%B9%E9%87%8F%E6%8E%A8%E7%90%86) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_afbcf38bdec05c05089d5de5c3fd8fc8.png) [API Key](https://ark.volcengine.com/region:cn-beijing/apiKey?apikey=%7B%7D) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_bef4bc3de3535ee19d0c5d6c37b0ffdd.png) [开通模型](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_57d0bca8e0d122ab1191b40101b5df75.png) [调用教程](https://ark.volcengine.com/region:cn-beijing/docs/ark/batch-inference) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1609c71a747f84df24be1e6421ce58f0.png) [常见问题](https://ark.volcengine.com/region:cn-beijing/docs/ark/modelark-faq) 鉴权说明本接口支持 API Key 与 Access Key鉴权，详见[鉴权认证方式](https://ark.volcengine.com/region:cn-beijing/docs/ark/base-url-and-authentication)。在线调试 [去调试](https://api.volcengine.com/api-explorer/?action=BatchChatCompletions&data=%7B%7D&groupName=%E6%89%B9%E9%87%8F%E6%8E%A8%E7%90%86&query=%7B%7D&serviceCode=ark&version=2024-01-01) --- ## 请求参数 > 跳转 [响应参数](https://ark.volcengine.com/region:cn-beijing/docs/ark/batch-chat-api#PM1q4ttH) ### 请求体 --- **model** `string` `必选` 通过 Endpoint ID 来调用模型，可参考 [获取 Endpoint ID](https://ark.volcengine.com/region:cn-beijing/docs/ark/create-standard-inference-endpoint)。 --- **messages** `object[]` `必选` 到目前为止的对话组成的消息列表。不同模型支持不同类型的消息，如文本、图片、视频等。消息类型 --- **系统消息** `object` 开发人员提供的指令，模型应遵循这些指令。如模型扮演的角色或者目标等。属性 --- messages.**role** `string` `必选` 发送消息的角色，此处应为`system`。 --- messages.**content** `string / object[]` `必选` 系统信息内容。属性 --- **纯文本消息内容** `string` 纯文本消息内容，大语言模型支持传入此类型。 --- **多模态消息内容** `object[]` 支持文本、图像、视频等类型，视觉理解模型等多模态模型、部分大语言模型支持此字段。各模态消息部分 --- **文本消息部分** `object` 多模态消息中，内容文本输入。[具备视觉理解能力模型](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-list#76df97c8)、部分大语言模型支持此类型消息。属性 --- messages.content.**text** `string` `必选` 文本消息部分的内容。 --- messages.content.**type** `string` `必选` 文本消息类型，此处应为 `text`。 --- **图像消息部分** `object` 多模态消息中，图像内容部分。[具备视觉理解能力模型](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-list#76df97c8) 支持此类型消息。属性 --- messages.content.**image_url** `object` `必选` 图片消息的内容部分。属性 --- messages.content.image_url.**url** `string` `必选` 支持传入图片链接或图片的Base64编码，具体使用请参见[使用说明](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-understanding#7a123cd1)。 --- messages.content.image_url.**detail** `string` `默认值 auto` 支持手动设置图片的质量，取值范围`high`、`low`、`auto`。 * `high`：高细节模式，适用于需要理解图像细节信息的场景，如对图像的多个局部信息/特征提取、复杂/丰富细节的图像理解等场景，理解更全面。 * `low`：低细节模式，适用于简单的图像分类/识别、整体内容理解/描述等场景，理解更快速。 * `auto`：默认模式，不同模型选择的模式略有不同，具体请参见 [理解图像的深度控制](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-understanding#bf4d9224)。 --- messages.content.**type** `string` `必选` 图像消息类型，此次应为 `image_url`。 --- **视频消息部分** > 视频理解模型请参见 [视频理解模型](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-list#76df97c8)。多模态消息中，视频内容部分。属性 --- messages.content.**type** `string` `必选` 视频消息类型，此次应为 `video_url`。 --- messages.content.**video_url**`object` `必选` 视频消息的内容部分。属性 --- messages.content.video_url.**url** `string` `必选` 支持传入视频链接或视频的Base64编码。具体使用请参见 [视频理解说明](https://ark.volcengine.com/region:cn-beijing/docs/ark/video-understanding)。 --- messages.content.video_url.**fps** `float/ null` `默认值 1` 取值范围：`[0.2, 5]`。每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，对于视频中画面变化感知减弱，但是使用的 token 花费少，速度也更快。详细说明见 [用量说明](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-understanding#57188ace)。 --- **用户消息** `object` 用户发送的消息，包含提示或附加上下文信息。不同模型支持的字段类型不同，最多支持文本、图片、视频形式的消息。属性 --- messages.**role** `string` `必选` 发送消息的角色，此处应为`user`。 --- messages.**content** `string / object[]` `必选` 用户信息内容。内容类型 --- **纯文本消息内容** `string` 纯文本消息内容，大语言模型支持传入此类型。 --- **多模态消息内容** `object[]` 支持文本、图像、视频等类型，视觉理解模型等多模态模型、部分大语言模型支持此字段。内容类型 --- **文本消息部分** `object` 多模态消息中，内容文本输入。视觉理解模型、部分大语言模型支持此类型消息。属性 --- messages.content.**text** `string` `必选` 文本消息部分的内容。 --- messages.content.**type** `string` `必选` 文本消息类型，此处应为 `text`。 --- **图像消息部分** `object` 多模态消息中，图像内容部分。视觉理解模型支持此类型消息。 **属性** --- messages.content.**type** `string` `必选` 图像消息类型，此次应为 `image_url`。 --- messages.content.**image_url** `object` `必选` 图片消息的内容部分。 **属性** --- messages.content.image_url.**url** `string` `必选` 支持传入图片链接或图片的Base64编码，不同模型支持图片大小略有不同，具体请参见[使用说明](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-understanding#7a123cd1)。 --- messages.content.image_url.**detail** `string / null` `默认值 low` 取值范围：`high`、`low`、`auto`。支持手动设置图片的质量。 * `high`：高细节模式，适用于需要理解图像细节信息的场景，如对图像的多个局部信息/特征提取、复杂/丰富细节的图像理解等场景，理解更全面。此时 **min_pixels** 取值`3136`、**max_pixels** 取值`4014080`。 * `low`：低细节模式，适用于简单的图像分类/识别、整体内容理解/描述等场景，理解更快速。此时 **min_pixels** 取值`3136`、**max_pixels** 取值`1048576`。 * `auto`：默认模式，不同模型选择的模式略有不同，具体请参见 [理解图像的深度控制](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-understanding#bf4d9224)。 --- messages.content.image_url.**image_pixel_limit** `object / null` `默认值 null` 允许设置图片的像素大小限制，如果不在此范围，则会等比例放大或者缩小至该范围内。生效优先级：高于 **detail** 字段，即同时配置 **detail** 与 **image_pixel_limit** 字段时，生效 **image_pixel_limit** 字段配置。若 **min_pixels** / **max_pixels** 字段未设置，使用 **detail** 设置配置的值对应的 **min_pixels** / **max_pixels** 值。子字段取值逻辑：`3136` ≤ **min_pixels** ≤ **max_pixels** ≤ `4014080` --- * messages.content.image_url.image_pixel_limit.**max_pixels** `integer` 取值范围：(**min_pixels**, `4014080`]。传入图片最大像素限制，大于此像素则等比例缩小至 **max_pixels** 字段取值以下。若未设置，则取值为 **detail** 设置配置的值对应的 **max_pixels** 值。 --- * messages.content.image_url.image_pixel_limit.**min_pixels** 取值范围：[`3136`, **max_pixels**)。传入图片最小像素限制，小于此像素则等比例放大至 **min_pixels** 字段取值以上。若未设置，则取值为 **detail** 设置配置的值对应的 **min_pixels** 值（`3136`）。 --- **视频信息部分** `object` > 视频理解模型请参见 [视频理解模型](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-list#76df97c8)。多模态消息中，视频内容部分。属性 --- messages.content.**type** `string` `必选` 视频消息类型，此次应为 `video_url`。 --- messages.content.**video_url**`object` `必选` 视频消息的内容部分。属性 --- messages.content.video_url.**url** `string` `必选` 支持传入视频链接或视频的Base64编码。具体使用请参见 [视频理解说明](https://ark.volcengine.com/region:cn-beijing/docs/ark/video-understanding)。 --- messages.content.video_url.**fps** `float/ null` `默认值 1` 取值范围：`[0.2, 5]`。每秒钟从视频中抽取指定数量的图像。取值越高，对于视频中画面变化理解越精细；取值越低，对于视频中画面变化感知减弱，但是使用的 token 花费少，速度也更快。详细说明见 [用量说明](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-understanding#57188ace)。 --- **模型消息** `object` 历史对话中，模型回复的消息。往往在多轮对话传入历史对话记录以及 [Prefill Response](https://ark.volcengine.com/region:cn-beijing/docs/ark/continuation-mode) 时让模型按照预置的回复内容继续回复时使用。属性

说明

messages.content 与 messages.tool_calls 字段二者至少填写其一。

--- messages.**role** `string` `必选` 发送消息的角色，此处应为`assistant`。 --- messages.**content** `string / array` 模型回复的消息。 --- messages.**tool_calls** `object[]` 历史对话中，模型回复的工具调用信息。显示子字段 --- messages.tool_calls.**function** `object` `必选` 模型调用工具对应的函数信息。显示子字段 --- messages.tool_calls.function.**name** `string` `必选` 模型需要调用的函数名称。 --- messages.tool_calls.function.**arguments** `string` `必选` 模型生成的用于调用函数的参数，JSON 格式。

说明

模型并不总是生成有效的 JSON，并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前，请在您的代码中验证这些参数是否有效。

--- messages.tool_calls.**id** `string` `必选` 调用的工具的 ID。 --- messages.tool_calls.**type** `string` `必选` 工具类型，当前仅支持`function`。 --- **thinking** `object` `默认值 {"type":"enabled"}` 控制模型是否开启深度思考模式。默认开启深度思考模式，可以手动关闭。 > 支持此字段的模型以及使用示例请参见 [文档](https://ark.volcengine.com/region:cn-beijing/docs/ark/deep-thinking#fa3f44fa)。属性 --- thinking.**type** `string` `必选` 取值范围：`enabled`， `disabled`，`auto`。 * `enabled`：开启思考模式，模型一定先思考后回答。 * `disabled`：关闭思考模式，模型直接回答问题，不会进行思考。 * `auto`：自动思考模式，模型根据问题自主判断是否需要思考，简单题目直接回答。 --- **max_tokens** `integer / null` `默认值 4096` 模型回复最大长度（单位 token），取值范围各个模型不同，详细见[模型列表](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-list)。输入 token 和输出 token 的总长度还受模型的上下文长度限制。 --- **max_completion_tokens** `integer / null` > 支持该字段的模型 `deepseek-r1-250528`。取值范围：`[0, 64k]`。使用示例见 [文档](https://ark.volcengine.com/region:cn-beijing/docs/ark/deep-thinking#cfc7c5a8)。控制模型输出的最大长度（包括模型回答和模型思维链内容长度，单位 token）。配置了该参数后，可以让模型输出超长内容，**max_tokens** （默认值 4k）与思维链最大长度将失效，模型按需输出内容，直到达到 **max_completion_tokens** 配置的值。不可与 **max_tokens** 字段同时设置，会直接报错。 --- **stop** `string / string[] / null` `默认值 null` 模型遇到 stop 字段所指定的字符串时将停止继续生成，这个词语本身不会输出。 * 默认最多支持 `4` 个停止词。 * `deepseek-v4-pro-ga-260813`、`deepseek-v4-flash-ga-260731` 最多支持 `16` 个停止词。 > [深度思考能力模型](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-list#32e9e053)默认不支持该字段；上述 DeepSeek V4 模型除外。示例：`["你好", "天气"]` --- **frequency_penalty** `float / null` `默认值 0` 取值范围为 [\-2.0, 2.0]。频率惩罚系数。如果值为正，会根据新 token 在文本中的出现频率对其进行惩罚，从而降低模型逐字重复的可能性。 --- **presence_penalty** `float / null` `默认值 0` 取值范围为 [\-2.0, 2.0]。存在惩罚系数。如果值为正，会根据新 token 到目前为止是否出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。 --- **temperature** `float / null` `默认值 1` 取值范围为 [0, 2]。采样温度。控制了生成文本时对每个候选词的概率分布进行平滑的程度。当取值为 0 时模型仅考虑对数概率最大的一个 token。较高的值（如 0.8）会使输出更加随机，而较低的值（如 0.2）会使输出更加集中确定。通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。 --- **top_p** `float / null` `默认值 0.7` 取值范围为 [0, 1]。核采样概率阈值。模型会考虑概率质量在 top_p 内的 token 结果。当取值为 0 时模型仅考虑对数概率最大的一个 token。 0.1 意味着只考虑概率质量最高的前 10% 的 token，取值越大生成的随机性越高，取值越低生成的确定性越高。通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。 --- **logprobs** `boolean / null` `默认值 false` 是否返回输出 tokens 的对数概率。 * `false`：不返回对数概率信息。 * `true`：返回消息内容中每个输出 token 的对数概率。 --- **top_logprobs** `integer / null` `默认值 0` 取值范围为 [0, 20]。指定每个输出 token 位置最有可能返回的 token 数量，每个 token 都有关联的对数概率。仅当 **logprobs** 为`true` 时可以设置 **top_logprobs** 参数。 --- **logit_bias** `map / null` `默认值 null` 调整指定 token 在模型输出内容中出现的概率，使模型生成的内容更加符合特定的偏好。**logit_bias** 字段接受一个 map 值，其中每个键为词表中的 token ID（使用 tokenization 接口获取），每个值为该 token 的偏差值，取值范围为 [\-100, 100]。 \-1 会减少选择的可能性，1 会增加选择的可能性；\-100 会完全禁止选择该 token，100 会导致仅可选择该 token。该参数的实际效果可能因模型而异。 `{"": -100}` --- **tools** `object[] / null` `默认值 null` 待调用工具的列表，模型返回信息中可包含。当您需要让模型返回待调用工具时，需要配置该结构体。支持该字段的模型请参见 [文档](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-list#f44ceef7)。属性 --- tools.**type** `string` `必选` 工具类型，此处应为 `function`。 --- tools.**function** `object` `必选` 模型返回中可包含待调用的工具。属性 --- tools.function.**name** `string` `必选` 调用的函数的名称。 --- tools.function.**description** `string` 调用的函数的描述，大模型会使用它来判断是否调用这个工具。 --- tools.function.**parameters** `object` 函数请求参数，以 JSON Schema 格式描述。具体格式请参考 [JSON Schema](https://json-schema.org/understanding-json-schema) 文档，格式如下： ```JSON { "type": "object", "properties": { "location": { "type": "string", "description": "城市，如：北京" } }, "required": ["location"] } ``` 其中， * 所有字段名大小写敏感。 * **parameters** 须是合规的 JSON Schema 对象。 * 建议用英文字段名，中文置于 **description** 字段中。 --- ## 响应参数 > 跳转 [请求参数](https://ark.volcengine.com/region:cn-beijing/docs/ark/batch-chat-api#B2fc2CRV) ### 非流式调用返回 --- **id** `string` 本次请求的唯一标识。 --- **model** `string` 本次请求实际使用的模型名称和版本。 --- **service_tier** `string` 本次请求是否使用了TPM保障包。 * `default`：本次请求未使用TPM保障包额度。 --- **created** `integer` 本次请求创建时间的 Unix 时间戳（秒）。 --- **object** `string` 固定为 `chat.completion`。 --- **choices** `object[]` 本次请求的模型输出内容。属性 --- choices.**index** `integer` 当前元素在 **choices** 列表的索引。 --- choices.**finish_reason** `string` 模型停止生成 token 的原因。取值范围： * `stop`：模型输出自然结束，或因命中请求参数 stop 中指定的字段而被截断。 * `length`：模型输出因达到模型输出限制而被截断，有以下原因： * 触发`max_token`限制（回答内容的长度限制）。 * 触发`max_completion_tokens`限制（思维链内容+回答内容的长度限制）。 * 触发`context_window`限制（输入内容+思维链内容+回答内容的长度限制）。 * `content_filter`：模型输出被内容审核拦截。 * `tool_calls`：模型调用了工具。 --- choices.**message** `object` 模型输出的内容。属性 --- choices.message.**role** `string` 内容输出的角色，此处固定为 `assistant`。 --- choices.message.**content** `string` 模型生成的消息内容。 --- choices.message.**reasoning_content** `string / null` 模型处理问题的思维链内容。仅深度推理模型支持返回此字段，深度推理模型请参见[回传思考内容加密原文](https://ark.volcengine.com/region:cn-beijing/docs/ark/deep-thinking#8cfd447b)。批量推理场景下，对于已默认开启 thinking summary 的模型，不返回此字段（思考内容摘要），仅返回回答内容。 --- choices.message.**tool_calls** `object[] / null` 模型生成的工具调用。属性 --- choices.message.tool_calls.**id** `string` 调用的工具的 ID。 --- choices.message.tool_calls.**type** `string` 工具类型，当前仅支持`function`。 --- choices.message.tool_calls.**function** `object` 模型调用的函数。属性 --- choices.message.tool_calls.function.**name** `string` 模型调用的函数的名称。 --- choices.message.tool_calls.function.**arguments** `string` 模型生成的用于调用函数的参数，JSON 格式。模型并不总是生成有效的 JSON，并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前，请在您的代码中验证这些参数是否有效。 --- choices.**logprobs** `object / null` 当前内容的对数概率信息。属性 --- choices.logprobs.**content** `object[] / null` message列表中每个 content 元素中的 token 对数概率信息。属性 --- choices.logprobs.content.**token** `string` 当前 token。 --- choices.logprobs.content.**bytes** `integer[] / null` 当前 token 的 UTF\-8 值，格式为整数列表。当一个字符由多个 token 组成（表情符号或特殊字符等）时可以用于字符的编码和解码。如果 token 没有 UTF\-8 值则为空。 --- choices.logprobs.content.**logprob** `float` 当前 token 的对数概率。 --- choices.logprobs.content.**top_logprobs** `object[]` 在当前 token 位置最有可能的标记及其对数概率的列表。在一些情况下，返回的数量可能比请求参数 top_logprobs 指定的数量要少。 **属性** --- choices.logprobs.content.top_logprobs.**token** `string` 当前 token。 --- choices.logprobs.content.top_logprobs.**bytes** `integer[] / null` 当前 token 的 UTF\-8 值，格式为整数列表。当一个字符由多个 token 组成（表情符号或特殊字符等）时可以用于字符的编码和解码。如果 token 没有 UTF\-8 值则为空。 --- choices.logprobs.content.top_logprobs.**logprob** `float` 当前 token 的对数概率。 --- choices.**moderation_hit_type** `string``/ null` 模型输出文字含有敏感信息时，会返回模型输出文字命中的风险分类标签。返回值及含义： * `severe_violation`：模型输出文字涉及严重违规。 * `violence`：模型输出文字涉及激进行为。注意：当前只有 [视觉理解模型](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-understanding#f8d6cc48) 支持返回该字段，且只有在方舟控制台 [接入点配置页面](https://ark.volcengine.com/region:cn-beijing/endpoint/create?customModelId=) 或者 [CreateEndpoint](https://ark.volcengine.com/region:cn-beijing/docs/ark/create-endpoint-api) 接口中，将内容护栏方案（ModerationStrategy）设置为基础方案（Basic）时，才会返回风险分类标签。 --- **usage** `object` 本次请求的 token 用量。属性 --- usage.**prompt_tokens** `integer` 输入的 prompt token 数量。 --- usage.**completion_tokens** `integer` 模型生成的 token 数量。 --- usage.**total_tokens** `integer` 本次请求消耗的总 token 数量（输入 + 输出）。 --- usage.**prompt_tokens_details** `object` 本接口暂不支持该字段。命中上下文缓存的tokens细节。属性 --- usage.prompt_tokens_details.**cached_tokens** `integer` 本接口暂不支持该字段。此处应为 `0`。 --- usage.**completion_tokens_details** `object` 本次请求花费的 token 的细节。属性 --- usage.completion_tokens_details.**reasoning_tokens** `integer` 输出思维链内容花费的 token 数。支持输出思维链的模型请参见 [文档](https://ark.volcengine.com/region:cn-beijing/docs/ark/deep-thinking#14b5c6db)。

火山方舟