OpenAI Chat Completions API：功能与使用指南

构建基于人工智能的应用，不只是让模型生成回复。你还需要可靠地管理对话、引导回复，并将所有环节连接到应用中。OpenAI Chat Completions API 让这一切成为可能，它使开发者能够控制 AI 如何处理消息并生成答案。如果你想了解它的工作原理，以及如何将其用于自己的项目，本文将带你全面了解所需知识。

OpenAI Chat Completions API 让开发者能够将 OpenAI 的语言模型集成到应用和服务中。它根据一系列消息生成回复，支持对话、问答、内容生成和文本分析等任务。

Chat Completions 仍受支持。对于新项目，OpenAI 推荐使用 Responses API。本指南将聚焦 Chat Completions，介绍其消息格式、请求参数以及如何搭配兼容的 SDK 使用。

与接受文本提示词的旧版 Completions 端点（/v1/completions）不同，Chat Completions 接受结构化的消息列表。每条消息都有一个角色，例如 developer、user 或 assistant，帮助模型理解指令和对话上下文。支持的角色和内容类型取决于所选模型。

开发者可以使用 API 构建多种基于人工智能的功能，包括：

• 对话应用：创建能够回复用户消息的 AI 聊天机器人、虚拟助手和客户支持系统。

• 内容生成：生成文章、产品描述、电子邮件、摘要及其他书面内容。

• 文本分析：对文本进行分类、提取信息、分析情感，并识别文档中的要点。

• 编程辅助：生成代码片段、解释编程概念，并帮助开发者排查错误。

• 语言处理：对不同语言的文本进行翻译、改写、简化和校对。

该 API 提供了一种灵活的方式，可将语言模型与现有软件连接起来，让开发者无需自行构建和托管语言模型，即可将 AI 生成的回复整合到应用中。

Chat Completions API 采用请求—响应工作流。应用会向 API 端点发送请求，其中包含模型标识符和消息列表。所选模型处理输入后，返回生成的回复。

基本工作流包括以下步骤：

1. 准备对话：应用收集用户输入，并将其组织为消息列表。还可以加入此前的对话消息，以提供上下文。

2. 发送 API 请求：应用将所选模型和消息列表通过 POST 请求发送至 https://api.openai.com/v1/chat/completions。请求使用 Authorization: Bearer <API_KEY> 请求头。Python SDK 的 client.chat.completions.create() 方法会处理这一请求结构和身份验证。

3. 处理输入：模型理解消息内容，考虑其角色和内容，并根据提供的上下文和参数生成回复。

4. 接收响应：非流式请求会返回一个 JSON 响应，其中包含生成的补全结果和元数据。启用流式传输后，API 会发送一系列服务器发送事件（SSE），应用会在事件到达时进行处理。

5. 显示或处理输出：应用提取生成的消息，将其显示给用户，或传递给应用中的其他组件。

该工作流基于 OpenAI Chat Completions API 的请求和响应模型。

要有效使用 Chat Completions API，开发者需要了解其主要请求参数，以及这些参数如何影响模型行为。

model 参数用于指定处理请求的语言模型。不同模型提供的能力、响应速度、推理性能和定价可能不同。

开发者应根据任务复杂度、预期回复质量、延迟要求和预算选择模型。

messages 参数包含一个对话消息数组。每条消息通常包含 role 和 content 字段。

常见角色包括：

请选择你的模型支持的指令角色；对于相同的指令，无需同时发送 system 和 developer 消息。要在多轮对话中保持上下文，请在每次请求中包含相关的对话历史记录。兼容提供商可能支持不同的角色，因此调整集成方案时，请遵循其各自的模型文档。

对于支持该参数的模型和配置，temperature 用于控制采样的随机性。API 参考文档规定其取值范围为 0 到 2，默认值为 1。设置自定义值前，请确认所选模型是否支持该参数。

• 较低的温度：生成的回复更聚焦、更可预测，适用于分类、信息提取和结构化任务。

• 较高的温度：让生成的文本更具变化性，可用于头脑风暴和创意写作。

某些推理配置不接受自定义的 temperature 或 top_p 值。对于这些配置，请省略这些采样参数，改用推理强度和输出限制等受支持的控制项。

在支持该参数的情况下，top_p 通过核采样控制 token 的选择。它设定了用于选择候选 token 的累积概率阈值。

例如，值为 0.1 表示模型会考虑累积概率最高 10% 范围内的 token。较低的值通常会生成更聚焦的输出，较高的值则允许更多变化。

OpenAI 建议调整 temperature 或 top_p 其中之一，而不要同时修改两者。

max_completion_tokens 参数设定模型在一次响应中最多可生成的 token 数量，包括适用时的推理 token。

设置合适的上限有助于开发者控制输出长度并管理 token 消耗。如果模型在完成响应前达到该限制，补全结果可能会以 length 完成原因结束。

stream 参数决定 API 是一次性返回生成的响应，还是在生成过程中逐步返回。

• false：生成完成后返回完整响应。

