OpenAI API 的 OpenAPI 规范

OpenAI API 的最新 OpenAPI 规范可以在这里找到：

https://app.stainless.com/api/spec/documented/openai/openapi.documented.yml

如需查看最新的人工维护版本的 OpenAPI 规范，请访问以下分支：

https://github.com/openai/openai-openapi/tree/manual_spec

如果您发现 OpenAPI 规范存在问题，请在此仓库中提交一个问题，OpenAI 团队将尽最大努力进行分类和解决。如需即时帮助，请访问：

https://help.openai.com/en/articles/6614161-how-can-i-contact-support

OpenAI OpenAPI 规范快速上手指南

本仓库提供了 OpenAI API 的官方 OpenAPI 规范文件，适用于需要生成客户端代码、进行接口文档集成或自动化测试的中国开发者。

环境准备

在使用本规范前，请确保满足以下基础要求：

• 操作系统：Windows / macOS / Linux 均可
• 前置依赖：
  • git：用于克隆仓库或拉取最新规范
  • curl 或浏览器：用于直接下载 YAML 文件
  • （可选）代码生成工具：如 openapi-generator、swagger-codegen 或语言特定的 SDK 生成库（如 Python 的 datamodel-code-generator）

注意：本仓库仅包含 API 描述文件（.yml），不包含可执行的二进制程序或 Python/Node.js 包，因此无需安装特定的运行时环境即可获取规范文件。

安装步骤

你可以通过以下两种方式获取最新的 OpenAPI 规范文件：

方式一：直接下载最新官方规范（推荐）

直接通过链接获取经过文档化处理的最新规范文件：

curl -O https://app.stainless.com/api/spec/documented/openai/openapi.documented.yml

或者在浏览器中访问该链接并保存为 openapi.documented.yml。

方式二：克隆仓库获取手动维护版本

如果你需要查看或贡献手动更新的规范版本，可以克隆整个仓库：

git clone https://github.com/openai/openai-openapi.git
cd openai-openapi
git checkout manual_spec

基本使用

获取 .yml 文件后，最常见的用法是将其输入到代码生成器中，自动生成特定语言的客户端 SDK。

示例：使用 openapi-generator 生成 Python 客户端

假设你已安装 Java 环境和 openapi-generator-cli，执行以下命令生成 Python 代码：

openapi-generator generate \
  -i openapi.documented.yml \
  -g python \
  -o ./openai-python-client

示例：在 Swagger UI 中预览接口文档

如果你本地运行了 Swagger UI，可以将下载的 openapi.documented.yml 文件路径配置到 url 参数中进行可视化浏览：

const ui = SwaggerUIBundle({
  url: "openapi.documented.yml", // 或指向该文件的在线链接
  dom_id: '#swagger-ui',
  // ...其他配置
})

生成后的代码库即可用于调用 OpenAI 的各项接口（如 Chat Completions, Images, Embeddings 等）。