openai-openapi
openai/openai-openapi加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
当你向 ChatGPT 发送一条消息，背后的请求是如何到达 OpenAI 服务器的？API 请求走的是哪条路径、带了什么参数、返回了什么格式？如果你曾经在调试 AI 应用时感到迷茫——为什么模型不听话、为什么 token 超出限制、为什么响应格式解析失败——那么你并不是一个人。对于接入 OpenAI API 的开发者而言，理解 API 的完整结构是写出稳定代码的前提。
openai/openai-openapi 仓库正是这个问题的系统性解决方案：由 OpenAI 官方维护的 OpenAPI 规范文档，机器可读，开发者可用。
openai/openai-openapi 并非一个普通的 GitHub 仓库。它是 OpenAI 官方发布的 OpenAPI 3.1 规范文件，以 openapi.yaml 和 openapi.json 两种格式，完整描述了 OpenAI REST API 的所有端点、认证方式、参数定义和请求/响应结构。截至 2025 年，该规范版本已更新至 v2.3.0，涵盖了从文本补全、聊天完成到文件上传、微调训练、图像生成等全部核心能力。
这个仓库的特殊之处在于它是 OpenAI 内部规范的上游镜像：OpenAI 团队在内部仓库修改 API 规范后，会自动同步更新到本仓库，外部贡献者不能直接修改规范文件，必须通过 Issue 反馈走上游流程。这确保了规范的权威性和一致性。
很多开发者只知道去 OpenAI 官网查阅 API 文档，但官方文档是给人读的，openai-openapi 是给工具读的。两者的使用场景完全不同：
场景一：生成强类型客户端 SDK
OpenAPI 规范可以被 Swagger Codegen、OpenAPI Generator 等工具直接消费，自动生成 Python、TypeScript、Go、Java、Ruby、.NET 等语言的 类型安全客户端代码。当你用 OpenAPI Generator 读取 openapi.yaml 后，它会为你生成包含端点函数、请求类、响应模型的完整 SDK，与手写 API 调用相比，IDE 自动补全、类型检查、参数校验一应俱全。
场景二：API 模拟与测试
通过规范文件，可以用 Prism、Mockoon 等工具快速搭建 Mock 服务器，在没有真实 API Key 的情况下进行开发和测试。规范中定义了每个端点的请求格式和响应模型，Mock 工具可以据此自动生成符合规范的模拟响应，大幅提升开发效率。
场景三：API 文档自动化
将规范导入 Swagger UI 或 Redoc 可以自动渲染出交互式 API 文档，支持在线调试每个端点。更进一步，可以将规范集成到内部 API 管理平台，为团队提供统一的接口参考。
场景四：确保 OpenAI SDK 版本一致性
OpenAI 官方维护了 6 个语言的 SDK（Python、JavaScript/TypeScript、.NET、Go、Java、Ruby），这些 SDK 都是从同一套 OpenAPI 规范生成的。因此，openai-openapi 仓库实际上就是这 6 个 SDK 的"源头规范"——当你发现某个 SDK 行为与文档不符时，查看规范文件是最权威的判断依据。
根据 OpenAPI 规范的结构分析，OpenAI API 共划分为以下功能分组：
| 模块 | 功能说明 |
|---|---|
| Assistants | 构建可调用模型和工具的助手（deprecated，建议迁移至新端点） |
| Audio | 语音转文本（TTS）和文本转语音（STT）能力 |
| Chat | 多轮对话补全，是当前最核心的 API |
| Conversations | 管理会话和会话项 |
| Completions | 传统文本补全 API（非 Chat 模式） |
| Embeddings | 将文本转为高维向量表示，用于语义搜索、相似度计算 |
| Evals | 在 OpenAI 平台上管理和运行评估任务 |
| Fine-tuning | 微调自有数据集，定制专属模型 |
| Graders | 管理 grader 任务，用于评估 LLM 输出质量 |
| Batch | 批量异步 API 请求，适合大规模数据处理 |
| Files | 上传和管理文件，支持 Assistants 和微调 |
| Uploads | 分段上传大文件（> 512MB） |
| Images | DALL·E 图像生成 |
| Models | 列出和描述可用模型 |
| Moderations | 内容安全审核，检测有害文本/图像 |
| Audit Logs | 审计日志，记录组织内用户行为 |
服务端点统一托管在 https://api.openai.com/v1，认证方式为 API Key（Authorization: Bearer 头部）。
# 下载最新 YAML 规范
curl -L https://raw.githubusercontent.com/openai/openai-openapi/main/openapi.yaml \
-o openai-openapi.yaml
# 或下载 JSON 版本
curl -L https://raw.githubusercontent.com/openai/openai-openapi/main/openapi.json \
-o openai-openapi.json
# 安装 OpenAPI Generator CLI
npm install @openapitools/openapi-generator-cli -g
# 生成 TypeScript 客户端
openapi-generator-cli generate \
-i openai-openapi.yaml \
-g typescript-axios \
-o ./openai-sdk
安装 Swagger Viewer 扩展，在 VS Code 中直接渲染 OpenAPI 规范，实时调试每个端点。
规范文件不可直接编辑：外部贡献者无法直接修改 openapi.yaml，必须通过 Issue 走上游反馈流程，OpenAI 团队在内部规范仓库处理后再同步到本仓库。
规范更新有时差：当 OpenAI 发布新的 API 功能时，规范文件可能存在数小时到数天的同步延迟，在此期间应以 OpenAI 官方文档为准。
这不是可运行项目：这是一个纯文档仓库，不包含任何可执行代码或服务端实现，不能通过 docker run 或本地环境运行它。
Assistants API 旧端点已废弃：规范中标记了 /assistants 端点为 deprecated，实际生产使用应参考最新的 Assistants API 端点。
openai/openai-openapi 代表了 AI 开放平台走向标准化的重要一步。OpenAPI 规范作为 REST API 领域的事实标准，被 OpenAI 采用意味着整个 AI API 生态可以无缝接入现有的开发者工具链。从自动生成 SDK 到构建 Mock 服务器，从 CI/CD 集成到内部文档平台，这个规范文件是整个 OpenAI 开发者生态的"地基"。
随着 OpenAI API 能力不断扩展，规范文件也在持续演进。对于需要深度集成 OpenAI 能力的开发者而言，理解并善用这份规范，是从"会用 API"走向"精通 API"的关键一步。