调用 openai 的 api

接入与开发

从零跑通 OpenAI 接口请求与结果解析:请求字段怎么填、响应怎么读、报错怎么排,给新手一份能照着走的落地顺序。

第一次调用 OpenAI 接口,多数人卡的不是鉴权,而是「参数填了不知道对不对、返回一大坨不知道取哪个字段、报错码看不出下一步」。这篇不讲协议原理,只按「先发一次最小请求 → 看懂响应结构 → 排掉常见错 → 加超时和日志」的顺序走一遍,让你在本地把一次调用真正跑通并能复盘。

第一次调用 OpenAI 接口,卡住你的往往不是鉴权,而是「参数填了不知道对不对、返回一大坨不知道取哪个字段、报错码看不出下一步」。这篇不讲协议原理,只按「先发一次最小请求 → 看懂响应结构 → 排掉常见错 → 加超时和日志」的顺序走一遍,目标是让你在本地把一次调用真正跑通,并且能复盘。

整篇只做一件事:把一次请求从发出到解析变成可重复的动作。凡是涉及具体价格、速率档位、模型版本这类会变动的数字,正文里都不写死,一律让你去站内页面核对当时的数字。这样你照着做的时候,拿到的就是当下的真实情况,而不是过期结论。

第一步:先发一次最小请求,别一上来就堆参数

最小请求的意思是:只保留让接口能识别并返回的三个部分——用哪个模型、消息数组里一条 user 内容、鉴权头。其余像温度、最大输出长度、系统提示这些先全部留空。跑通之后再一个一个加,加一个测一次,这样出问题时你立刻知道是哪个新参数引起的。

  • 鉴权头格式固定,是 Bearer 加一个空格再加密钥,少一个空格就会走到鉴权失败那类报错,而不是参数报错。
  • 消息数组是一条条对象,role 和 content 成对出现;role 的取值和拼写是硬要求,拼错会被直接判为请求体不合法。
  • 请求地址由基础地址加路径拼成,别把两段都写成完整 URL,重复拼接是新人最常见的 404 来源。
  • 发送前先把请求体打印成 JSON 看一眼,比事后靠猜快得多,也能顺手确认 content 是不是空的。
  1. 准备一份最小请求体只放模型名和一条 role 为 user 的消息,content 写一句短话,比如「用一句话说明什么是接口」。写成 JSON 字符串,别用模板拼字符串。
  2. 加上鉴权头再发请求头里放鉴权字段和内容类型字段。发出去之前先把完整请求头打印一遍,确认空格和大小写没问题。
  3. 看返回码,不看正文先只看状态码。成功就往解析走,失败就先按后面的排查表对号入座,别急着改参数。
  4. 固定成脚本再改把这次能跑的请求存成一个文件或一个函数,后面所有调试都在这个基础上改,不要每次重敲。

响应怎么读:先认字段,再决定取哪一段

返回体第一层是几个并列的区块,先分清「候选内容」「用量统计」「其他元信息」这三块,不要在错误的层级里找文本。很多新手把整个返回体打印出来看到一堆嵌套就慌了,其实只要记住「正文在候选内容的第一条里」,取字段的路径就定下来了。

候选内容
通常是一个数组,因为一次可以返回多条;取第一条再取其中的正文部分,才是你要的字符串。
用量统计
输入和输出两个计数是分开的,做成本估算时两个都要拿,只算输出会偏小。
元信息
模型名、请求标识等,调试时用来确认这次请求到底打到了哪个模型。
结束原因
告诉你这次是被正常说完、被长度截断,还是走了工具调用分支。
你看到的形态大概率原因下一步动作
正文是对象不是字符串只取了一层,没取到最里面那层把取值路径再往里走一层,先打印类型确认
正文为空但有其他内容被截断或走了工具调用分支看结束原因字段,再决定是放宽长度还是换解析方式
用量计数只有输出没有输入解析时漏掉了输入那一项把两个计数都取出来,做成本估算时一起用
返回一串流式片段开启了流式返回要么按片段拼接,要么这次先关掉流式再跑一遍

把「取字段」的路径写成一个小函数固定下来,换模型或换中转时只改地址和模型名,解析逻辑不动。这样做的好处是:出问题时你能确定是链路问题还是解析问题,排查范围直接砍一半。想对比不同来源的响应差异,可以到 /sites 里找对应通道自己发一次同样内容来对照。

超时、重试与日志:跑通之后立刻补上这三件事

连接超时和读取超时要分开放。连接超时管的是「连不上」,可以设短一点;读取超时管的是「连上了但等结果」,要按你最长输出预留。用同一个秒数套所有请求,要么误杀慢请求,要么卡住不返回。具体档位不用抄别人的,到 /tools/speed-test 量出你自己的延迟基线再定。

  • 重试只对可重试的错生效:超时和网关类错误可以退避重试,参数错和鉴权错重试再多次也没用,反而放大账单。
  • 日志至少记四个字段:请求时间、模型名、用量计数、耗时;缺了用量复盘不了成本,缺了耗时定位不了慢。
  • 把一次请求的输入输出留一份可回放的记录,排查「同一句话昨天行今天不行」时能直接对上。
  • 并发别一上来拉满,先单条跑通再小批量试,触到限流再退避;限流口径可以对照 /tools/verify 里的检测方式理解。
现象先查哪里常见结论
鉴权失败类报错鉴权头空格、密钥是否带多余字符格式问题居多,不是密钥本身错
请求体不合法消息数组结构、role 取值拼写多半是字段层级或拼写写错
连不上或超时基础地址、网络出口、超时设置地址拼错或读取超时设太短
返回慢但没报错输出长度、并发数、读取超时输出太长或并发压住了,先减量再观察

成本相关的事不要凭印象。你想知道某次调用大概落在什么区间,去 /price-watch 核对当时的数字,再拿自己日志里的用量计数去乘,比任何别人给的结论都准。

先跑通最小请求,再补解析,最后补超时和日志;顺序反过来,你会在三个问题里同时打转。
下一步把你本地那条最小请求保存成脚本,再去站内核对一次当下的价格与速率口径,然后按排查表把手上报错对号入座。

常见问题

请求发出去了但一直没返回,是接口挂了吗?

先别下结论。多数情况是读取超时设得太短,而模型还在生成。把读取超时按最长输出放宽,再看是否稳定返回。如果换成极短提示词也一样卡,再怀疑网络链路,用站内的测速页量一次延迟基线,比反复重发有效。

返回里有内容但格式不是我想要的,是接口的问题吗?

通常不是。默认返回的是一段自然语言,想拿固定结构得在提示词里明确要求,或者改用支持结构化输出的参数。先确认自己取的是不是候选内容那一条的正文,很多时候结构不对只是取错层级。要稳定拿到格式,去看提示词与结构化输出那篇的做法。

报错码看不懂,按什么顺序排?

按「鉴权 → 地址 → 请求体 → 限流」的顺序查一遍:先确认密钥和鉴权头格式,再确认基础地址有没有多拼一层路径,然后看请求体是不是缺了必填或拼错了取值,最后才考虑是不是请求太密被限流。这个顺序能覆盖绝大多数新手第一次跑不通的情况。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。