• true：通过服务器发送事件（SSE）将响应数据流式传输给应用程序。

流式传输适用于聊天界面，以及用户希望逐步看到响应出现、而非等待整个输出完成的应用程序。

response_format 参数可在支持的模型上选择输出格式。默认格式为文本。将 type 设置为 json_object 可启用 JSON 模式，该模式会生成有效的 JSON，但不强制特定的 schema。请在消息中加入要求返回 JSON 的指令。

如需获得可预测的字段和数据类型，请在兼容模型上使用基于 JSON Schema 的结构化输出，并设置 type: "json_schema" 和 strict: true。严格模式下只能使用 JSON Schema 中受支持的子集。处理结果前，请检查是否发生拒绝响应或响应被截断。配置详情请参阅结构化输出指南。

当模型通过 Chat Completions 支持工具调用时，tool_choice 参数可控制工具选择。是否支持取决于模型及其推理配置；部分较新的模型需要使用 Responses API 才能使用工具。请在请求中添加工具前确认这些要求。

常用设置包括：

• none：阻止模型调用工具。

• auto：允许模型自行决定是否调用可用工具。

• required：要求模型调用一个或多个工具。

此功能支持函数调用，使应用程序能够将模型生成的决策与外部函数、数据库和服务连接起来。应用程序负责执行所请求的函数，并将结果返回给模型。

参数定义和模型兼容性要求请参阅 Chat Completions API 参考文档。以下 Python 示例使用不含工具的基础文本请求。

开发者可以通过 HTTP 请求或官方 SDK 使用 Chat Completions API。以下示例使用 Python 发送对话请求并获取生成的响应。

第 1 步：获取 API 密钥

在 OpenAI API 平台创建 API 密钥，并确保你的账户有权访问所选模型，且拥有足够的 API 额度或计费容量。请将密钥存储在环境变量中，而非应用程序源代码中。在 macOS 或 Linux 上，运行：

将 YOUR_API_KEY 替换为你自己的密钥。在 Windows 上，请在 shell 或系统环境中设置相同的 OPENAI_API_KEY 变量。

第 2 步：安装 OpenAI Python SDK

使用 pip 安装官方 Python 库：

第 3 步：初始化 API 客户端

导入 SDK 并初始化客户端。OpenAI() 会自动读取在第 1 步中设置的 OPENAI_API_KEY 环境变量。

第 4 步：发送聊天补全请求

使用模型和消息列表调用 client.chat.completions.create()。本示例使用 gpt-6-astra，设置较低的推理强度，并将生成总量限制为 4,096 个 token。如果你的账户无法使用该模型，请选择支持 Chat Completions 的模型，并根据其文档调整参数。

在本示例中：

• model 用于指定生成响应的语言模型。

• messages 提供指令和用户输入。

• reasoning_effort 用于为支持该参数的模型设置推理强度。

• max_completion_tokens 用于限制生成的 token 数量，包括推理 token。它不保证可见文本达到特定长度。

• response.choices[0].message.content 用于提取助手的响应。

处理 API 响应

对于此非流式请求，API 会返回包含补全结果和请求元数据的 JSON。Python SDK 会将其解析为 ChatCompletion 对象，因此示例通过 response.choices[0].message.content 等属性访问字段。

重要的响应字段包括：

finish_reason 字段可帮助开发者了解生成是如何结束的。常见值包括 stop、length 和 tool_calls。

开发者还可以检查 usage 字段来监控输入和输出 token 消耗，这有助于估算 API 成本并优化应用使用情况。

此示例展示了基本的文本响应。添加流式传输、结构化输出或工具时，请同时更新请求和响应处理逻辑，以匹配所选模型和端点。

对于探索 OpenAI Chat Completions API 替代方案的开发者，Kimi API 可通过兼容 OpenAI API 的格式访问月之暗面的大语言模型。

Kimi 提供 Chat Completions、Responses 和 Messages 接口。以下示例使用其兼容 OpenAI API 的 Chat Completions 端点，因此你可以复用上文介绍的 SDK 工作流程。配置 Kimi API 密钥，设置 Kimi 基础 URL，并选择支持的模型。有关模型参数、消息角色和工具支持，请参考 Kimi 自己的文档。

第 1 步：获取 Kimi API 密钥

在 Kimi API 平台注册，并在开发者控制台中创建 API 密钥。首次发起请求前，请检查余额、模型访问权限和账户速率限制。

请将 Kimi 密钥存储在单独的环境变量中。在 macOS 或 Linux 上，运行：

将 YOUR_KIMI_API_KEY 替换为你自己的 Kimi 密钥。在 Windows 上，请在环境中设置相同的 KIMI_API_KEY 变量。

第 2 步：安装 OpenAI Python SDK

如果尚未安装 SDK，请运行：

第 3 步：配置 Kimi API 客户端

使用 Kimi 基础 URL 和第 1 步设置的 KIMI_API_KEY 变量，创建一个单独的 kimi_client。通过 os.environ 读取密钥，可让缺失的环境变量立即以错误形式显现。

