OpenAI 请求参数与输入格式
本文档详细说明通过 UniGateway 调用 OpenAI 规范端点(Responses API POST /v1/responses 与 Chat Completions API POST /v1/chat/completions)时的完整顶层请求参数定义、消息与输入项结构、多模态块格式及网关规范化规则。
章节导引
本篇为 OpenAI API 参考文档的第 2 章节:
- Responses 概述与快速开始
- 请求参数与输入格式(当前章节)
- 扩展推理与会话状态
- 结构化输出与采样参数
- 工具调用与内置工具
- 响应、流式与错误处理
顶层请求参数一览
在向 UniGateway 的 OpenAI 接口发送 JSON 请求体时,支持以下顶层参数:
| 参数名 | 适用端点 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
model | 双端点通用 | string | 是 | 目标模型 ID(支持带推理强度后缀简写,如 gpt-5.4-high) |
input | /v1/responses | string | array | 是 | Responses API 的输入文本或结构化输入项(Items)列表 |
instructions | /v1/responses | string | 否 | 系统级/开发者级指令(优先级高于 input 中的对话历史) |
messages | /v1/chat/completions | array | 是 | Chat Completions 对话消息数组(包含 developer/system/user/assistant/tool 角色) |
max_output_tokens | /v1/responses | integer | 否 | Responses API 最大生成 Token 数(包含推理 Token 与可见输出 Token,要求 >= 1,小于 16 时自动钳制为 16) |
max_completion_tokens | /v1/chat/completions | integer | 否 | Chat Completions 最大生成 Token 数(包含推理 Token 与可见输出 Token,推荐替代 max_tokens) |
max_tokens | /v1/chat/completions | integer | 否 | 旧版最大输出 Token 数(在推理模型与 Responses 端点上由网关自动迁移) |
reasoning | /v1/responses | object | 否 | 推理配置对象,详见 扩展推理与会话状态 |
reasoning_effort | /v1/chat/completions | string | 否 | Chat Completions 推理强度控制(none / minimal / low / medium / high / xhigh / max) |
tools | 双端点通用 | array | 否 | 可用工具列表,详见 工具调用与内置工具 |
tool_choice | 双端点通用 | string | object | 否 | 工具选择策略("auto" / "none" / "required" 或指定特定函数/工具) |
parallel_tool_calls | 双端点通用 | boolean | 否 | 是否允许模型在单回合中并行发起多个工具调用 |
text | /v1/responses | object | 否 | 文本输出配置,包含结构化输出 text.format 与详细度 text.verbosity |
response_format | /v1/chat/completions | object | 否 | 结构化输出格式配置(text / json_object / json_schema) |
temperature / top_p | 双端点通用 | number | 否 | 采样温度与核采样阈值,详见 结构化输出与采样参数 |
logprobs / top_logprobs | 双端点通用 | boolean | integer | 否 | 输出对数概率配置(仅在非推理模型或 effort="none" 时生效) |
presence_penalty / frequency_penalty / logit_bias | /v1/chat/completions | number | object | 否 | 词频惩罚与 Token 偏置(仅在非推理模型或 effort="none" 时生效) |
store | 双端点通用 | boolean | 否 | 是否在服务端持久化响应以供后续引用或评估 |
previous_response_id | /v1/responses | string | 否 | 上一轮响应 ID(用于服务端有状态多轮续写) |
truncation | /v1/responses | string | 否 | 上下文超长时的截断策略("auto" 或 "disabled") |
include | /v1/responses | array<string> | 否 | 指定在响应中额外返回的字段(如 "reasoning.encrypted_content") |
prompt_cache_key | 双端点通用 | string | 否 | 提示缓存路由键,用于提升相同前缀请求的缓存命中率 |
prompt_cache_retention | 双端点通用 | string | 否 | 提示缓存保留策略(如 "in_memory" 或 "24h") |
prompt_cache_options | /v1/responses | object | 否 | GPT-5.6 / GPT-6 / GPT-6.1 系列原生提示缓存配置(如 {"ttl": "30m"}) |
service_tier | 双端点通用 | string | 否 | 服务处理档位("auto" / "default" / "flex" / "priority") |
stream / stream_options | 双端点通用 | boolean | object | 否 | 是否开启 SSE 流式输出及流式附加选项,详见 响应、流式与错误处理 |
safety_identifier / metadata | 双端点通用 | string | object | 否 | 终端用户安全标识(替代旧版 user 字段)与自定义键值元数据 |
provider | /v1/chat/completions | object | 否 | OpenRouter 兼容提供商路由偏好(only / order / ignore / quantizations / zdr) |
核心参数三维规范对比
UniGateway 对所有入站请求严格对齐 OpenAI 官方规范与 Migration Guide,并在转发多云及第三方通道时提供确定性的协议规范化保障:
1. model(模型标识、代际路由与通道约束)
| 参数 / 场景 | OpenAI 官方规范与 Migration Guide | UniGateway 处理规则 |
|---|---|---|
model 标准模型标识 | 必填字符串。指定目标模型 ID(如 gpt-6.1-sol、gpt-6、gpt-5.6、gpt-5.4、gpt-5.3-codex、o3、gpt-4.1)。 | 自动别名归一化:网关根据上游通道类型自动将用户传入的模型别名(如日期快照或内部代号)映射为目标上游接受的标准模型标识。响应体中的 model 字段默认保持与客户端请求一致。 |
模型名带推理后缀简写(如 gpt-5.4-high、gpt-6-xhigh) | OpenAI 官方 API 要求通过独立的 reasoning.effort 或 reasoning_effort 字段传递推理强度,直接将 -high / -xhigh / -low 拼接在 model 中会导致上游报错 model_not_found。 | 后缀自动提取与注入:当客户端请求如 gpt-5.4-high、gpt-5.3-codex-low、gpt-6.1-sol-xhigh 时,网关自动剥离模型后缀还原为基础模型名(如 gpt-5.4),并在请求未显式指定推理强度时将该后缀注入到 reasoning.effort(或 reasoning_effort)。 |
gpt-5.5 / gpt-5.5-pro 订阅通道下线与选路隔离 | OpenAI 自 2026-10-14 起在 ChatGPT 订阅(Codex OAuth)通道正式下线 gpt-5.5 与 gpt-5.5-pro,仅在标准 OpenAI Platform API Key 通道保留支持。 | 通道感知选路隔离:调度器在为 gpt-5.5 / gpt-5.5-pro(或经模型映射指向 gpt-5.5 的自定义别名)选路时自动排除 ChatGPT OAuth 账号,仅路由至支持该模型的 OpenAI API Key 账号;若分组将 gpt-5.5 映射至 gpt-6.1-sol 等在线模型,则按映射后的目标模型正常调度。 |
gpt-5.5 / gpt-5.5-pro 模型目录过滤与 404 迁移指引 | 官方建议在订阅通道迁移至 gpt-6.1-sol(GPT-6.1 Sol)或 gpt-6-luna(GPT-6 Luna)。 | 目录隐藏与明确 404 指引:当分组仅包含 ChatGPT OAuth 账号且无可用 API Key 账号时,GET /v1/models 与 Codex 模型目录会自动隐藏已下线的 gpt-5.5;若直接调用 gpt-5.5,网关返回 404 model_not_found,明确提示选择替代模型 GPT-6.1 Sol(gpt-6.1-sol)或 GPT-6 Luna(gpt-6-luna),或配置支持 gpt-5.5 的 API Key 上游。 |
Codex 订阅档位门禁模型(如 gpt-5.3-codex-spark) | 部分专属模型(如 gpt-5.3-codex-spark)仅对特定订阅计划(如 ChatGPT Pro)开放,普通 Plus / Team 账号调用会被上游拒绝。 | 账号能力校验与自动选路:网关在调度阶段校验所选账号的计划档位是否支持该模型;若当前账号不满足要求,调度器自动切换至具备权限的备选账号。 |
2. max_output_tokens / max_completion_tokens / max_tokens(输出上限与载体迁移)
| 参数 / 场景 | OpenAI 官方规范与 Migration Guide | UniGateway 处理规则 |
|---|---|---|
max_output_tokens(/v1/responses) | Responses API 的官方输出上限字段,控制单次响应生成的最大 Token 总数(包含不可见的 reasoning_tokens 与可见输出 Token),要求整数值 >= 1。 | 官方规范校验与最小阈值钳制:若传入 max_output_tokens < 1(如 0 或负数),网关直接返回官方格式的 400 Bad Request(code: "integer_below_min_value");若传入 1 <= max_output_tokens < 16,出站前自动向上钳制为 16 以满足推理模型最小输出约束;当请求经由 Codex OAuth 通道转换时,网关自动确保 max_output_tokens 不低于上游规定的最小阈值(128)。 |
/v1/responses 误传 max_tokens 或 max_completion_tokens | /v1/responses 仅识别 max_output_tokens,传入 Chat Completions 的输出上限字段会被拒绝。 | 向 max_output_tokens 自动迁移:若客户端在 /v1/responses 端点误传了 max_tokens 或 max_completion_tokens,网关自动将其读取并迁移为 max_output_tokens(当未显式指定 max_output_tokens 时),随后移除原字段。 |
/v1/chat/completions 推理模型传入旧版 max_tokens | Migration Guide:在 /v1/chat/completions 中,max_tokens 已标记为弃用(Deprecated)。对于所有推理模型(o1 / o3 / o4-mini / GPT-5.x / GPT-6.x),官方要求使用 max_completion_tokens,传入 max_tokens 会直接返回 400 Unsupported parameter: 'max_tokens'。 | 跨代载体自动迁移:在 /v1/chat/completions 端点,当目标模型为推理模型时,网关自动将 max_tokens 或误传的 max_output_tokens 迁移至 max_completion_tokens 并删除旧字段;当目标模型为传统非推理模型(如 gpt-4o)且误传了 max_output_tokens 时,自动迁移为 max_tokens。 |
同时传入 max_tokens 与 max_completion_tokens | 同时携带新旧两个输出上限字段且数值冲突时属于歧义请求。 | 冲突校验与归一化:在绑定了固定协议规则的通道上,若客户端同时传入 max_tokens 与 max_completion_tokens 且数值不一致,网关返回 400 提示字段冲突;数值一致时自动归一为目标协议字段。 |
3. instructions 与 developer / system 角色(系统与开发者指令)
| 参数 / 场景 | OpenAI 官方规范与 Migration Guide | UniGateway 处理规则 |
|---|---|---|
instructions(/v1/responses) | Responses API 顶层字符串字段,用于提供系统级指令。在使用 previous_response_id 进行多轮续写时,上一轮的 instructions 不会自动继承,可通过本轮指定新的 instructions 覆盖。 | 原生透传与双向补齐:在官方 API Key 通道原样透传;在 Codex OAuth 通道上,若请求未携带 instructions,网关自动注入默认基础指令以满足上游必传校验;当请求从 /v1/responses 转换至 /v1/chat/completions 上游时,顶层 instructions 会自动转换为首条系统/开发者消息。 |
developer 与 system 角色(OpenAI 原生通道) | Migration Guide:自 o1 与 GPT-5 系列起,OpenAI 引入 "developer" 角色替代传统的 "system" 角色,用于标识应用开发者提供的指令(在指令层级中高于 "user",低于平台级规范)。 | 完整保留角色语义:在 /v1/responses 及支持 developer 角色的 OpenAI 上游中,网关完整保留 developer 与 system 角色语义,不会将 developer 降级为 user。 |
developer 角色在第三方兼容通道的降级 | 部分第三方通道(如部分原生 Chat Completions 端点)仅支持 "system" 角色,不识别 "developer" 角色。 | 角色自适应改写:当目标上游为不支持 "developer" 角色的通道时,网关在转发前自动将 messages[].role == "developer" 改写为 "system",防止上游返回 invalid role 错误。 |
4. input 与 messages(对话输入、多模态与历史项规范化)
| 参数 / 场景 | OpenAI 官方规范与 Migration Guide | UniGateway 处理规则 |
|---|---|---|
/v1/responses 传入旧版 messages 或 prompt | Responses API 标准输入字段为 input(接收纯文本字符串或结构化 Item 数组)。 | 旧格式入站兼容:若客户端在 /v1/responses 端点未传 input,而是传入了 Chat Completions 的 messages 数组或旧版 Completions 的 prompt 字符串,网关在入口处自动将其转换为标准 input 与 instructions。 |
input[] 无头内容块包装 | input[] 中的内容块需包裹在带 role 的 message 对象内。 | 自动补齐外层消息结构:若 input[] 数组中包含仅带 type("input_text" / "input_image" / "input_file")而缺少外层 role 的裸内容块,网关自动将其包装为 {"type": "message", "role": "user", "content": [...]}。 |
内容块类型与角色对齐(input_text vs output_text) | Responses API 严格区分输入与输出内容块类型:user / system / developer 消息的内容块必须为 input_text(或 input_image / input_file),而历史 assistant 消息回放的内容块必须为 output_text(或 refusal)。 | 按角色自动纠正 content[].type:网关遍历 input[] 中的 message 项,将 user / system / developer 角色下的 "text" 或 "output_text" 自动纠正为 "input_text";将 assistant 角色下的 "text" 或 "input_text" 自动纠正为 "output_text";对于非 message 类型的输入项(如 function_call),自动剥离误带的 content 字段。 |
| 第三方通道的内容块展平与扩展清理 | 部分第三方通道对内容块数组格式及附加字段有严格限制。 | 按需展平与字段清理:在此类通道上,网关自动将纯文本块数组展平为单字符串(保留含 image_url 或缓存断点的复合结构),并剥离内容块上的 annotations 与回声 reasoning 字段。 |
input[] 项 id 格式与 call_id 约束 | Responses API 对 input[] 各项的 id 格式有严格前缀与长度校验(仅允许字母/数字/_/-,长度 <= 64 字符,message 要求 msg 前缀、reasoning 要求 rs、web_search_call 要求 ws、custom_tool_call 要求 ctc、tool_search_call 要求 tsc、function_call 与 custom_tool_call_output 要求 fc 前缀),且仅工具调用配对项允许携带 call_id。 | 非法 id 与 call_id 剥离:若 input[] 中某项的 id 含非法字符、超出 64 字符或前缀与 type 不匹配,网关自动移除该项的 id 字段(保留业务载荷);同时自动移除误挂在 message、reasoning 或 image_generation_call 项上的 call_id 字段。 |
| 客户端私有调试与追踪元数据清洗 | 许多 IDE / Agent 客户端会在 messages[] 或 input[] 中附带私有追踪字段(如 messageId、traceId、conversationId、agent 等),严格校验的上游会因此返回 400 Extra inputs are not permitted。 | 主动剥离与反应式重试剥离:在 Chat Completions 出口自动剥离 messages[] 中的客户端私有追踪字段(messageId/message_id、model/requestModel*、traceId/trace_id、conversationId/conversation_id/conversationRequestId、agent);在 /v1/responses 主动剥离 input[] 中的 internal_chat_message_metadata_passthrough;若上游因其他未知扩展属性返回 400,网关在自适应重试时自动剥离对应字段并重试。 |
多模态输入(input_image / image_url 与 input_file) | /v1/responses 使用 {"type": "input_image", "image_url": "..."} 与 {"type": "input_file", "file_data": "...", "filename": "..."};/v1/chat/completions 使用 {"type": "image_url", "image_url": {"url": "..."}}。 | 跨协议双向转换与空数据防护:在 Chat Completions 与 Responses 互转时自动映射图像与文件结构;若检测到空的 Base64 Data URI(如 "data:image/png;base64," 无实际载荷),网关自动过滤该空图像块,避免上游解析崩溃。 |