POST https://ark.cn-beijing.volces.com/api/v3/responses 本文介绍 Responses API 创建模型请求时的输入输出参数，供您使用接口时查阅字段含义。 :::tip 此为邀测能力，如需使用，提交[测试申请工单](https://console.volcengine.com/workorder/create?step=2&SubProductID=P90002304)。 ::: ```mixin-react return ( ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2abecd05ca2779567c6d32f0ddc7874d.png =20x) [模型列表](https://www.volcengine.com/docs/82379/1330310) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a5fdd3028d35cc512a10bd71b982b6eb.png =20x) [模型计费](https://www.volcengine.com/docs/82379/1544106) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_57d0bca8e0d122ab1191b40101b5df75.png =20x) [模型调用教程](https://www.volcengine.com/docs/82379/1585128) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_afbcf38bdec05c05089d5de5c3fd8fc8.png =20x) [API Key](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) `}>); ``` --- ## 请求参数 ### 请求体 --- **model** `string` %%require%% 您需要调用的模型的 ID （Model ID），[开通模型服务](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)，并[查询 Model ID](https://www.volcengine.com/docs/82379/1330310) 。您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力，可参考[获取 Endpoint ID](https://www.volcengine.com/docs/82379/1099522)。 --- input string / array %%require%% 用于生成回复的文本、图片或视频内容。属性 **text input** `string` 模型的文本输入。 input item list array **input message** `object` 发送给模型的消息输入，其中角色用于指示指令遵循的优先级层级。由 `developer` 或 `system` 角色给出的指令优先于 `user` 角色给出的指令。`assistant` 角色的消息通常被认为是模型在先前交互中生成的回复。 **content** `string / array` %%require%% 用于生成回复的文本、图片或视频输入，也可以包含先前助手的回复内容。 **text Input** `string` 模型的文本输入。 **input item content list** `array` 包含一个或多个输入项的列表，每个输入项可包含不同类型的内容。 **input text** `object` **text** `string` **** %%require%% 输入模型的文本。 **type** `string` **** %%require%% 输入项的类型，始终为`input_text`。 **input image** `object` 输入模型的图片或视频。 **type** `string` **** %%require%% 输入项的类型，可选视图片或视频 * `input_image`：输入为图片类型。 * `input_video`：输入为视频类型。 **image_url** `string` **** 要发送给模型的图片 URL。可以是完整的 URL，或以 data URL 形式编码的 base64 图片。 **video_url** `string` **** 要发送给模型的视频 URL。可以是完整的 URL，或以 data URL 形式编码的 base64 视频。 **detail** `string` **** type为input_image时，发送给模型的图片细节级别。可选值为 high、low 或 auto，默认为 auto。 **fps** `integer` type为input_video时，每秒钟从视频中抽取指定数量的图像，取值范围：`[0.2, 5]`。 **role** `string` %%require%% 输入消息的角色，可以是 user，system ，assistant或 developer。 **type** `string` 消息输入的类型，总是`message`。 **item** `object` 表示模型生成回复时所用上下文的一项内容。该项可以包含文本、图片和视频输入，以及先前助手的回复和工具调用的输出。 **input message** `object` 发送给模型的消息输入。 **content** `array` %%require%% 与 `input message` 中 `content` 的结构完全一致。 **role** `string` %%require%% 输入消息的角色，可以是 system，`user` 或 developer。 **type** `string` 消息输入的类型，总是`message`。 **output message** `object` 模型输出的消息。 **content** `array` %%require%% 输出消息的内容。 **output text** `object` 模型的文本输出。 **text** `string` %%require%% 模型的文本输出。 **type** `string` %%require%% 输出文本的类型，总是`output_text`。 **role** `string` %%require%% 输出信息的角色，总是`assistant`。 **status** `string` 输入消息的状态。 **type** `string` %%require%% 输出消息的类型。 **reasoning** `object` 推理模型在生成响应时所使用的思维链条的说明。如果您在手动管理对话上下文，请务必在后续轮次调用 Response API 时，将这些内容包含在您的 `input` 中。 **summary** `array` **** %%require%% 推理文本内容。 **text** `string` %%require%% 模型生成答复时的推理内容。 **type** `string` %%require%% 对象的类型，总是 `summary_text`。 **type** `string` **** %%require%% 对象的类型，总是 `reasoning`。 **status** `string` 该项的状态。 **function tool call** `object` **arguments** `string` %%require%% 要传递给函数的参数的 JSON 字符串。 **call_id** `string` %%require%% 模型生成的函数工具调用的唯一ID。 **name** `string` %%require%% 要运行的函数的名称。 **type** `string` %%require%% 工具调用的类型，始终为 `function_call`。 **status** `string` 该项的状态。 **function tool call output** `object` **call_id** `string` %%require%% 模型生成的函数工具调用的唯一 ID。 **output** `string` %%require%% 函数工具调用输出的结果。 **type** `string` %%require%% 工具调用的类型，始终为 `function_call`。 **status** `string` 该项的状态。 --- **instructions** `string / null` 在模型上下文中插入系统消息或者开发者作为第一条指令。当与 `previous_response_id` 一起使用时，前一个回复中的指令不会被继承到下一个回复中。这样可以方便地在新的回复中替换系统（或开发者）消息。 --- **previous_response_id** `string / null` 上一个模型回复的唯一标识符。使用该标识符可以实现多轮对话。 **note：**在多轮连续对话中，建议在每次请求之间加入约 100 毫秒的延迟，否则可能会导致调用失败。 --- **expire_at** `integer` 传入 UTC Unix 时间戳（单位：秒）。默认值为当前时间加 3 天。用户传入的时间戳不得超过当前时间加 3 天。 --- **max_output_tokens** `integer / null` 可生成的最大 token 数上限，不包括思考 token。 --- **thinking** `object / null` `默认值 null` 控制模型是否开启深度思考模式。默认开启深度思考模式，可以手动关闭。属性 --- thinking.type **** `string` `默认值 enabled` %%require%% 取值范围：`enabled`， `disabled`，`auto`。 * `enabled`：开启思考模式，模型一定先思考后回答。 * `disabled`：关闭思考模式，模型直接回答问题，不会进行思考。 * `auto`：自动思考模式，模型根据问题自主判断是否需要思考，简单题目直接回答。 --- **caching** `object` 是否开启缓存。属性 --- caching.type **** `string` `默认值 disabled` %%require%% 取值范围：`enabled`， `disabled`。 * `enabled`：开启缓存。 * `disabled`：关闭缓存。 --- **store** `boolean / null` `默认值 true` 是否储存生成的模型响应，以便后续通过 API 检索。 * `false`：不储存，对话内容不能被后续的 API 检索到。 * `true`：储存当前模型响应，对话内容能被后续的 API 检索到。 --- **stream** `boolean / null` `默认值 false` 响应内容是否流式返回： * `false`：模型生成完所有内容后一次性返回结果。 * `true`：按 SSE 协议逐块返回模型生成内容，并以一条 `data: [DONE]`消息结束。 --- **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 其中之一，不建议两者都修改。 --- **text** `object` 用于定义输出的格式，可以是纯文本，也可以是结构化的 JSON 数据。详情请看[结构化输出](https://www.volcengine.com/docs/82379/1568221)。属性 **format** `object` 指定模型必须输出的格式的对象。 **text** `object` 文本对象响应格式。 **type** `string` %%require%% 回复格式的类型，总是 `text`。 **JSON object** `object` JSON 对象响应格式。 **type** `string` %%require%% 回复格式的类型，总是 `json_object`。 --- **tools** `array` 模型可以调用的工具列表，当您需要让模型调用工具时，需要配置该结构体。属性 --- **function** `object` 模型可以调用的类型为`function`的工具列表。 **name** `string` %%require%% 调用的函数的名称。 **parameters** `object` %%require%% 函数请求参数，以 JSON Schema 格式描述。具体格式请参考 [JSON Schema](https://json-schema.org/understanding-json-schema) 文档，格式如下： ```JSON { "type": "object", "properties": { "参数名": { "type": "string | number | boolean | object | array", "description": "参数说明" } }, "required": ["必填参数"] } ``` 其中， * 所有字段名大小写敏感。 * parameters 须是合规的 JSON Schema 对象。 * 建议用英文字段名，中文置于 description 字段中。 **type** `string` %%require%% 工具调用的类型，总是`function`。 **description** `string` 调用函数的描述，大模型会用它来判断是否调用这个函数。 ## 响应参数 ### 非流式调用返回 --- **created_at** `integer` 本次请求创建时间的 Unix 时间戳（秒）。 --- **error** `object / null` 模型未能生成响应时返回的错误对象。 * code：相应的错误码。 * message：错误描述。 --- **id** `string` 本次请求的唯一标识。 --- **incomplete_details** `object / null` 响应未能完成的细节。 `reason`：响应未能完成的原因。 --- **instructions** `string / null` 在模型上下文中插入一条系统（或开发者）消息，作为首项。当与 `previous_response_id` 一起使用时，前一响应中的指令不会延续到下一响应。 --- **max_output_tokens** `integer / null` 可生成的最大 token 数上限，不包括思考 token。 --- **model** `string` 本次请求实际使用的模型名称和版本。 --- **output** `array` 模型的一条输出消息。属性 **output message** `object` **content** `array` 输出消息的内容。 **output text** `object` 模型的文本输出。 **text** `string` %%require%% 模型的文本输出。 **type** `string` %%require%% 输出文本的类型，总是`output_text`。 **role** `string` 输出信息的角色，总是`assistant`。 **status** `string` 输出消息的状态。 **id** `string` output message 请求的唯一标识。 **type** `string` 输出消息的类型。 **reasoning** `object` 推理模型在生成响应时所使用的思维链条的说明。如果您在手动管理对话上下文，请务必在后续轮次调用 Response API 时，将这些内容包含在您的 `input` 中。 **summary** `array` **** 推理文本内容。 **text** `string` 模型生成答复时的推理内容。 **type** `string` 对象的类型，总是 `summary_text`。 **type** `string` **** 对象的类型，总是 `reasoning`。 **status** `string` 该项的状态。 **id** `string` reasoning 请求的唯一标识。 **function tool call** `object` **arguments** `string` 要传递给函数的参数的 JSON 字符串。 **call_id** `string` 模型生成的函数工具调用的唯一ID。 **name** `string` 要运行的函数的名称。 **type** `string` 工具调用的类型，始终为 `function_call`。 **status** `string` 该项的状态。 **id** `string` funciton call tool 请求的唯一标识。 --- **previous_response_id** `string / null` 模型上一次响应的唯一 ID。使用该参数可以创建多轮对话。 --- **thinking** `object / null` 思考模型的详细信息，仅对思考模型生效。属性 **effort** `string / null` 推理模型的推理力度。目前支持的取值有 `low`、`medium` 和 `high`。降低推理力度可以使响应更快，同时减少响应中用于推理的 token 数量。 **summary** `string / null` 模型的思考内容。 --- **caching** `object` 是否开启缓存。属性 --- caching.type **** `string` `默认值 disabled` %%require%% 取值范围：`enabled`， `disabled`。 * `enabled`：开启缓存。 * `disabled`：关闭缓存。 --- service_tier `string` 本次请求是否使用了TPM保障包。 * scale：本次请求使用TPM保障包额度。 * default：本次请求未使用TPM保障包额度。 --- **status** `string` 生成响应的状态。 * `completed`：响应已完成。 * `failed`：响应失败。 * `in_progress`：响应中。 * `incomplete`：响应未完成。 --- **text** `object` 用于定义输出的格式，可以是纯文本，也可以是结构化的 JSON 数据。详情请看[结构化输出](https://www.volcengine.com/docs/82379/1568221)。属性 **format** `object` 指定模型必须输出的格式的对象。 **text** `object` 文本对象响应格式。 **type** `string` %%require%% 回复格式的类型，总是 `text`。 **JSON object** `object` JSON 对象响应格式。 **type** `string` %%require%% 回复格式的类型，总是 `json_object`。 --- **tools** `array` 模型可以调用的工具列表，当您需要让模型调用工具时，需要配置该结构体。属性 --- **function** `object` 模型可以调用的类型为`function`的工具列表。 **name** `string` %%require%% 调用的函数的名称。 **parameters** `object` %%require%% 函数请求参数，以 JSON Schema 格式描述。具体格式请参考 [JSON Schema](https://json-schema.org/understanding-json-schema) 文档，格式如下： ```JSON { "type": "object", "properties": { "参数名": { "type": "string | number | boolean | object | array", "description": "参数说明" } }, "required": ["必填参数"] } ``` 其中， * 所有字段名大小写敏感。 * parameters 须是合规的 JSON Schema 对象。 * 建议用英文字段名，中文置于 description 字段中。 **type** `string` %%require%% 工具调用的类型，总是`function`。 **description** `string` 调用的函数的描述，大模型会使用它来判断是否调用这个函数。 --- **top_p** `float / null` 核采样概率阈值。 --- **usage** `object` 本次请求的 token 用量，包括输入 token 数量、输入 token 的详细分解、输出 token 数量、输出 token 的详细分解，以及总共使用的 token 数。属性 **Input_tokens** `integer` 输入的 token 量。 **input_tokens_details** `object` 输入 token 的详细信息。 **cached_tokens** `integer` 缓存 token 的数量。 **output_tokens** `integer` 输出的 token 量。 **output_tokens_details** `object` 输出 token 的详细信息。 **reasoning_tokens** `integer` 思考用 token 的数量。 **total_tokens** `integer` 消耗 token 的总量。 --- ### **store** `boolen` `默认值 true` 是否储存生成的模型响应，以便后续通过 API 检索。 * `false`：不储存，对话内容不能被后续的 API 检索到。 * `true`：储存当前模型响应，对话内容能被后续的 API 检索到。

火山方舟大模型服务平台