当前位置： 正文

OpenAI两套对话接口怎么选：新老项目避坑

2小时前 AI技术 8 0 推广

文章配图

1 ~> OpenAI API 体系与版本演进

1.1 两套核心 API 定位

OpenAI 现在开放了两代聊天交互接口，定位和使用场景其实差别挺大：

  • Chat Completions API ：传统文本聊天接口，架构简单，仅面向文本交互场景
  • Responses API ：新一代事件驱动型接口，原生支持多模态，官方推荐新项目优先使用

1.2 核心能力对比

对比维度 Chat Completions API Responses API
产品定位 对话生成场景（聊天机器人、客服问答、简单 FAQ） 多模态智能助手（文本、语音、图像、函数调用等复杂交互）
输入格式 聊天消息数组 messages:[{role, content}] 统一输入字段 input，支持文本、音频、图像、文件等多类型
输出形式 完整文本回复，支持文本流式输出 基于语义事件流输出，包含文本增量、音频增量、工具调用、完成事件等
流式能力 仅支持文本逐 token 流式返回 支持多模态细粒度流式输出，包含文本、语音、工具调用状态
多模态支持 部分模型支持图像输入，能力有限 原生全链路支持多模态，可同步输出文本与语音
交互可控性 一次请求对应一次完整回复，生成过程不可干预 支持生成中动态打断、分支跳转、工具函数调用
典型应用 简单对话机器人、文本补全、问答系统 智能办公助手、语音对话机器人、多模态应用、Agent 系统

1.3 官方选型建议

  • 新项目优先采用 Responses API ，以适配 OpenAI 平台最新特性与多模态能力
  • 存量简单文本对话项目可继续使用 Chat Completions API，具备广泛的模型兼容性

2 ~> Chat Completions API（传统聊天接口）

2.1 接口基础信息

  • 请求方法：POST
  • 接口地址：`
  • 核心能力：文本对话生成，兼容绝大多数开源与闭源大模型

2.2 请求参数详解

2.2.1 核心必填参数

参数名称 参数类型 必填 参数说明
model string 是 模型名称，如 gpt-4o-mini、gpt-4.1
messages array 是 对话历史数组，每条消息包含 role 与 content 字段

2.2.2 常用可选参数

参数名称 参数类型 默认值 参数说明
temperature number 1 采样温度，取值范围 0~2；值越高输出随机性越强，值越低输出越确定
top_p number 1 核心采样阈值，与 temperature 二选一，不可同时设置；0.1 表示仅考虑概率前 10% 的 token
stream boolean false 是否开启流式响应，开启后以增量数据形式返回
stop string / array none 停止词，最多支持 4 个，模型生成到对应字符时终止输出
max_tokens integer - 生成内容的最大 token 数；OpenAI 官方已不推荐使用，但多数模型仍兼容
max_completion_tokens integer - 生成 token 数上限，包含可见输出 token 与推理 token
presence_penalty number 0 重复惩罚，取值 - 2.0~2.0；正值降低重复概率，负值增加重复概率
frequency_penalty number 0 频率惩罚，取值 - 2.0~2.0；根据 token 出现频率惩罚，减少重复内容
n integer 1 单次请求生成的回复结果数量
seed integer - 随机种子，指定后相同参数与种子的请求将返回确定性结果
tools array - 工具调用列表，仅支持函数类型工具，用于实现 Function Calling 能力

2.2.3 消息角色（Role）定义

  • system：系统提示词，用于给模型设定角色与行为规范；新版模型推荐使用developer替代
  • developer：开发者指令，优先级高于历史消息，用于注入模型必须遵循的规则
  • user：用户输入消息，即终端用户向模型提交的提问与内容
  • assistant：助手回复消息，即模型生成的回答内容
  • tool：工具调用结果，用于将外部工具执行结果返回给模型

2.3 请求头规范

字段名称 字段值 说明
Content-Type application/json 请求体格式为 JSON
Authorization Bearer ${API_KEY} 认证方式为 Bearer Token，值为 OpenAI API 密钥

2.4 响应体结构（非流式）

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLnn5755qMJKT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-4.1-2025-04-14",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I assist you today?",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default"
}
  • 核心字段说明：
    • choices[0].message.content：模型生成的完整文本回复
    • finish_reason：生成终止原因，常见值：stop（正常结束）、length（达到 token 上限）
    • usage：token 消耗统计，用于计费与用量监控

2.5 会话上下文机制

  • OpenAI API 本身为无状态设计，不具备会话记忆能力
  • 实现多轮对话必须将完整历史对话通过messages数组全部提交给模型
  • 官方已推出记忆功能，但仅面向 C 端用户，API 调用仍需开发者自行维护上下文

3 ~> Responses API（新一代多模态接口）

3.1 接口基础信息

  • 请求方法：POST
  • 接口地址：`
  • 核心定位：事件驱动型多模态交互接口，官方主推的新一代 API 标准

