大模型服务平台 TokenHub Responses API 兼容模式说明

一、概述

该转换过程对调用方透明，你无需感知模型底层实际使用的协议，只需统一使用 Responses API 调用即可。由于两种协议在设计上存在差异，兼容模式下部分 Responses API 参数与能力（如 previous_response_id、内置工具等）暂不支持或行为存在限制，具体请参见这篇各章节说明。

本兼容模式支持模型列表详见语言模型调用概览。

二、适用场景

·你已基于 Responses API 构建应用，现在希望直接调用兼容模式支持的模型，无需额外接入 Chat Completions 协议。

·你需要使用模型自身的推理（思考）能力，并希望以 Responses API 统一的 reasoning 输出条目格式获取推理过程。

三、使用方法

调用方式与标准 Responses API 完全一致，无需任何额外参数或配置：TokenHub 会自动为兼容模式支持的模型完成协议转换。

关于 Base URL、地域接入地址、鉴权方式等基础信息，请参见 API 使用说明。

四、请求参数说明

以下参数按支持程度分为三类：完全支持、不支持（会返回错误）、接受但不生效，请在调用前确认所用参数的实际支持情况。

五、完全支持的参数

参数	类型	必填	说明
model	String	是	模型 ID。
input	String 或 Array	是	输入内容，支持纯字符串或输入条目数组，详情请参见输入格式说明。
instructions	String	否	系统指令。
stream	Boolean	否	是否以流式方式返回，详情请参见流式输出。
max_output_tokens	Integer	否	最大输出 Token 数，必须大于 0。
temperature	Float	否	采样温度，取值范围 [0, 2]。
top_p	Float	否	核采样参数，取值范围 [0, 1]。
tools	Array	否	工具列表，兼容模式下仅支持 function 类型，详情请参见工具调用支持范围。
tool_choice	String 或 Object	否	工具选择策略。
parallel_tool_calls	Boolean	否	是否允许并行工具调用。
text.format	Object	否	输出格式，支持 text、json_object、json_schema。
reasoning.effort	String	否	推理努力程度，详情请参见推理模型说明。
metadata	Object	否	键值对元数据，最多 16 对，Key 不超过 64 个字符，Value 不超过 512 个字符，会在响应中原样回显。
service_tier	String	否	服务层级，可选值：auto、default、flex、scale、priority，会在响应中回显。
prompt_cache_key	String	否	提示缓存键，会在响应中回显。
prompt_cache_retention	String	否	提示缓存保留策略，可选值：in_memory、24h，会在响应中回显。
top_logprobs	Integer	否	对数概率数量，会在响应中回显。
stream_options.include_usage	Boolean	否	流式模式下是否在末尾返回 usage，默认开启。
user	String	否	用户标识。

六、不支持的参数

以下参数在兼容模式下不支持，传入会直接返回 HTTP 400 错误：

参数	错误信息	说明
background=true	background mode is not supported in chat-compat mode	不支持后台异步运行模式。
background=true 且 stream=true	background and stream=true cannot be used together	后台模式与流式输出互斥。
previous_response_id（非空值）	previous_response_id is not supported in chat-compat mode	不支持基于历史响应 ID 延续对话，需通过 input 数组传入完整对话历史，详情请参见多轮对话说明。
previous_response_id（空字符串）	previous_response_id must not be empty string	参数值校验。
previous_response_id 与 conversation 同时传入	previous_response_id and conversation cannot be used together	两个参数互斥。
prompt（input 为空时）	prompt template is not supported in chat-compat mode, please provide input directly	不支持提示词模板，请直接通过 input 传入内容。
input 为空	input is required and must contain at least one message	input 为必填参数。
temperature 超出 [0, 2]	temperature must be between 0 and 2	参数取值范围校验。
top_p 超出 [0, 1]	top_p must be between 0 and 1	参数取值范围校验。
max_output_tokens ≤ 0	max_output_tokens must be greater than 0	参数取值范围校验。
service_tier 非法值	invalid service_tier value: xxx	枚举值校验。
prompt_cache_retention 非法值	invalid prompt_cache_retention value: xxx	枚举值校验。

注意：说明：

注意：background 仅在显式传入 background=true 时报错；未传入或传入 false 时会被正常接受，并在响应中原样回显。

七、接受但不生效的参数

以下参数会被正常接受（不报错），但实际不生效：

参数	说明
truncation	上下文截断策略，兼容模式下不做截断处理。
include	额外字段返回请求，兼容模式下不会返回额外字段。
store	响应存储开关，兼容模式下不存储响应。
conversation	会话管理，需通过 input 数组自行管理对话历史。
context_management	上下文自动管理（如自动压缩）。
max_tool_calls	最大工具调用次数限制。
prompt（input 非空时）	提示词模板。
moderation	内容审核配置。
reasoning.summary	推理摘要模式。

