Cookbook

响应接口 Responses API 示例

Q: OfApp.cn 支持 Responses API 吗？

OfApp.cn 官方文档展示了 POST /v1/responses 示例。具体可用模型、计费规则、额度、速率限制和能力边界，请以 OfApp.cn 控制台或官方文档为准。

Q: instructions 和 input 有什么区别？

instructions 放稳定的高层要求，例如身份、语气、输出格式和边界；input 放这次用户要处理的任务、材料或消息数组。两者分开更便于复用、审计和调试。

Q: output_text 取不到怎么办？

先打印完整响应对象。检查输出是否在 output 数组里、是否返回了工具调用或错误对象、SDK 是否过旧，以及兼容服务是否返回了不同字段。

Q: 多轮对话一定要用 previous_response_id 吗？

不一定。你也可以自己保存必要上下文。涉及敏感资料、成本控制或上下文裁剪时，自己管理历史往往更可控。是否使用 previous_response_id 还要看服务商支持情况。

Responses API 接入 OfApp.cn 教程，覆盖 instructions、input、output_text、curl、JavaScript、Python、stream、多轮上下文、Chat Completions 迁移、常见错误和上线检查。

预计阅读: 9 分钟
最近更新: 2026/07/03
维护方式: 人工编辑

Responses API 是 OpenAI 当前推荐新项目优先评估的统一响应接口。它把文本生成、结构化输出、工具调用、多轮上下文和多模态能力放在更统一的响应对象里，适合新项目、代理式流程和需要逐步扩展能力的应用。

本文示例基于 OfApp.cn 的 OpenAI 兼容接口写法。Base URL 使用 https://api.ofapp.cn/v1。OfApp.cn 官方文档展示了 POST /v1/responses 示例；具体可用模型、价格、额度、套餐和能力，请以 OfApp.cn 控制台或官方文档为准。

页面摘要

项目	内容
阅读时间	约 9 分钟
更新时间	2026-07-03
适合场景	新项目文本生成、Chat Completions 迁移评估、AI 工作流封装、代理式应用入门、办公自动化脚本
核心问题	什么时候应该用 Responses API，如何验证 OfApp.cn 兼容入口是否支持你的真实任务
你会完成	curl、JavaScript、Python 三种最小请求，一份任务选择矩阵，以及迁移、返回解析和上线检查清单
边界提醒	OfApp.cn 官方文档展示了 `/v1/responses` 示例；具体可用模型、价格、额度、套餐、速率限制和能力边界请以 OfApp.cn 控制台或官方文档为准

适合谁读

读者	正在处理的问题	读完能得到什么
新项目开发者	不确定该用 Responses 还是 Chat Completions	明确两者的输入、输出和迁移差异
AI 客户端或工具作者	想支持新的 OpenAI 风格端点	知道最小请求和错误边界
后端维护者	要把文本生成封装成服务端接口	建立响应解析、超时、日志和重试习惯
产品经理	想判断新接口是否值得排期	理解它适合的场景和不适合的边界
普通办公用户	想把 AI 写作、总结、分类接进流程	看懂为什么示例从 `input` 开始，而不是从复杂参数开始

调用流程图

这张图的重点是顺序。先验证 /responses 能返回，再加入流式输出、多轮上下文、结构化输出或工具调用。兼容服务的能力边界必须逐项验证。

Responses API 是什么

Responses API 可以理解为一个更统一的“让模型完成一次响应”的接口。和 Chat Completions 相比，它的请求和返回结构更像任务对象，而不是只围绕 messages 和 choices 展开。

对比项	Chat Completions	Responses API
请求入口	`/v1/chat/completions`	`/v1/responses`
主要输入	`messages`	`input`，也可以配合 `instructions`
常用读取方式	`choices[0].message.content`	`response.output_text`
返回结构	多个 `choices`	typed `output` items
多轮上下文	通常由应用自己保存 messages	可评估 `previous_response_id`、会话对象或自行管理上下文
适合场景	旧项目、兼容客户端、基础聊天	新项目、工具能力、多模态和代理式流程

OpenAI 官方迁移文档说明，Chat Completions 仍被支持；新项目可以优先评估 Responses API。放到 OpenAI 兼容服务里，还要加上一条现实判断：服务商是否支持这个端点、字段和你要调用的能力。

Responses 任务选择矩阵

Responses API 不只服务聊天界面。它更适合把一次 AI 请求当作“任务对象”来管理：输入是什么、稳定指令是什么、输出应该怎样解析、失败后如何重试。

