不再猜 OpenAI API 参数：3步用openai-openapi查清每个接口

不再猜 OpenAI API 参数3步用openai-openapi查清每个接口【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapiopenai-openapi 是官方发布的 OpenAI API 的 OpenAPI 3.1 规范仓库里面写清了每个接口的参数、请求体和响应结构。它适合想在调用前用可视化方式核对参数、生成类型化客户端、或想理解错误码语义的开发者。跟着本文走一遍3 步就能在自己电脑上跑起来。调用前先查参数是不是枚举值假设你正在接一个内容审核场景想调用 Moderations 接口但不确定input到底收字符串还是数组或者调/responses连续撞了 429不知道重试该等多久。翻网页文档要开好几个标签页而 openai-openapi 把接口的 schema、请求示例、响应示例都写在一个 YAML 文件里直接搜索字段名就能看到答案。三步上手从克隆到本地文档站第 1 步克隆规范仓库先跑这条命令把规范文件拉到本地git clone https://gitcode.com/GitHub_Trending/op/openai-openapi仓库结构很克制openapi.yaml 和 openapi.json 两份等价规范外加几个说明文档。日常用 YAML 这份即可。第 2 步把 openapi.yaml 导入本地文档站规范用的是 OpenAPI 3.1任何支持该版本的工具都能导入。用 Docker 起一个 Swagger UI 最省事docker run -p 8080:8080 -e SWAGGER_JSON/spec/openapi.yaml -v $PWD:/spec swaggerapi/swagger-ui浏览器打开http://localhost:8080就能看到按 Assistants、Audio、Chat、Responses 等标签分组的接口列表。Redoc 这类静态文档工具同样支持换工具时把文件路径指过去就行。第 3 步挑一个端点30 秒验证规范是否生效在文档站里搜listAssistants效果如下——端点、查询参数、默认值一目了然/assistants: get: operationId: listAssistants summary: List assistants parameters: - name: limit in: query schema: type: integer default: 20能搜到、参数类型和默认值都对得上说明规范导入成功了。规范里藏着的 3 个细节每个端点自带多语言请求示例规范里很多操作挂了x-oaiMeta.examples字段curl、python、javascript 的请求示例和响应示例直接写在 YAML 里。还是以listAssistants为例同一段规范里就有可复制的 Python 代码from openai import OpenAI client OpenAI() my_assistants client.beta.assistants.list( orderdesc, limit20, ) print(my_assistants.data)也就是说写请求前不用切换标签页找文档端点定义旁边就是示例。429 错误码附带了重试策略多数规范只写429请求过多这份文件把components/responses里的限流错误拆成了三种TooManyRequests、InferenceRateLimited、InferenceServiceUnavailable并且都带Retry-After响应头的定义。后两种还解释了语义——slow_down表示你的请求速率增长太快要降速再逐步加回server_is_overloaded表示模型侧暂时过载稍等重试即可。做重试逻辑时直接照这个语义写分支比只盯状态码可靠。官方 SDK 全部由这份规范生成README 里列了 Python、JavaScript/TypeScript、.NET、Go、Java、Ruby 六套官方 SDK它们都是从这份规范生成的。这意味着规范是唯一的真身接口参数以规范为准SDK 行为与规范对不上时多半是该报 issue 了而不是自己绕过去。3 个容易踩的坑提前说1. 改了 openapi.yaml 提交 PR 会被 CI 拒绝现象你本地改了两行参数描述提 PR 后直接挂掉。原因这两份文件是从上游源自动生成并同步的产物仓库的 Generated files unchanged CI 检查会拒绝任何对它们的改动CONTRIBUTING.md 里写明了。解决别直接改文件把版本号、端点 HTTP 方法、期望行为和合成数据的示例整理好用 issue 反馈官方会在上游源修正后自动同步过来。2. 接口调用报错实际是缺了 Beta 版本头现象照着规范调用 Assistants 相关端点返回不符合预期的结果。原因规范里该模块的示例请求带了OpenAI-Beta: assistantsv2这类头且部分端点标了deprecated: true。解决对照x-oaiMeta.examples里的请求头补全调用前顺手看一眼有没有 deprecated 标记。3. 报 schema 问题被搁置多数是信息不全现象issue 提了这个字段不对长期没人处理。原因官方要求报告包含受影响的版本号、端点和 HTTP 方法或 schema、期望行为、以及用合成数据写的最小示例并且不能带 API key、客户数据或私有 URL。解决按这个清单自查一遍再提交如果疑似安全漏洞走 SECURITY.md 的私有渠道不要发公开 issue。适合谁以及下一步如果你要给 OpenAI API 生成客户端、搭内部接口文档站或只是想在发请求前确认参数类型和重试语义这个仓库就是起点。下一步建议直接打开 openapi.yaml搜一个你明天就要调用的operationId把它的参数和示例从头到尾读一遍。【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考