八、输入格式说明

input 字段支持两种形式。

九、纯字符串输入

{ "model": "glm-5.2", "input": "你好，请介绍一下自己。"}

等同于一条 role 为 user 的文本消息。

十、输入条目数组

input 为数组时，每个元素为一个输入条目。

支持的输入条目类型：

条目类型	type 取值	说明
消息	message	标准消息输入，支持 user、assistant、system、developer 角色，developer 角色等同于 system。
函数调用	function_call	上一轮模型发起的函数调用。
函数调用结果	function_call_output	工具执行结果。
推理	reasoning	上一轮的推理内容。
自定义工具调用	custom_tool_call	处理方式与 function_call 一致。
自定义工具调用结果	custom_tool_call_output	处理方式与 function_call_output 一致。

不支持的输入条目类型（会被自动忽略）：

条目类型	type 取值
计算机操作调用	computer_call
计算机操作结果	computer_call_output
文件搜索调用	file_search_call
网络搜索调用	web_search_call

十一、消息内容类型

message 类型条目的 content 字段支持字符串或内容块数组，支持以下内容块类型：

内容块类型	type 取值	说明
文本输入	input_text	文本内容。
文本输出	output_text	文本内容，用于 assistant 消息。
纯文本	text	文本内容的兼容写法。
图像输入	input_image	支持 image_url（远程 URL 或 base64 data URI）。file_id 形式的图像输入不支持。
文件输入	input_file	仅当携带 file_data（Base64 编码内容）时支持，会转换为 Data URI 格式传递给模型。

图像输入支持 image_url（远程 URL 或 base64 data URI）。file_id 形式的图像输入不支持。input_file 类型仅当包含 file_data（base64 编码内容）时支持，且会以 data URI 形式传递给下游。

十二、多模态输入示例

对于支持多模态输入的模型，可在 message 类型输入条目的 content 字段中同时传入文本和图像内容块。图像内容块使用 input_image 类型，通过 image_url 传入远程图片 URL 或 base64 data URI。file_id 形式的图像输入不支持。

curl https://tokenhub.tencentmaas.com/v1/responses \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer $API_KEY" \\ -d '{ "model": "your-model", "input": [ { "role": "user", "content": [ {"type": "input_text", "text": "这张图片里有什么？"}, { "type": "input_image", "image_url": "https://example.com/image.jpg", "detail": "auto" } ] } ] }'

十四、支持的工具类型

工具类型	type 取值	说明
函数工具	function	完全支持，name、description、parameters、strict 字段均可用。

Function 工具字段说明：

字段	类型	必填	说明
type	String	是	固定为 function。
name	String	是	函数名称。
description	String	否	函数描述，供模型判断是否调用。
parameters	Object	否	函数参数的 JSON Schema，未提供时默认为 {"type": "object", "properties": {}}。
strict	Boolean	否	是否进行严格参数校验。

十五、不支持的工具类型

以下工具类型在兼容模式下暂不支持，传入会被自动丢弃，不会报错：

工具类型	type 取值
文件搜索	file_search
网络搜索	web_search、web_search_preview
代码解释器	code_interpreter
MCP 工具	mcp
计算机操作	computer_use_preview、computer
图像生成	image_generation
自定义工具	custom
Shell 工具	shell
补丁工具	apply_patch

十七、Response 对象

非流式请求返回 Response 对象；流式请求的 response.created、response.completed 等事件中也包含该对象。以下示例中 output 为空数组，实际调用时会按模型的输出内容填充，具体结构见下文与调用示例。

{ "id": "resp_xxx", "object": "response", "created_at": 1751548800, "status": "completed", "model": "glm-5.2", "output": [], "output_text": "模型生成的文本", "usage": { "input_tokens": 20, "output_tokens": 11, "total_tokens": 31, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens_details": { "reasoning_tokens": 0 } }, "metadata": {}, "error": null}

字段	类型	说明
id	String	响应唯一标识符。
object	String	固定为 response。
created_at	Integer	响应创建时间，Unix 时间戳（秒）。
status	String	响应状态，取值 completed、incomplete、failed。
model	String	实际调用的模型 ID。
output	Array	输出条目列表，详情请参见输出条目类型。
output_text	String	便捷字段，为 output 中所有文本内容块的拼接结果。
usage	Object	Token 用量统计，详情请参见 Usage 用量统计。
error	Object 或 null	错误信息，正常完成时为 null。
metadata	Object	元数据回显，始终返回（可为空对象）。
incomplete_details	Object 或 null	响应不完整时的详情，reason 取值为 max_output_tokens 或 content_filter；正常完成时不返回。

以下请求参数如传入，会在响应中原样回显：

instructions	temperature	top_p	max_output_tokens
parallel_tool_calls	tool_choice	tools	reasoning
text	truncation	service_tier	prompt_cache_key
prompt_cache_retention	top_logprobs	background	prompt
max_tool_calls	–	–	–

十八、输出条目类型

output 数组按推理、消息、函数调用的实际产生顺序排列。

推理条目：

{ "type": "reasoning", "id": "rs_xxx", "status": "completed", "summary": [ { "type": "summary_text", "text": "推理过程文本" } ]}

消息条目：

{ "type": "message", "id": "msg_xxx", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "模型生成的回复文本", "annotations": [] } ]}

