第一次调用 OpenAI API

2.1 今天你要完成什么

API 可以理解成“程序之间的点餐窗口”。你的程序把问题提交过去，OpenAI 返回模型生成的结果。

• 知道请求、响应、模型名、输入内容分别是什么。
• 能运行一次最小 Responses API 示例。
• 能读懂常见错误：密钥错误、网络失败、输入为空。
• 能把模型回复打印出来。

2.2 核心理论

理论不是背概念，而是帮你判断项目为什么这样设计。下面这些规则会在代码里反复出现。

• 核心理论：AI 应用是一条流程，不是一个单独按钮。用户输入进入程序，程序调用模型，模型返回内容，程序再展示结果。
• 提示词理论：提示词不是越长越好，而是越清楚越好。角色、任务、格式、限制、例子，这五项最重要。
• 分工理论：模型擅长理解语言和生成表达；程序擅长保存数据、检查格式、处理错误和保护密钥。
• 输入契约：先规定用户要给什么资料。本课的输入要围绕“AI一句话解释器”，不要让用户随便输入到程序无法处理。
• 输出契约：先规定 AI 必须交出什么结果。本课重点是“API 调用、输入、输出、错误信息”，所以输出要能被人读懂，也要方便程序检查。
• 验证思维：AI 的一次好结果不等于项目可靠。至少用正常输入、边界输入、异常输入各测一次。
• 安全边界：API Key 是密码，不能写进浏览器前端，不能发截图，不能提交到公开仓库。

2.3 课堂讲解

这一课的项目是“AI一句话解释器”，重点是“API 调用、输入、输出、错误信息”。你可以把它当成一个小实验：先给它一个清楚输入，再观察代码里哪些地方用到了 Responses API。课堂里我们不会一上来就追求复杂功能，而是先把最小版本做出来。最小版本跑通以后，你再改输入、改提示词、改输出格式，变化就会看得很清楚。

这几课像是在搭一张地图。地图上有用户、程序、模型、输出和测试。你不需要一开始就记住所有 API 细节，先要知道每一站在做什么。

本课有一条很实用的学习线索：先问“用户到底给了什么”，再问“程序希望拿到什么”。比如你可以试这些输入：用一句话解释变量；用一个生活例子解释循环；函数是什么？给 10 岁学生听。这些输入故意有简单的，也有容易出问题的。正常输入能帮你确认功能；短输入、空输入、奇怪输入能帮你发现系统边界。

写代码时建议你分三轮。第一轮只跑通官方调用，不加自己的想法；第二轮把输入换成自己的例子，看看结果是否还合理；第三轮才开始改结构，比如增加字段、加错误提示、做网页交互。这个顺序有点慢，但很稳。真正浪费时间的不是慢，而是一下子改太多，最后不知道错在哪里。

如果回答不理想，先别急着怪模型。很多时候是任务没说清楚，或者输出要求太模糊。把“详细解释一下”改成“用三句话解释，并给一个生活例子”，结果通常会稳定很多。

理论部分要和代码一起看。比如“输入契约”不是一个漂亮词，它在代码里就是长度检查、必填字段、表单校验；“输出契约”也不是空话，它在代码里就是 JSON Schema、固定字段或页面渲染规则。你每写一行检查代码，都是在告诉系统：什么结果可以接受，什么结果需要退回去重新处理。

课堂里可以把同桌当成第一个用户。你把项目跑给同桌看，让对方换一个输入，观察系统会不会乱。很多问题都是别人随手一试才出现的，比如输入太短、问题太模糊、连续点击按钮、图片看不清。能处理这些小麻烦，作品就会从“我电脑上能跑”变成“别人也能用”。

最后做复盘时，不要只写“我学会了调用 API”。可以写得更具体：我学会了怎样限制输入，怎样让输出固定，怎样判断结果不可靠，怎样把报错变成用户看得懂的提示。这样的复盘有用，因为下一课你真的会再次用到它。

课堂讨论题

