OpenAI Responses API 文本生成入门教程

把OpenAI Python SDK装好之后，最容易踩的坑其实不是网络或认证，而是对着旧接口文档、返回数组和提示词角色来回试。结果往往是：请求发出去了，代码却取不到正文，或者业务规则被普通输入覆盖。下面这个最小流程走完，就能让脚本通过Responses API生成文本，并稳定地用response.output_text拿到结果。 开始前需要：一个能调OpenAI API的项目、配好的API密钥、Python环境，以及当前版本的openai包。示例用的是官方文本生成页面展示的gpt-5.6；如果你的项目没有这个模型的权限，记得换成实际可用的文本模型，别只靠重复提交去碰模型权限错误。 ## 先跑通一条最小文本请求 **主要动作：** 创建text_demo.py，写入一条只包含模型和输入的Responses API请求。代码很简单： ```python from openai import OpenAI client = OpenAI() response = client.responses.create( model="gpt-5.6", input="用一句话说明为什么要给 API 请求设置超时。" ) print(response.output_text) ``` **成功标志：** 运行python text_demo.py后，终端直接打印出一段模型生成的文本，没有任何Python traceback。**失败处理：** 提示模块缺失？用同一个Python环境安装openai。认证错误？检查环境变量在当前终端是否生效。模型不可用？换一个项目能访问的模型再试。 官方页面已经把Responses API作为直接文本生成请求的推荐入口。下面这张图只看四个地方：OpenAI()创建客户端，client.responses.create发出请求，model和input提供参数，最后用output_text打印文本。少了其中任何一个，都应该先核对代码，而不是继续往上堆参数。  ## 读取文本时不要固定猜数组位置 很多人在写业务代码时，习惯用固定下标去读返回结果，比如output[0].content[0].text。这不是不行，但容易出问题——一旦响应结构发生一点变化，代码就崩了。更稳妥的做法是直接用response.output_text，这是SDK提供的聚合属性，专门用来取文本生成的最终结果。 **成功标志：** 文本请求能直接拿到聚合后的字符串，代码不依赖output数组中某一项的固定位置。**失败处理：** 如果你确实需要分析工具调用、推理信息或其他输出项目，那就逐项检查response.output的类型和内容，但不要一开始就假设文本一定在output[0].content[0].text。 下面这张图展示的是官方示例中的output数组：当前这一项是message，内部的内容类型是output_text。真实请求可能同时返回其他项目，所以这张图证明的是响应层级，并不代表所有请求都只有这一种结构。普通文本展示优先用SDK提供的聚合属性，需要解析完整响应时再遍历数组。  ## 用 instructions 固定本次请求的行为 **主要动作：** 把语气、目标和回答规则放进instructions，把本次问题保留在input。代码可以改成这样： ```python response = client.responses.create( model="gpt-5.6", instructions="回答控制在三句话内，先给结论，再给原因。", input="为什么生产环境要记录请求 ID？" ) print(response.output_text) ``` **成功标志：** 输出遵守三句话和先结论后原因的约束，同时回答了input中的问题。**失败处理：** 规则没生效？先确认instructions和input没有写反，也没有把互相冲突的要求分散在两个参数里。多轮请求时还得注意：上一轮的instructions不会自动进入下一轮。 官方说明明确指出，instructions的优先级高于普通input，并且只作用于当前响应请求。下面这张图里两个参数同时出现，正好用来核对职责是否分开：前者写应用规则，后者写这次要处理的问题。如果画面和代码对不上，先回到参数层级检查。  ## 复杂输入改用 developer 与 user 角色 当需要把应用规则和最终输入拆成多条消息时，可以把input改为角色数组。代码如下： ```python response = client.responses.create( model="gpt-5.6", input=[ { "role": "developer", "content": "回答控制在三句话内，先给结论，再给原因。" }, { "role": "user", "content": "为什么生产环境要记录请求 ID？" } ] ) print(response.output_text) ``` **成功标志：** developer消息提供的规则约束了user消息的回答，返回文本仍能通过output_text读取。**失败处理：** 角色写错或内容结构不完整？先检查每一项是否同时有role和content。业务规则被输入改变了？确认规则在developer，终端输入在user。 下面这张图把两种角色放在同一个input数组里。developer承载应用规则，优先于user；user承载最终输入；模型生成的消息用assistant角色。如果画面中的数组层级和本地代码对不上，先修正括号和字段位置。  ## 用一次可重复请求确认结果 跑完上面这些步骤，你手上应该有一个能稳定工作的脚本。验收标准很简单： - 同一个终端能读取API密钥，运行脚本时达到“能打印正文”的结果，不再出现认证错误。 - 代码调用client.responses.create，并使用项目实际可访问的文本模型。 - 普通文本通过response.output_text读取，没有依赖固定数组下标。 - 行为规则放在instructions或developer消息中，实际问题放在input或user消息中。 - 相同脚本连续运行两次都能打印文本；失败时能区分模块、认证、模型权限、网络与响应解析问题。 - 四张官方截图都能打开，并分别对应最小请求、响应结构、指令优先级和消息角色。 最小请求稳定之后，再考虑加入流式输出、结构化数据、工具调用或会话状态。每增加一种能力，就留一条独立的验收信号。这样遇到异常时，能立刻判断问题出在输入规则、返回结构，还是新加入的功能上。