企业官网建设流程全解析

如何读懂 OpenAI OpenAPI 规范 openapi.documented.yml：OpenAI API 接口参数速查指南

【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi

openai-openapi 仓库收录了 OpenAI 官方发布的机器可读 OpenAPI OpenAPI 规范（文档版即 openapi.documented.yml，本仓库同步发布由同一来源生成的openapi.yaml与openapi.json），覆盖每个端点的请求参数、合法取值和错误结构。第一次调用 OpenAI API，或长期靠抄示例却查不到参数在哪的开发者，可以在这份规范里直接验证任何字段。

规范文件到底在描述什么

OpenAPI 规范（OAS）是用 YAML/JSON 描述 REST API 的方式：端点、参数、请求与响应结构、鉴权方式全部写成数据，既可以导入文档查看器，也可以作为客户端代码的生成源。这个文件声明openapi: 3.1.0，info.version当前为2.3.0，整个 openapi.yaml 超过 11 万行；官方 Python、JavaScript 等 SDK 都由它生成。

和只翻示例代码相比，规范回答的是"字段有哪些、取值范围是什么、失败时服务端返回什么"，每一项都能对照文件原文核实。

上图就是这份规范渲染出的参考页效果，规范里的内容最终都会变成你看到的文档。

把规范拿到本地并用 Redoc 打开的步骤

先克隆仓库（已有本地副本可跳过）：

git clone https://gitcode.com/GitHub_Trending/op/openai-openapi

再用 Redoc 打开规范文件，需要本机有 Node.js 环境，首次运行会自动下载依赖：

npx redoc openapi.yaml

运行后访问终端提示的本地地址（默认 http://localhost:8000），左侧是 17 个模块的导航树，点开后每个端点的参数表和示例都能展开查看。同一内容的 openapi.json 也可以直接导入 Swagger UI 获得交互式 Try it out。

🔍 顶层字段速览：快速定位 API 参数字段

规范顶层字段不多，各司其职：

openapi: 3.1.0 # 规范方言版本 info: # 标题、版本号（2.3.0）、联系方式、许可证 servers: # 服务地址 https://api.openai.com/v1 security: # 全局鉴权 ApiKeyAuth，即 Bearer token tags: # 功能模块清单，驱动文档导航 paths: # 所有端点定义（路径 + HTTP 方法） components: # 可复用 schema 与响应，$ref 的指向目标

查参数的固定路线：paths下找到端点 →requestBody的$ref指到components/schemas里的 schema → 逐字段读约束。

tags下的完整模块清单：

拆解 POST /chat/completions 端点看细节

以使用频率最高的聊天补全接口为例，规范中的定义（节选）：

/chat/completions: post: operationId: createChatCompletion tags: [Chat] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateChatCompletionRequest' responses: '200': # 常规返回；stream 为 true 时是 text/event-stream '400': # 参数非法，错误体为 ErrorResponse '429': # 触发限流 '500': # 服务端错误

operationId是 SDK 方法名的来源；requestBody通过$ref按名字引用components/schemas里的 schema，避免把整个结构内联展开。CreateChatCompletionRequest用allOf复用公共字段：messages要求至少一个元素（minItems: 1），frequency_penalty限定在 [-2, 2]，response_format是oneOf三选一（text / json_object / json_schema），按type字段区分。

请求参数与 schema 的对应关系和真实调用

下面 Python 示例的每个参数都能在CreateChatCompletionRequest里逐字段对上：

from openai import OpenAI client = OpenAI() # 从环境变量读取 OPENAI_API_KEY resp = client.chat.completions.create( model="gpt-4o", # 对应 model 字段 messages=[{"role": "user", "content": "用一句话解释 OpenAPI 规范"}], response_format={"type": "json_object"}, # oneOf 三选一，按 type 区分 frequency_penalty=0.5, # 规范限定 [-2, 2] ) print(resp.choices[0].message.content)

不想用 SDK 时可以直接发 HTTP 请求，下面这条 curl 取自规范内 Images 模块自带的示例：

curl https://api.openai.com/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{"model": "gpt-image-2.5-flare", "prompt": "A baby sea otter", "n": 1, "size": "1024x1024"}'

注意：几乎每个端点都挂着x-oaiMeta字段，内嵌 curl / python / javascript 请求示例，按 operationId 搜索就能找到现成参考。

⚠️ 读规范时的常见坑与版本跟踪

• 枚举字段按规范取值：带enum的字段只能传列表内的值，如列表接口的order只接受asc/desc，传别的值会拿到 400。
• 非 200 错误体统一处理：错误响应统一是ErrorResponse，其error对象要求type、message、param、code四个字段；部分端点有额外状态码，例如/images/generations在项目无权限时返回 403、端点退役时返回 410。
• Beta 接口靠请求头标版本：规范示例中 Assistants 相关请求都带-H "OpenAI-Beta: assistants=v2"，用 beta 功能时照抄示例的头即可。
• 留意 deprecated 标记：调用前先确认端点没有deprecated: true，如 Assistants 的列表接口；不再使用的 assistants、files 资源要及时调删除接口清理。
• 对不上先确认版本：仓库里的openapi.yaml/openapi.json是从上游来源自动同步的生成物，当前info.version为2.3.0；发现 schema 问题按 CONTRIBUTING.md 的反馈流程提 issue。

适用于三类场景：写新调用前查参数、报错时核对状态码表、自己生成客户端前导入规范。入口就在本仓库的 README.md 和两份生成的规范文件里。

【免费下载链接】openai-openapiOpenAPI specification for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-openapi