第 4 步：发送 Chat Completions 请求

使用 Kimi 客户端调用相同的 SDK 方法。此请求选择 kimi-k3，使用 Kimi 支持的 system 角色来提供指令，并返回非流式文本响应。

• 适用于不同工作负载的模型选项：Kimi K3.1 Pro 支持复杂推理、长程编程和知识型工作。其高速版在保持相同模型能力的同时提供更快的输出。上例使用 Kimi K3；请查看当前模型列表以了解可用性和迁移指南。

• OpenAI API 兼容性：熟悉 OpenAI Chat Completions 格式的开发者，在集成 Kimi 模型时可以复用相似的请求结构和受支持的 SDK 工作流程。

• 多轮对话：开发者可提供消息历史记录，以支持具备上下文感知能力的对话、虚拟助手和交互式应用。

• 流式传输和函数调用：API 支持流式响应和工具调用工作流程，使开发者能够构建更具交互性的应用，并将模型连接到外部函数。

• 多模态输入：支持的 Kimi 模型可根据自身能力处理不同类型的输入，包括文本、图像和视频。

使用 Chat Completions API 时，开发者可能会遇到与身份验证、API 配置、模型可用性或请求限制相关的错误。了解这些常见问题，有助于你定位问题并顺利运行集成：

• API 密钥无效或缺失：当 API 密钥不正确、已过期、已被撤销或配置不当时，可能会出现 HTTP 401 等身份验证错误。请检查密钥是否有效、环境变量是否正确加载，以及请求是否包含适当的身份验证凭据。

• API 基础 URL 不正确：发送到错误端点的请求可能返回 404 等错误或连接失败。请确认基础 URL 与 API 提供商文档一致，并且请求使用正确的端点路径。在 OpenAI 与兼容提供商之间切换时，记得相应更新基础 URL。

• 模型 ID 无效或不可用：如果指定的模型名称不正确、你的账户无法使用该模型，或所选端点不支持该模型，请求可能会失败。请查看提供商的模型文档，并确认模型 ID 与你的 API 账户可用的模型一致。

• 超出上下文长度：如果合并后的输入消息和生成输出超过模型的上下文窗口，API 可能会拒绝请求。请缩短输入、移除不必要的对话历史记录，或先总结较早的消息，再重新发送请求。

• 输出被截断：如果响应达到 max_completion_tokens 限制，可能会在完成所请求内容前停止。在支持的情况下提高 token 限制，或将长篇生成任务拆分为较小的请求。你还可以检查 choices[].finish_reason，确认响应是否因 length 限制而结束。

• 超出速率限制或配额：对于 OpenAI，HTTP 429 可能表示请求或 token 速率限制、消费限额或其他使用限制。重试前请检查错误类型和代码。对于临时速率限制，请降低请求频率，并在提供时遵循 Retry-After，或使用指数退避。

如果错误表明额度已用尽，或存在账单或消费限额，请检查账户余额和账单设置；反复重试不会恢复访问权限。使用 Kimi 或其他兼容提供商时，请遵循该提供商的错误代码文档，因为状态代码和配额规则可能不同。

为更高效地调试，请在更改请求参数前检查 API 返回的 HTTP 状态代码和错误消息。这些信息有助于区分身份验证问题、配置错误和使用限制。

Chat Completions API 可支持广泛的应用场景。其结构化消息格式和可自定义的生成参数，使其既适用于简单的文本功能，也适用于更复杂的 AI 工作流程。

• AI 聊天机器人和虚拟助手：开发者可使用 API 为网站、移动应用和客户服务平台构建对话助手。通过将之前的消息传入后续请求，应用可以保留对话上下文并提供更相关的回复。

• 内容创作和文本编辑：API 可根据用户指令生成和转换文本。应用可将其用于起草博客文章、撰写营销文案、总结长内容、改写段落，以及针对不同受众和用途调整写作风格。

• 文本分类和信息提取：企业可将 API 集成到处理大量文本的工作流程中。例如，它可以对客户反馈进行分类、识别情感、从消息中提取重要信息，并将非结构化内容整理到预定义类别中。

• 编程助手： API 可通过生成代码、解释编程概念、提供解决方案建议以及帮助开发者识别错误，为软件开发工具提供支持。应用程序还可以通过函数调用将模型连接到外部开发工具。

• 基于人工智能的业务工作流： 开发者可以将 API 集成到业务应用中，自动处理重复性的语言相关任务。例如处理客户咨询、生成报告、从文档中提取信息，以及根据预设指令准备回复。

OpenAI Chat Completions API 为开发者提供了一种实用途径，可将对话式 AI 引入应用程序，打造更实用的用户体验。选择合适的模型、理解其参数并谨慎处理 API 响应，都会切实影响应用程序的表现。不过，开发者在构建基于人工智能的解决方案时，并不必依赖单一服务提供商。如果你想探索另一种选择，不妨体验 Kimi API，看看其兼容 OpenAI API 的配置是否符合你的开发需求。