3.2 核心请求参数

3.2.1 核心输入参数

参数名称 参数类型 必填 参数说明
model string 是 模型名称，如 gpt-4o-mini、gpt-4.1
input string / array 是 多模态输入，支持文本、图像、文件等多种格式；替代 Chat Completions 的messages字段

3.2.2 常用控制参数

文章配图

参数名称 参数类型 默认值 参数说明
instructions string - 系统 / 开发者指令，作用等同于 system 消息；与previous_response_id联用时不会继承历史指令
max_output_tokens integer - 生成 token 上限，替代原max_tokens，包含可见输出与推理 token
temperature number 1.0 采样温度，作用与 Chat Completions 一致
top_p number 1.0 核心采样阈值，作用与 Chat Completions 一致
stream boolean false 是否开启流式响应
max_tool_calls integer - 单次响应中内置工具的最大调用次数
tool_choice string auto 工具调用策略，可选值：auto、none、指定工具
store boolean true 是否存储该对话，用于后续会话继承
previous_response_id string null 上一条响应 ID，用于实现多轮会话上下文继承

3.2.3 高级参数

  • background：布尔值，是否后台运行模型响应，适用于长耗时任务
  • conversation：会话 ID 或会话对象，用于关联多轮对话，响应完成后自动追加内容
  • include：数组，指定额外输出数据，支持：
    • 网页搜索来源、代码解释器输出、文件搜索结果
    • 输入图片 URL、输出文本 logprobs、推理加密内容

3.3 请求头规范

与 Chat Completions API 完全一致：

字段名称 字段值 说明
Content-Type application/json 请求体格式为 JSON
Authorization Bearer ${API_KEY} Bearer Token 认证

3.4 全量响应结构（非流式）

{
  "id": "resp_67ccd2bed1ec819b14f964abc54267bb6a6b4523795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1-2025-04-14",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd2bf17f81981f3bb3cf658e6bb6a6b4523d3795b",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "In a peaceful grove beneath a silver",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 36,
    "input_tokens_details": {
      "cached_tokens": 2
    },
    "output_tokens": 22,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 58
  }
}
  • 核心提取字段：output[0].content[0].text 为模型生成的完整文本内容

3.5 流式响应与事件驱动机制

3.5.1 流式开启方式

请求体中设置 "stream": true 即可开启流式响应，响应以 Server-Sent Events（SSE）事件流形式返回

3.5.2 标准事件类型

事件类型 触发时机 携带数据
response.created 响应对象创建完成，模型开始处理前 响应基础信息
response.in_progress 模型开始生成内容 进度状态
response.output_text.delta 文本增量输出，每生成一段文本触发一次 增量文本内容delta
response.output_text.completed 单个文本输出块生成完成 完整文本块
response.output_item.added 新增输出项（如工具调用、音频等） 输出项信息
response.content_part.added 新增内容分片 内容分片信息
response.completed 整个响应生成结束 最终完整响应与用量统计

3.5.3 流式数据解析要点

  • 核心文本数据通过连续的 response.output_text.delta 事件返回，每个事件携带一段增量文本
  • 客户端需按顺序拼接所有delta字段，得到完整回复
  • 最终通过 response.completed 事件确认响应结束，并获取最终 token 用量
  • 与 DeepSeek 等模型不同，OpenAI 流式响应的结束事件同时携带完整结果

3.6 多模态能力支持

Responses API 原生支持多模态输入输出：

  • 输入侧 ：文本、图片、文件、音频
  • 输出侧 ：文本、音频、结构化数据、工具调用结果
  • 内置工具 ：网页搜索、文件搜索、代码解释器、计算机调用

4 ~> Apifox 接口测试实操流程

4.1 环境与密钥配置

4.1.1 环境变量配置

在 Apifox 环境管理中配置全局环境变量，用于密钥管理：

变量名 类型 说明
CHATGPT_APIKEY 秘密 ChatGPT 官方 API 密钥
DEEPSEEK_APIKEY 秘密 DeepSeek API 密钥
GEMINI_APIKEY 秘密 Gemini API 密钥

