OpenAI兼容的API格式长什么样？请求与响应结构一次看懂

很多人接中转站或第三方平台时踩同一个坑：文档写着「兼容 OpenAI」，复制官方示例却报参数错误或返回读不出来。其实兼容只保证结构骨架一致，字段含义、必填项和返回形态各有差异。这篇把一条请求从发出去到收回来拆成几层，逐层告诉你看哪里、怎么对照、哪里容易错位，读完你能自己判断一个接口到底兼容到什么程度。

很多人接中转站或第三方平台时踩同一个坑：文档写着「兼容 OpenAI」，复制官方示例却报参数错误，或者返回读不出来。其实兼容只保证结构骨架一致，字段含义、必填项和返回形态各有差异。这篇把一条请求从发出去到收回来拆成几层，逐层告诉你看哪里、怎么对照、哪里容易错位。

读完你能自己判断一个接口到底兼容到什么程度：不是看它宣传页怎么写，而是照着字段清单一条条比。下面的判断标准偏工程视角，涉及具体模型价格或可用清单这类会变动的数字，一律建议到站内页面核对当时的数字，不要照抄任何一篇旧文章的结论。

「OpenAI 兼容」到底兼容了什么

兼容的通常是四层：请求路径的写法、鉴权头的写法、请求体的字段名、返回结构的骨架。这四层对上，你换一个 base_url 大概率能跑通。但它不包含模型能力、参数默认值、流式行为细节和错误文案，这些各家都可能不一样。所以「兼容」是一个程度问题，不是一个开关。

什么情况下不适用：如果你接的是 Anthropic 那套协议，或者某家自研协议，结构对不上是正常的，不能按兼容处理，老老实实为它写一层独立的适配。硬套兼容模板只会让你在字段映射上反复返工。

一条请求的骨架：端点、鉴权、请求体

端点是「域名 + 版本段 + 资源名」的拼接。换平台时通常只改域名部分，版本段和资源名的写法各家可能不同，有的保留斜杠，有的换成别的分段写法。这一层最好放在配置里，不要硬编码到业务代码里。

1. 先确认端点拼法把域名、版本段、资源名拆成三个配置项，发一条最小请求确认能通，通了再往下走。
2. 再确认鉴权头检查请求头里的鉴权键名和值的前缀写法，值通常以固定前缀加密钥组成，键名各家偶有差异。
3. 最后确认请求体编码确认请求体是 JSON 并且带对了内容类型头，否则有些网关会直接拒掉，返回的错误还很难懂。

密钥管理单独说一句：别写进代码仓库，别放到前端。前端调用等于把密钥公开，任何人打开开发者工具都能拿到。要用就经过你自己的后端转发，顺便把日志留在自己能查的地方。

• 域名放配置，不硬编码
• 版本段和资源名分开配，方便逐段替换
• 鉴权值只从环境变量读，日志里做脱敏
• 请求体统一用序列化工具生成，别手拼字符串
• 给每次调用带上自己的追踪标识，方便对账

messages 数组：系统、用户、助手三种角色怎么排

消息是一个对象数组，每个对象至少有两个键：角色和内容。角色决定这句话被当成指令还是当成上文。系统角色是全局设定，用户角色是你这次的输入，助手角色是上一轮模型的回复。顺序就是模型看到的时间线，排错了上下文就读歪了。

常见的排法：系统指令放最前面，然后按时间顺序把用户和助手的往来一条条往后排，最后一条是这次的用户输入。多轮对话不要只保留最后一句，模型不会自动记得前面聊过什么，除非你把它作为历史消息传进去。

系统角色

全局约束，放最前面，用来定人设、格式和边界

用户角色

本次输入或历史里用户说的话

助手角色

历史里模型自己说过的话，用来保持上下文连贯

内容字段

多数场景是字符串，多模态场景是一个分块数组

多模态是很多兼容实现的坑：内容不一定是纯字符串，在传图片或文件时它变成数组，里面按类型分块。有的实现只支持字符串，你传数组它会静默忽略，或者直接报一个跟内容无关的参数错误。接之前先确认目标平台支持到什么程度。

采样参数：温度、最大长度、停止词各管什么

温度控制随机程度。写代码、做抽取、要稳定复现的任务，把它调低；写文案、做头脑风暴，可以调高。关键是别在同一个任务里来回改，改了之后输出风格会漂移，排查问题时你会怀疑是提示词的问题，其实是参数在动。

