English 跳到内容
主导航

推荐
API 仪表板
API 参考
简介

API 概览

简介

标题为“简介”的部分

此 API 参考文档描述了可用于与 OpenAI 平台交互的 RESTful、流式和实时 API。REST API 可通过 HTTP 在任何支持 HTTP 请求的环境中使用。特定语言的 SDK 列于 库页面.

身份验证

标题为“认证”的部分

OpenAI API 接受来自 API 密钥的持有者凭据，或使用以下方式创建的短期访问令牌： 工作负载身份联合。创建、管理和进一步了解你的 API Key，请访问 组织设置.

请记住，您的 API 密钥是机密信息！ 请勿将其与他人分享，也不要在任何客户端代码（浏览器、应用）中暴露它。API 密钥应在服务器上通过环境变量或密钥管理服务安全地加载。

通过以下方式提供 API 凭据 HTTP Bearer 认证.

Authorization: Bearer OPENAI_API_KEY_OR_ACCESS_TOKEN

如果您属于多个组织，或通过旧版用户 API 密钥访问项目，请传递一个标头，以指定 API 请求要使用的组织和项目：

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Organization: $ORGANIZATION_ID" \
  -H "OpenAI-Project: $PROJECT_ID"

这些 API 请求的使用量将计入所指定的组织和项目。组织 ID 可以在您的 组织设置 页面中找到。项目 ID 可以在您的 常规设置 页面中选择特定项目后找到。

调试请求

标题为“调试请求”的部分

In addition to 错误代码 从 API 响应返回，你可以检查 HTTP 响应头，其中包含特定 API 请求的唯一 ID 或应用于你的请求的速率限制信息。以下是 API 响应中返回的部分 HTTP 头信息：

API 元信息

  • openai-organization： 组织 与请求相关联
  • openai-processing-ms: 处理你的 API 请求所花费的时间
  • openai-version: 用于此请求的 REST API 版本 (当前为 2020-10-01)
  • x-request-id: 此 API 请求的唯一标识符 (用于故障排查)

速率限制信息

  • x-ratelimit-limit-requests
  • x-ratelimit-limit-tokens
  • x-ratelimit-remaining-requests
  • x-ratelimit-remaining-tokens
  • x-ratelimit-reset-requests
  • x-ratelimit-reset-tokens

OpenAI 建议在生产部署中记录请求 ID 以便更高效地与我们的 支持团队, 以备不时之需。我们的 官方 SDK 在顶级响应对象上提供一个属性，包含 x-request-id header.

使用 X-Client-Request-Id

小节标题为“使用 X-Client-Request-Id 提供你自己的请求 ID”

除了服务器生成的 x-request-id, 你可以通过 X-Client-Request-Id 请求头之外。此请求头不会自动添加；你必须在请求上显式设置它。

当您包含 X-Client-Request-Id:

  • 您控制 ID 的格式（例如 UUID 或您的内部追踪 ID），但它只能包含 ASCII 字符，且长度不得超过 512 个字符；否则，请求将失败并返回 400 错误。我们强烈建议确保此值在每个请求中都是唯一的。

  • OpenAI 会在受支持端点（包括 chat/completions、embeddings、responses 等）的内部日志中记录此值。

  • 在遇到超时或网络问题等导致您无法获取 X-Request-Id 响应头的情况下，您可以将该 X-Client-Request-Id 值分享给我们的支持团队，我们将能够查询是否收到了该请求以及接收的具体时间。

Example:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-Client-Request-Id: 123e4567-e89b-12d3-a456-426614174000"

向后兼容性

标题为“向后兼容性”的部分

OpenAI 致力于为 API 用户提供稳定性，在合理的情况下尽可能避免在主要 API 版本中引入破坏性变更。这包括：

快照之间的模型提示行为可能会发生变化为每个请求提供你自己的唯一标识符。模型输出本质上具有可变性，因此预期不同快照之间的提示词和模型行为会有所差异。例如，如果你从 gpt-4o-2024-05-13 to gpt-4o-2024-08-06, 相同的 system or user 消息在不同版本之间的功能可能会有所不同。确保提示行为和模型输出一致的最佳方法是使用锁定的模型版本，并实现 评估 for your applications.

向后兼容的 API 更改:

  • 向 REST API 和 SDK 添加新的资源 (URL)
  • 添加新的可选 API 参数
  • 向 JSON 响应对象或事件数据添加新的属性
  • 更改 JSON 响应对象中的属性顺序
  • 更改不透明字符串的长度或格式，例如资源标识符和 UUID
  • 添加新的事件类型（在流式传输或 Realtime API 中）

参阅 GitHub 上的 更新日志 以获取向后兼容的更改和罕见的破坏性更改列表。