任务	推荐输入方式	第一次验证	主要风险
文章摘要	`instructions` 固定摘要规则，`input` 放正文或片段	先用短文验证 `output_text` 是否稳定	长文超上下文、来源页码丢失、摘要过度概括
批量分类	`instructions` 固定标签口径，`input` 放单条样本	先跑 10 条脱敏样本，看标签是否一致	标签边界不清、输出格式漂移、批量失败难回放
办公自动化	`instructions` 固定角色和格式，`input` 放会议、邮件或表格摘要	先生成一份人工可复核初稿	敏感材料进入日志、人工复核环节缺失
开发辅助	`input` 放错误日志、需求或代码片段，必要时拆分上下文	先用最小日志验证解释质量	把推测当事实、泄露源码或密钥
AI 客户端功能	根据客户端能力选择字符串或消息数组	先确认客户端是否支持 `/responses`	客户端只支持 Chat Completions，不能直接迁移
服务端封装	服务端统一读取环境变量，输出给前端前做脱敏	先写一个只接收测试输入的内部接口	前端暴露 Key、异常返回过多内部信息

如果任务只是验证 Key 和 Base URL，Responses API 不是唯一选择；任何 OfApp.cn 官方文档明确支持的最小端点都可以用于连通性测试。若任务会持续扩展到结构化输出、工具调用、多模态或代理式流程，再优先评估 Responses API。

input 和 instructions 怎么写

最小文本生成只需要 model 和 input。当你需要约束语气、身份、格式或输出边界时，再加入 instructions。

字段	放什么	建议
`model`	当前账号可用模型名	不猜名称，以控制台、Models API 或官方文档为准
`instructions`	高层指令、风格、角色和输出要求	保持稳定，便于复用和版本管理
`input`	用户任务、材料或消息数组	最小验证先用字符串，迁移时再用数组
`stream`	是否流式返回事件	先非流式，确认稳定后再开启
`store`	是否保存响应，支持情况按服务商确认	涉及敏感材料时要单独评估

简单规则：instructions 写“模型应该怎样做”，input 写“这次要处理什么”。不要把长篇业务规则、用户材料和调试信息混在一个字符串里。

前置条件

把配置放进环境变量，避免在代码、截图、日志和公开仓库里暴露真实 Key。

export OPENAI_BASE_URL="https://api.ofapp.cn/v1"
export OPENAI_API_KEY="sk-xxxx"
export OPENAI_MODEL="以 OfApp.cn 控制台可用模型为准"

如果工具会自动拼接 /v1，Base URL 可能需要填写 https://api.ofapp.cn。判断标准是最终请求地址只出现一个 /v1/responses。

curl 最小请求

curl 适合确认端点、鉴权、模型名和返回结构。它能绕开 SDK 封装，直接看服务端返回什么。

curl "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "instructions": "你是一个简洁的中文助手，只回答用户问题。",
    "input": "用三点说明 Responses API 适合哪些任务。",
    "stream": false
  }'

预期结果不是固定文案，而是一个响应对象。调试时先保存完整 JSON，再看 SDK 是否能提供 output_text 这类便捷字段。

JavaScript 最小请求

JavaScript 适合 Node.js 服务端、内部工具、Web 项目的后端接口和自动化脚本。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

const response = await client.responses.create({
  model: process.env.OPENAI_MODEL,
  instructions: "你是一个简洁的中文助手，只回答用户问题。",
  input: "用三点说明 Responses API 适合哪些任务。",
  stream: false,
});

console.log(response.output_text);

不要把这段代码放进浏览器组件。API Key 应留在服务端，前端只调用你自己的后端接口。

Python 最小请求

Python 适合办公自动化、数据整理、研究脚本、批处理任务和后台服务。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
)

response = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    instructions="你是一个简洁的中文助手，只回答用户问题。",
    input="用三点说明 Responses API 适合哪些任务。",
    stream=False,
)

print(response.output_text)

生产代码里建议加入超时、有限重试、错误分层和日志脱敏。不要把用户原文、真实 Key 或完整响应无差别写入日志。

从 Chat Completions 迁移

如果旧代码没有使用工具调用、多模态或复杂函数参数，可以先把迁移拆成三步：

迁移点	旧写法	新写法
请求路径	`/v1/chat/completions`	`/v1/responses`
输入字段	`messages`	`input`
读取文本	`choices[0].message.content`	`output_text` 或解析 `output`

简单消息数组可以作为 input 传入 Responses API，用于降低迁移成本：

const context = [
  { role: "system", content: "你是一个简洁的中文技术助手。" },
  { role: "user", content: "把这段会议记录整理成行动项。" },
];

const response = await client.responses.create({
  model: process.env.OPENAI_MODEL,
  input: context,
});

console.log(response.output_text);

迁移时不要只改路径。还要检查返回结构、流式事件、结构化输出、工具调用、日志字段和错误处理。

迁移前自检清单

