TRAE-AI编程
OpenAI API 参考概览
使用本参考文档可以查阅 OpenAI API 的端点、请求和响应模式、流式事件、客户端库方法，以及身份验证、错误、速率限制和请求 ID 等通用行为。
从这里开始
- 选择适合应用的 API：
- Responses：适用于直接模型请求、工具使用、音频、图像和文本输入，以及有状态交互。
- Realtime API：通过 WebRTC、WebSocket 或 SIP 建立低延迟语音或音频会话。构建会话时，需要结合客户端事件和服务端事件参考。
- Administration：适用于用户、邀请、项目、API 密钥和审计日志等组织管理工作流。
- 创建凭证。应用请求使用标准 API 密钥，Administration 端点使用 Admin API 密钥，也可以通过工作负载身份联邦获取短期访问令牌。
- 从客户端库页面安装官方客户端库，或在任何支持 HTTP 请求的环境中直接调用 HTTP API。
- 通过开发者快速开始发出第一个请求，或直接查看创建 Responses 的参考文档。
- 投入生产环境前，查看错误代码、速率限制，并了解下文的请求 ID 日志记录方式。
身份验证
OpenAI API 接受以 API 密钥作为 Bearer 凭证，也接受通过工作负载身份联邦创建的短期访问令牌。
API 密钥属于秘密信息。 不要与他人分享，也不要在浏览器、应用等客户端代码中暴露。应在服务器端从环境变量或密钥管理服务加载 API 密钥。
撤销 API 密钥会在几秒内生效。大多数影响 API 密钥身份验证结果的更新会在 15 分钟内传播完成，但也可能需要更长时间。
通过 HTTP Bearer 身份验证提供 API 凭证：
来源示例 1（bash）：
中文译释：
这是HTTP请求头格式，不是可独立执行的Shell命令。Authorization与Bearer保留协议原名；OPENAI_API_KEY_OR_ACCESS_TOKEN表示API密钥或适用访问令牌的占位内容，发送请求前需替换为实际凭证。
Authorization: Bearer OPENAI_API_KEY_OR_ACCESS_TOKEN如果你属于多个组织，或通过旧版用户 API 密钥访问项目，可以传入请求头，指定本次 API 请求使用的组织和项目：
来源示例 2（bash）：
## [中文] 通过Bearer凭证请求模型列表，并显式指定组织与项目；变量值需由服务器安全配置提供。
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。
请求头
为了在不同 API 路径和 HTTP 版本下保持可靠行为，请将 API 请求头的总大小控制在 64 KiB 以下。这个预算包含所有请求头的名称和值，既包括 Authorization、Content-Type、User-Agent 等常用头，也包括自定义头。
为了给必需请求头和中间设备添加的请求头留出空间，任何单个自定义请求头的值，以及全部自定义请求头值的总大小，都应保持在 60 KiB 或以下。请求头过大的请求可能在到达 API 之前就失败，因此你可能收不到响应，也收不到 x-request-id。
请求调试
错误代码说明 API 响应返回的失败类型。可以检查 HTTP 响应头，了解请求的唯一 ID 和速率限制详情。常见响应头如下。
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：词元数量限制的重置时间信息。x-ratelimit-limit-project-tokens：项目词元数量限制。x-ratelimit-remaining-project-tokens：项目剩余词元数量。x-ratelimit-reset-project-tokens：项目词元数量限制的重置时间信息。
适用项目级词元限制时，响应中可能出现项目词元相关请求头。
OpenAI 建议在生产部署中记录请求 ID，以便需要时与支持团队更高效地排查问题。官方客户端库会在顶层响应对象中提供一个属性，用来获取 x-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，帮助查询 OpenAI 是否收到该请求以及接收时间。
示例：
来源示例 3（bash）：
## [中文] 展示X-Client-Request-Id请求头的显式设置；来源片段未包含完整创建请求体，仅供说明请求标识。
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 用户提供稳定性。这包括：
不同模型快照之间，提示词的实际行为可能发生变化。 模型输出本身具有变化性，因此应预期快照之间的提示词效果和模型行为存在差异。要尽可能保持一致的提示词行为和模型输出，最佳方式是固定模型版本，并为应用运行评估。
以下 API 变更属于向后兼容的变更：
- 在 REST API 和客户端库中增加新资源，即新的 URL。
- 增加新的可选 API 参数。
- 在 JSON 响应对象或事件数据中增加新属性。
- 改变 JSON 响应对象中属性的顺序。
- 改变资源标识符等不透明字符串的长度或格式。
- 在流式 API 中增加新的事件类型。
向后兼容变更以及少数破坏性变更的记录，见更新日志。
更多建议：