4.1.2 全局前置 URL 配置

  • ChatGPT 官方接口基础地址：`
  • 所有接口继承全局前置 URL，避免重复填写域名

4.2 接口创建与参数配置

  1. 新建接口，请求方法选择POST，路径填写/v1/responses
  2. 请求头配置 ：
    1. Content-Type: application/json
    2. Authorization: Bearer {{CHATGPT_APIKEY}}
  3. 请求体（Body）配置 ：
    1. 选择 JSON 格式，填写核心参数：model、input、stream等
    2. 示例：
      • { "model": "gpt-4o-mini", "input": "你好", "stream": false }

4.3 网络代理配置

OpenAI 的接口部署在境外，直连基本不通，所以得挂一层代理：

  • 代理模式：自定义代理
  • 代理服务器：127.0.0.1
  • 代理端口：7890（本地代理工具默认端口）
  • 生效范围：仅应用于发送接口请求，不影响 Apifox 服务器连接

4.4 非流式响应测试与解析

  1. 发送请求，响应状态码为200 OK表示请求成功
  2. Apifox 自动反序列化 JSON 响应体，展示结构化数据
  3. 核心数据提取路径：output[0].content[0].text，即为模型返回的文本内容
  4. 可通过usage字段查看本次请求的 token 消耗情况

4.5 流式响应测试与事件解析

  1. 请求体设置"stream": true，发送请求
  2. Apifox 控制台实时展示事件流，按时间顺序输出所有事件
  3. 解析要点：
    1. 忽略初始的创建、进度事件，聚焦response.output_text.delta事件
    2. 每个 delta 事件携带一段增量文本，按顺序拼接得到完整内容
    3. 最终通过response.completed事件确认响应结束
  4. 代码实现时，需使用 SSE 解析器逐事件处理，实现打字机效果
0

猜你喜欢

开源AI Agent工具集推荐：工具市场解析
AI技术

工具市场：开源AI Agent工具集推荐 📝 本章学习目标 ：本章聚焦工具系统，让AI Ag...
2小时前 6 0
reverse-skill：装上逆向渗透路由大脑
AI技术

文章目录 一、为什么需要「路由」而不是直接问 AI 二、整体架构：从用户任务到...
2小时前 6 0
AI编程平台：MonkeyCode接入VS Code
AI技术

前言 MonkeyCode 部署完成以后，是不是只能在那台 Linux 服务器上使用？ 不是。 ...
1天前 18 0
LLM踩坑实录：2个最容易忽略的细节
AI技术

我是工藤学编程 🦉 一个正在努力学习的小博主，期待你的关注 ，大家好 实...
1天前 12 0
AI修图不是玄学：扩散模型与提示词工程的技术拆解
AI技术

AI修图技术解析：从扩散模型到提示词工程的实战路径 引言 AI 修图的技术底座已经...
1天前 16 0
小白也能懂：AI智能体如何读代码并调用工具干活
AI技术

DeepSeek Harness 即将推出？小白看懂 AI 智能体如何读代码、调用工具并完成任务 ...
1天前 14 0
网址变React项目：Open-Lovable实测
AI技术

前言： 看到别人一个漂亮的页面想照着做一个，传统做法通常并不轻松。 先开开发...
1天前 14 0
OpenClaw加内网穿透：NAS与远程桌面实战
AI技术

前言 很多人第一次把 OpenClaw 部署起来后，会碰到一个很现实的问题： 它能聊天...
1天前 12 0
Penpot搭配Codex MCP：本地实改设计稿
AI技术

前言 设计工具正在出现一个明显转向：AI 不再只是站在画布外给建议，而是真正走...
1天前 14 0
用Few-shot提示词规范时序异常分析输出格式
AI技术

为什么零样本指令会翻车 只给一句"请详细分析这段数据，找出异常波动点"时，模型...
1天前 14 0
从入门到放弃？AI学习避坑的3个建议
AI技术

前言 我一直觉得，聊天式 AI 和真正能“替你做点事”的 Agent，中间隔着一道很明显...
2天前 16 0
Penpot MCP打通设计画布：Codex生成UI
AI技术

前言 Figma这类在线设计平台已经把UI设计、原型和团队协作放进了浏览器，但对于希...
2天前 18 0

评论0

请先
显示验证码
没有账号？注册  忘记密码？