把旧 Chat Completions 代码迁到 Responses API 前，先用这张表判断迁移是否值得做。不能通过的项目，先保留旧接口或做小范围试点。

自检项	通过标准	不通过时的处理
服务商支持	OfApp.cn 官方文档或控制台明确支持当前账号要用的 `/v1/responses` 能力	继续用 Chat Completions，或只做内部验证
输入结构	旧 `messages` 能被清楚映射到 `input` 和 `instructions`	先整理 system、user、history 的职责
返回解析	代码能处理 `output_text`，也能在为空时检查完整 `output`	不要只替换一个字段名就上线
流式事件	客户端、网关和前端都能处理 Responses 的事件类型	保留 Chat Completions 流式作为回退
回归样例	至少有真实脱敏样例覆盖成功、失败、空输出和长输入	先补样例，再迁移生产路径
日志安全	只记录状态码、耗时、请求 ID、脱敏摘要和错误分类	删除完整 Key、用户原文和敏感文件内容

多轮上下文怎么处理

Responses API 可以用不同方式处理多轮上下文。选择哪一种，取决于服务商支持情况、隐私要求和你是否需要自己控制上下文长度。

做法	适合场景	注意事项
应用自己保存历史	需要完全控制上下文、脱敏和裁剪	旧历史要摘要，避免上下文过长
`previous_response_id`	想把前一次响应串到下一次请求	顶层 `instructions` 通常仍要重新传入
会话对象	需要持久会话管理	是否支持以服务商当前文档为准

如果你的应用处理合同、简历、医疗、客户资料或内部会议记录，建议优先自己管理上下文和日志保留策略。

流式输出怎么写

Responses API 的流式输出会返回事件。OpenAI 文档中，文本增量事件常见类型是 response.output_text.delta，其中 delta 是新增文本片段。兼容服务可能只支持部分事件类型，先用非流式请求验证，再打开 stream: true。

