OpenAI API/OpenAI 请求参数与输入格式

OpenAI Responses 与 Chat Completions 顶层请求参数、消息格式与输入项规范化完整参考。

OpenAI 请求参数与输入格式

本文档详细说明通过 UniGateway 调用 OpenAI 规范端点(Responses API POST /v1/responses 与 Chat Completions API POST /v1/chat/completions)时的完整顶层请求参数定义、消息与输入项结构、多模态块格式及网关规范化规则。


章节导引

本篇为 OpenAI API 参考文档的第 2 章节:

  1. Responses 概述与快速开始
  2. 请求参数与输入格式(当前章节)
  3. 扩展推理与会话状态
  4. 结构化输出与采样参数
  5. 工具调用与内置工具
  6. 响应、流式与错误处理

顶层请求参数一览

在向 UniGateway 的 OpenAI 接口发送 JSON 请求体时,支持以下顶层参数:

参数名适用端点类型必填说明
model双端点通用string是目标模型 ID(支持带推理强度后缀简写,如 gpt-5.4-high)
input/v1/responsesstring | array是Responses API 的输入文本或结构化输入项(Items)列表
instructions/v1/responsesstring否系统级/开发者级指令(优先级高于 input 中的对话历史)
messages/v1/chat/completionsarray是Chat Completions 对话消息数组(包含 developer/system/user/assistant/tool 角色)
max_output_tokens/v1/responsesinteger否Responses API 最大生成 Token 数(包含推理 Token 与可见输出 Token,要求 >= 1,小于 16 时自动钳制为 16)
max_completion_tokens/v1/chat/completionsinteger否Chat Completions 最大生成 Token 数(包含推理 Token 与可见输出 Token,推荐替代 max_tokens)
max_tokens/v1/chat/completionsinteger否旧版最大输出 Token 数(在推理模型与 Responses 端点上由网关自动迁移)
reasoning/v1/responsesobject否推理配置对象,详见 扩展推理与会话状态
reasoning_effort/v1/chat/completionsstring否Chat Completions 推理强度控制(none / minimal / low / medium / high / xhigh / max)
tools双端点通用array否可用工具列表,详见 工具调用与内置工具
tool_choice双端点通用string | object否工具选择策略("auto" / "none" / "required" 或指定特定函数/工具)
parallel_tool_calls双端点通用boolean否是否允许模型在单回合中并行发起多个工具调用
text/v1/responsesobject否文本输出配置,包含结构化输出 text.format 与详细度 text.verbosity
response_format/v1/chat/completionsobject否结构化输出格式配置(text / json_object / json_schema)
temperature / top_p双端点通用number否采样温度与核采样阈值,详见 结构化输出与采样参数
logprobs / top_logprobs双端点通用boolean | integer否输出对数概率配置(仅在非推理模型或 effort="none" 时生效)
presence_penalty / frequency_penalty / logit_bias/v1/chat/completionsnumber | object否词频惩罚与 Token 偏置(仅在非推理模型或 effort="none" 时生效)
store双端点通用boolean否是否在服务端持久化响应以供后续引用或评估
previous_response_id/v1/responsesstring否上一轮响应 ID(用于服务端有状态多轮续写)
truncation/v1/responsesstring否上下文超长时的截断策略("auto" 或 "disabled")
include/v1/responsesarray<string>否指定在响应中额外返回的字段(如 "reasoning.encrypted_content")
prompt_cache_key双端点通用string否提示缓存路由键,用于提升相同前缀请求的缓存命中率
prompt_cache_retention双端点通用string否提示缓存保留策略(如 "in_memory" 或 "24h")
prompt_cache_options/v1/responsesobject否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/completionsobject否OpenRouter 兼容提供商路由偏好(only / order / ignore / quantizations / zdr)

核心参数三维规范对比

UniGateway 对所有入站请求严格对齐 OpenAI 官方规范与 Migration Guide,并在转发多云及第三方通道时提供确定性的协议规范化保障:

1. model(模型标识、代际路由与通道约束)

参数 / 场景OpenAI 官方规范与 Migration GuideUniGateway 处理规则
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 GuideUniGateway 处理规则
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_tokensMigration 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 GuideUniGateway 处理规则
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 GuideUniGateway 处理规则
/v1/responses 传入旧版 messages 或 promptResponses 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," 无实际载荷),网关自动过滤该空图像块,避免上游解析崩溃。