content 数组中的内容块支持 output_text（模型生成的文本）和 refusal（模型拒绝回复时的原因文本）两种类型。

函数调用条目：

{ "type": "function_call", "id": "fc_xxx", "status": "completed", "call_id": "call_xxx", "name": "get_weather", "arguments": "{\\"location\\":\\"北京\\",\\"unit\\":\\"celsius\\"}"}

注意：function_call.arguments 始终为 JSON 字符串格式，调用方需自行执行 JSON 解析后再使用。提交函数执行结果时，需在 function_call_output 条目中传入与该函数调用对应的 call_id。

十九、Usage 用量统计

{ "input_tokens": 20, "output_tokens": 11, "total_tokens": 31, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens_details": { "reasoning_tokens": 0 }}

字段	类型	说明
input_tokens	Integer	输入 Token 数。
output_tokens	Integer	输出 Token 数，包含推理 Token。
total_tokens	Integer	输入与输出 Token 总数。
input_tokens_details.cached_tokens	Integer	命中缓存的输入 Token 数，无缓存命中时为 0。
output_tokens_details.reasoning_tokens	Integer	推理过程消耗的 Token 数，无推理时为 0。

注意：推理 Token 计入 output_tokens 与 output_tokens_details.reasoning_tokens，会影响本次调用的 Token 总消耗。

20、流式输出

设置 stream: true 后，响应通过 SSE（Server-Sent Events）方式流式返回。

21、事件序列

response.created 响应已创建response.in_progress 响应进行中 [reasoning，可选] response.output_item.added 推理条目开始 response.reasoning_summary_part.added 推理摘要部分开始 response.reasoning_summary_text.delta 推理文本增量（多次） response.reasoning_summary_text.done 推理文本完成 response.reasoning_summary_part.done 推理摘要部分完成 response.output_item.done 推理条目完成 [message，可选] response.output_item.added 消息条目开始 response.content_part.added 内容块开始 response.output_text.delta 文本增量（多次） response.output_text.done 文本完成 response.content_part.done 内容块完成 response.output_item.done 消息条目完成 [function_call，可多个] response.output_item.added 函数调用条目开始 response.function_call_arguments.delta 参数增量（多次） response.function_call_arguments.done 参数完成 response.output_item.done 函数调用条目完成response.completed 响应已完成，包含完整 usage

reasoning 与 message 条目为可选，是否出现取决于模型的实际输出内容。当推理与正文交替出现（推理、正文、推理、正文）时，各输出条目的开始与结束事件均会按序正确返回。

22、事件类型说明

事件类型	说明
response.created	响应已创建。
response.in_progress	响应进行中。
response.output_item.added	新增输出条目，包含 output_index 与 item。
response.output_item.done	输出条目完成，包含 output_index 与 item。
response.content_part.added	内容块开始，包含 item_id、output_index、content_index、part。
response.content_part.done	内容块完成，包含 item_id、output_index、content_index、part。
response.output_text.delta	文本增量，包含 item_id、output_index、content_index、delta。
response.output_text.done	文本完成，包含 item_id、output_index、content_index、text。
response.reasoning_summary_part.added	推理摘要部分开始。
response.reasoning_summary_part.done	推理摘要部分完成。
response.reasoning_summary_text.delta	推理文本增量。
response.reasoning_summary_text.done	推理文本完成。
response.function_call_arguments.delta	函数调用参数增量。
response.function_call_arguments.done	函数调用参数完成。
response.completed	响应完成，包含完整 Response 对象及 usage。
response.failed	响应失败，包含 Response 对象及 error 信息。

23、多轮对话说明

兼容模式下不支持 previous_response_id，多轮对话需通过 input 数组完整传入历史消息：

{ "model": "glm-5.2", "input": [ {"role": "user", "content": "我叫小明。"}, {"role": "assistant", "content": "你好，小明！"}, {"role": "user", "content": "今天天气怎么样？"}, {"role": "assistant", "content": "我无法直接获取天气信息，但可以为你查询。"}, {"type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": "{\\"city\\":\\"北京\\"}"}, {"type": "function_call_output", "call_id": "call_1", "output": "{\\"temp\\":25,\\"weather\\":\\"晴\\"}"}, {"role": "assistant", "content": "北京今天25度，晴天。"}, {"role": "user", "content": "那明天呢？"} ]}

注意：input 数组中的条目顺序需与对话时间线一致；function_call 与 function_call_output 需成对出现，且 call_id 需保持一致。

24、推理模型说明

对于支持推理能力的模型，兼容模式会自动处理以下两种推理内容返回格式，统一转换为 Responses API 的 reasoning 输出条目，调用方无需关心底层返回格式的差异：

·模型通过 reasoning_content 字段返回的推理内容。

·部分模型在正文中使用特定标签包裹推理内容的格式，会被自动识别并拆分为推理条目与正文条目。

如需关闭推理过程，可将 reasoning.effort 设置为 none 或 no_think：

{ "model": "glm-5.2", "input": "你好", "reasoning": { "effort": "none" }}

26、基础文本对话

27、带系统指令的对话

curl https://tokenhub.tencentmaas.com/v1/responses \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer $API_KEY" \\ -d '{ "model": "glm-5.2", "instructions": "你是一个专业的翻译助手，请将用户输入翻译为英文。", "input": "今天天气真好" }'

28、函数调用

第一轮：定义工具并发起请求。

curl https://tokenhub.tencentmaas.com/v1/responses \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer $API_KEY" \\ -d '{ "model": "glm-5.2", "input": "北京今天天气怎么样？", "tools": [ { "type": "function", "name": "get_current_weather", "description": "获取指定地点的当前天气", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "城市名称"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["location", "unit"] } } ], "tool_choice": "auto" }'

模型返回函数调用请求后，将执行结果通过 function_call_output 提交，即可获得最终回复：

curl https://tokenhub.tencentmaas.com/v1/responses \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer $API_KEY" \\ -d '{ "model": "glm-5.2", "input": [ {"role": "user", "content": "北京今天天气怎么样？"}, { "type": "function_call", "call_id": "call_xxx", "name": "get_current_weather", "arguments": "{\\"location\\":\\"北京\\",\\"unit\\":\\"celsius\\"}" }, { "type": "function_call_output", "call_id": "call_xxx", "output": "{\\"temperature\\": 28, \\"unit\\": \\"celsius\\", \\"description\\": \\"晴天\\"}" } ], "tools": [ { "type": "function", "name": "get_current_weather", "description": "获取指定地点的当前天气", "parameters": { "type": "object", "properties": { "location": {"type": "string"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["location", "unit"] } } ] }'

29、流式输出

30、结构化输出

curl https://tokenhub.tencentmaas.com/v1/responses \\ -H "Content-Type: application/json" \\ -H "Authorization: Bearer $API_KEY" \\ -d '{ "model": "glm-5.2", "input": "提取以下文本中的人物信息：张三，男，25岁，北京人。", "text": { "format": { "type": "json_schema", "name": "person_info", "schema": { "type": "object", "properties": { "name": {"type": "string"}, "gender": {"type": "string"}, "age": {"type": "number"}, "city": {"type": "string"} }, "required": ["name", "gender", "age", "city"], "additionalProperties": false }, "strict": true } } }'

注意：使用 json_schema 输出格式时，建议在 schema 中包含 "additionalProperties": false，以获得更好的模型兼容性。

32、现有基于 Responses API 的代码，调用兼容模式支持的模型需要做哪些改动？

不需要任何改动，将 model 设置为对应模型 ID 即可正常调用，TokenHub 会自动完成协议转换，详情请参见使用方法。

33、为什么调用 previous_response_id 会报错？

兼容模式下不支持基于历史响应 ID 延续对话，需改为通过 input 数组完整传入对话历史，详情请参见多轮对话说明。

34、为什么传入 web_search、code_interpreter 等工具没有生效？

兼容模式下仅支持 function 类型工具，其余内置工具类型会被自动丢弃，不会报错，详情请参见工具调用支持范围。

35、tool_choice 设置为 required 后报错，如何处理？

required 的支持情况取决于所调用的模型本身是否支持该取值，部分模型可能不支持并返回错误，建议改用 auto 或直接指定具体的工具名称。

36、input 为空字符串时会怎样？

若 input 完全为空（既无字符串也无数组元素），会返回 HTTP 400 错误。若 input 中某条 user 消息内容为空字符串，系统会自动填充占位文本，避免模型调用异常。