const stream = await client.responses.create({
  model: process.env.OPENAI_MODEL,
  input: "分三点说明流式输出适合哪些界面。",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

如果流式失败而非流式成功，优先检查代理是否缓冲响应、客户端是否支持 Server-Sent Events、超时时间是否过短，以及服务商是否支持 Responses 流式事件。

如何读取返回结构

SDK 的 output_text 是便捷字段，适合最小示例和普通文本生成。上线前仍建议理解完整响应对象。

字段	说明	排查用途
`id`	本次响应标识	关联日志和问题单
`output_text`	SDK 便捷取文本	快速展示文本结果
`output`	typed items 数组	检查消息、工具调用、结构化输出
`status`	响应状态，是否存在取决于返回结构	判断是否完成、失败或仍在运行
`usage`	token 用量，是否返回取决于服务	成本观察和异常排查

如果 output_text 为空，不要马上认定模型没有回答。先打印完整响应，确认是否返回了工具调用、拒答、安全过滤、错误对象或不同字段名。

上线前建议按这个顺序解析：

顺序	读取动作	目的
1	判断 HTTP 状态码和 SDK 异常	先区分请求失败和模型正常返回
2	读取 `output_text`	处理普通文本生成和最小示例
3	检查 `output` 数组	处理 typed items、工具调用和结构化输出
4	保存脱敏摘要	支持复现，但不泄露 Key、用户原文和敏感文件
5	给前端返回稳定错误码	避免把供应商原始错误完整暴露给用户

常见错误速查

现象	可能原因	建议处理
401 Unauthorized	Key 缺失、拼错或请求头错误	检查 `Authorization: Bearer ...` 和环境变量
404 Not Found	`/responses` 路径不存在或 Base URL 拼错	确认最终地址是 `/v1/responses`
model not found	模型名不可用或账号没有权限	使用 OfApp.cn 控制台或官方文档中的可用模型名
`output_text` 为空	返回结构不同、输出在 `output` 中、或触发工具事件	打印完整响应再解析
参数不支持	兼容服务未实现对应字段	删除非必要参数，从最小请求重测
流式事件缺失	SDK、代理或服务端不支持 Responses streaming	先用非流式，必要时改用 Chat Completions 流式
上下文过长	input 或历史内容太多	摘要旧内容，只保留当前任务需要的信息
本地成功，线上失败	线上环境变量、网络出口或运行时不同	对比线上 Base URL、Key 来源、SDK 版本和日志

什么时候继续用 Chat Completions

Responses API 值得新项目评估，但不是每个场景都要立刻迁移。

场景	建议	原因
老项目已经稳定运行	暂时保留 Chat Completions	迁移会影响返回解析、日志和测试
AI 客户端只支持 messages	继续用 Chat Completions	客户端协议约束比接口偏好更重要
只想排查 Key 和 Base URL	任选服务商明确支持的最小端点	目标是确认通路，不是比较接口
需要新式工具能力或多模态流程	评估 Responses API	更贴近统一响应对象和事件流

OfApp.cn 文档同时展示了 /v1/responses 和 /v1/chat/completions。实际项目应按工具要求、服务商支持情况和当前账号能力选择。

上线前检查清单

检查项	通过标准
Key 管理	Key 只存在服务端环境变量或安全密钥系统中
Base URL	最终请求地址只出现一个 `/v1`
模型名	来自控制台、官方文档或 Models API 返回结果
最小请求	curl、JavaScript 或 Python 至少一种能稳定返回
返回解析	`output_text` 和完整 `output` 都有兜底处理
错误处理	401、404、429、5xx、超时和上下文过长都有明确提示
流式输出	能处理中断、空事件、重连和超时
日志脱敏	不记录完整 Key、敏感用户材料和未脱敏文件内容
迁移测试	Chat Completions 旧路径和 Responses 新路径分别有回归用例

常见问题

Responses API 一定比 Chat Completions 更好吗？

不一定。OpenAI 推荐新项目评估 Responses API，但旧项目、兼容客户端和简单聊天场景仍可能继续使用 Chat Completions。真正的判断标准是服务商支持、项目代码结构和你要用的能力。

OfApp.cn 支持 Responses API 吗？

OfApp.cn 官方文档展示了 POST /v1/responses 示例。具体可用模型、计费规则、额度、速率限制和能力边界，请以 OfApp.cn 控制台或官方文档为准。

`instructions` 和 `input` 有什么区别？

instructions 放稳定的高层要求，例如身份、语气、输出格式和边界；input 放这次用户要处理的任务、材料或消息数组。两者分开更便于复用、审计和调试。

`output_text` 取不到怎么办？

先打印完整响应对象。检查输出是否在 output 数组里、是否返回了工具调用或错误对象、SDK 是否过旧，以及兼容服务是否返回了不同字段。

可以把 Chat Completions 的 messages 直接放进 Responses 吗？

简单消息数组可以作为迁移起点，但复杂工具调用、结构化输出、多模态输入和流式事件不能只靠字段替换完成。迁移前要用真实业务样例回归。

多轮对话一定要用 `previous_response_id` 吗？

不一定。你也可以自己保存必要上下文。涉及敏感资料、成本控制或上下文裁剪时，自己管理历史往往更可控。是否使用 previous_response_id 还要看服务商支持情况。

流式输出应该先接 Responses 还是 Chat Completions？

先用服务商明确支持且你的客户端最容易处理的流式端点。若 Responses 流式事件支持不完整，可以先用 Chat Completions 流式验证界面，再回到 Responses 做能力评估。

生产环境可以直接记录完整响应吗？

不建议。响应里可能包含用户材料、工具结果、文件摘要或业务数据。建议记录 request id、状态码、耗时和脱敏后的错误摘要，敏感内容按权限和保留周期管理。

OpenAI 兼容 API 快速调用：从 Base URL、Key、模型名和最小请求开始。
聊天补全 Chat Completions 示例：理解 messages、choices 和旧项目迁移边界。
curl 示例：用终端排查路径、请求头和状态码。
JavaScript SDK 示例：在 Node.js 服务端接入兼容接口。
Python SDK 示例：把 Responses 放进脚本和后台任务。
OpenAI API 流式输出示例：处理流式输出、中断和前端展示。
错误重试示例：为 429、5xx 和超时建立重试策略。
Base URL 配置：避免 /v1 重复或缺失。
快速排错：按状态码定位接入问题。
404 Not Found：排查端点不存在。
context length exceeded：压缩长输入和历史上下文。

资料来源

OfApp.cn OpenAI API 直转文档：用于核对 OfApp.cn 公开的 Base URL、Bearer 鉴权、/v1/responses 和 /v1/chat/completions 示例。
OfApp.cn 首页：用于理解 OfApp.cn 作为统一 API 入口的品牌和产品入口。
OfApp.cn 天才游乐场：用于确认 OfApp.cn 面向体验和模型试用的公开入口。
OpenAI 文本生成指南：用于核对 Responses API 在文本生成场景中的基础写法。
OpenAI Responses API 参考：用于核对 Responses API 的端点、字段和返回对象。
OpenAI 迁移到 Responses API 指南：用于整理 Chat Completions 迁移到 Responses API 的判断路径。

带走什么

Responses API 适合新项目、统一响应对象和后续扩展能力。接入 OfApp.cn 时，先用 /v1/responses 跑通最小 input 请求，再加入 instructions、流式输出、多轮上下文和生产级错误处理。任何模型、价格、额度、能力和兼容边界，都以 OfApp.cn 控制台或官方文档为准。