• 如果把“AI一句话解释器”交给低年级学生使用，哪一步最容易让他们困惑？
• 这个项目里，哪些事情适合交给模型，哪些事情应该交给普通代码？
• 如果模型给出一个看起来不错但没有依据的答案，你打算怎样提醒用户？
• 你能不能把今天的项目换一个主题，但保持同样的输入、处理、输出结构？
• 如果只能保留一个测试用例，你会保留正常输入、边界输入还是异常输入？为什么？

2.4 先看例子

先把例子看懂，再动手写代码。你不需要一次记住所有概念，先能说清楚“输入是什么、输出是什么、程序要检查什么”。

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.5",
  input: "用一句话解释什么是变量，给10岁学生听。"
});

console.log(response.output_text);

输入：用一句话解释变量。
输出：变量就像一个贴了名字的小盒子，可以暂时存放数字、文字或其他信息。

正确：把 OPENAI_API_KEY 放在后端环境变量里。
错误：把密钥直接写进 HTML、发到群里、放进公开截图。

你可以替换成这些输入

• 用一句话解释变量。
• 用一个生活例子解释循环。
• 函数是什么？给 10 岁学生听。
• 请解释 API，不要超过 60 字。
• 用一句话解释 JSON。

2.5 完整代码实现

下面同时给出 Node.js 和 Python 两套完整最小实现。先任选一种原样跑通，再改输入、改提示词、改输出格式。

Node.js 运行方式

1. 新建文件 lesson-02.mjs，把下面完整代码放进去。
2. 在终端运行：npm init -y
3. 安装依赖：npm install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：node lesson-02.mjs
6. 把最后一行的示例输入换成你自己的测试内容。

Node.js 完整代码

import OpenAI from "openai";

const client = new OpenAI();
const MODEL = process.env.OPENAI_MODEL || "gpt-5.5";

const question = process.argv.slice(2).join(" ") || "用一句话解释什么是变量，给10岁学生听。";

if (question.length > 120) {
  console.error("问题太长了，请先缩短到 120 字以内。");
  process.exit(1);
}

const response = await client.responses.create({
  model: MODEL,
  input: [
    {
      role: "system",
      content: "你是一位耐心的编程老师。回答要简单、准确，并给一个生活例子。",
    },
    {
      role: "user",
      content: question,
    },
  ],
});

console.log("你的问题：", question);
console.log("\nAI 的解释：\n");
console.log(response.output_text);

Python 运行方式

1. 新建文件 lesson-02.py，把下面完整代码放进去。
2. 建议新建虚拟环境后再安装依赖。
3. 安装依赖：pip install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：python lesson-02.py
6. 把 main 里的示例输入换成你自己的测试内容。

Python 完整代码

from openai import OpenAI
import os
import sys

client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")

question = " ".join(sys.argv[1:]) or "用一句话解释什么是变量，给10岁学生听。"

if len(question) > 120:
    raise SystemExit("问题太长了，请先缩短到 120 字以内。")

response = client.responses.create(
    model=MODEL,
    input=[
        {
            "role": "system",
            "content": "你是一位耐心的编程老师。回答要简单、准确，并给一个生活例子。",
        },
        {
            "role": "user",
            "content": question,
        },
    ],
)

print("你的问题：", question)
print("\nAI 的解释：\n")
print(response.output_text)

2.6 跟着做

1. 确认课堂环境已经配置好 API Key。
2. 复制最小代码，先不要加复杂功能。
3. 把 input 改成你自己的问题。
4. 运行后观察 response.output_text。
5. 故意输入空问题，看看程序应该怎么提醒用户。

2.7 常见错误

• 一开始就写大项目，导致错误太多不好查。
• 把模型回复当成一定正确，没有复核。
• 报错后只说“不行”，没有记录错误信息。
• 把 API Key 写在前端页面里。

2.8 课后练习

1. 做一个“一句话解释器”，可以解释变量、循环、函数。
2. 每个概念准备 1 个生活例子。
3. 记录一次错误和你的修复方法。

2.9 自测清单

• 我能指出代码里哪一行是输入吗？
• 我知道输出从哪里读取吗？
• 我能解释环境变量的作用吗？
• 我能把一个报错描述清楚吗？