最大输出长度是最容易被误解的一个：它限制的是这次回复最多能有多长，跟你总共能塞多少上下文是两码事。设小了会出现截断，而截断不一定报错，很多时候只是 response 里的结束原因变成长度类的原因，你得去看那个字段才知道。

什么情况下不适用：有的平台对这些参数只做透传不做校验，你传了它收下但不生效。判断方法是同一个提示词用该参数的两个极端值各跑一次，输出形态没变化，基本就是没生效。

响应结构：choices、finish_reason 与 usage 三个关键块

返回体里最先要认的是 choices，它是一个数组，每一项里有消息对象和结束原因。多数场景只取第一个元素的消息内容，但别假设它一定存在，也别假设数组长度永远是一。异常返回里它可能是空的，业务代码要能接住这种情况。

结束原因告诉你这次为什么停：正常结束、撞到长度上限、被内容策略拦下，还是别的原因。排查「回答不完整」这个问题时，第一眼看它，比看内容本身快得多。usage 则是计费依据，输入和输出通常分开记，有些实现会缺这个字段或者全为零。

• 先判 choices 是否为空，空了就别取下标
• 取第一个元素的消息内容前，先确认键存在
• 看结束原因区分正常结束和截断
• 把 usage 的输入输出分别落库，方便对账
• 缺 usage 或全为零的实现，另外记一份调用次数做兜底

关于调用成本这类会浮动的数字，不要在代码里写死估算，到 价格追踪（/price-watch） 这类站内页面核对当时的数字，再决定你的用量策略。想知道某个平台靠不靠谱，可以配合 中转站目录（/sites） 里的信息一起看。

流式返回：结构差在哪，解析要注意什么

开启流式以后，返回不再是一整个 JSON，而是一行行以固定前缀开头的数据片段，最后一个片段是终止标记。每个片段里同样是 choices 数组，但取增量文本的键名和非流式不一样，混用会取到空字符串，表现为前端一直转圈却没有字出来。

1. 按行切分而不是整体解析把响应流按行读，逐行判断前缀是不是数据行，不是就跳过，别试图一次性整体反序列化。
2. 遇到终止标记就收尾终止标记出现后停止追加，并给前端发一个结束信号，避免连接挂着不关。
3. 按到达顺序拼接增量严格按到达顺序追加文本，不要排序、不要去重，否则输出顺序会乱。

流式还有两个细节容易漏：一是结束原因可能只出现在某几个片段里，不是每片都有；二是用量统计有的平台在流式下放在最后一片，有的干脆不给。接入前拿一小段测试流确认一遍，比看文档快。

错误结构和响应头：对账与排错的两条线索

错误体一般是一个对象套一个错误说明，里面有类型和消息。类型是分诊依据，消息是给人看的。照类型分诊比逐条读文案快得多，因为文案各平台都在改，类型相对稳定：鉴权类、参数类、限流类、服务端类，处理策略完全不同。

响应头里常带请求编号和限流余量。请求编号建议每次调用都落到日志，出问题时拿它去跟平台对账，比描述「大概几点那次」有用得多。限流余量则可以用来做主动限速，别等被拒绝才开始退避。

什么情况下不适用：有些平台把错误包成正常状态码返回，这时候看状态码没用，得看响应体里有没有错误字段才判得准。所以解析逻辑里状态码和响应体两条都要判，缺一条都会漏。

拿到一个新接口，按这个顺序自检一遍

1. 发最小请求只带一条用户消息，不带任何可选参数，确认能通。不通就先解决端点和鉴权，别急着叠参数。
2. 叠必填参数再跑把系统指令、温度、长度上限逐个加上，每加一个跑一次，确定哪个参数引发变化。
3. 对照字段清单核返回确认 choices、消息内容、结束原因、用量统计四个位置的名字和类型是否与预期一致。
4. 人为制造一个错误故意传错参数或错密钥，看错误结构能否被你的分诊逻辑正确归类。
5. 把差异写进适配层所有字段映射和错误转换集中在一处，业务代码只依赖你自家的内部结构。

这套顺序的价值在于：把「能不能用」和「差异在哪」分成两步。很多人一上来就叠满参数，报错了不知道是哪一层的问题，来回删参数反而更慢。先跑通最小路径，再逐项加，问题定位成本会低很多。

上线前建议再做一次对照检查：把目标平台的字段清单和你的适配层列成一张表，标出哪些是直接映射、哪些是转换、哪些是忽略。这张表就是以后换源时唯一要改的地方。具体平台的可用性和口碑，可以到 可信度排行（/rankings） 或 测速工具（/tools/speed-test） 看看当时的情况再决定。