01 用 JSON 调用 AI API：给 AI 寄一张任务单

这一课，我们要请 AI 帮一个小忙：用中文给小朋友解释，为什么下雨后有时能看见彩虹。

你已经知道怎么读 JSON。如果还不熟悉大括号、方括号和双引号，可以先看上一课。

先跟着示例走一遍，再决定要不要真实发送。阅读、改任务单和回答成就题，都不需要 API 密钥。

一、API 就像一个收任务的窗口

平时，你在聊天软件里打字，再点“发送”。如果你想让自己写的程序向 AI 提问，就需要一个程序能使用的窗口。这种窗口叫 API。

你可以把这次调用想成寄信：

整个过程是：

Write a JSON task
       |
       v
Send it to the AI API
       |
       v
Read the JSON response
       |
       v
Find the answer and check it

从上到下就是：写任务单 → 发送 → 读回信 → 找到并检查答案。

JSON 是任务单的格式，API 是收任务的窗口，模型才负责生成回答。

二、把问题放进 JSON

本课以 OpenAI 的 Responses API 为例。不同公司的窗口可能要求不同的字段，不能只换地址就认定能用。

如果你在 LLM 101 的 Chat 教程里见过 messages，那是另一种聊天接口的写法。本课使用的接口把输入放在 input 里。按对应接口的规则填写就好。

先写最小的一张任务单：

{
  "model": "gpt-6-astra",
  "input": "Explain in Chinese, in two short sentences for a child, why rainbows can appear after rain."
}

只有两项，逐项读：

• model：用哪个 AI 模型。这里的值是模型名称。
• input：交给 AI 的内容。英文任务的意思是：“用中文，用两句短话，给小朋友解释雨后为什么可能出现彩虹。”

input 的值也能直接写中文。这里保留英文，是为了方便你对照代码和说明。

这两个名字是接口规定的。把 input 改成自己起的 question，虽然仍可能是合法 JSON，接口却不一定接受。

模型名称取自 OpenAI 官方文本生成示例。真实调用前，请由账号持有人确认该模型可用；如果不可用，将 model 的值改为账号可用且支持 Responses API 的文本模型。

三、可选实操：把任务单发出去

你需要一台电脑、能连接接口的网络，以及有可用额度的 API 账号。准备步骤可参考 OpenAI 官方快速入门。

下面的命令适用于 macOS 或 Linux 的终端，以及 Windows 的 WSL / Git Bash。终端是一个用文字命令操作电脑的窗口。这些命令不适用于直接粘贴到 Windows PowerShell。

第一步：保存任务单

在电脑上新建一个文件夹，例如 ai-json-practice。用纯文本编辑器，在里面新建一个 request.json 文件，把上一节的任务单复制进去并保存。

确认文件使用 UTF-8 编码，名字不是 request.json.txt。不要用 Word 文档代替这个文件。

打开终端，输入 cd、一个空格，再输入这个文件夹的路径，按回车。cd 的意思是“进入这个文件夹”。路径里有空格时，用英文双引号包住整个路径。

然后输入：

curl --version

看见 curl 的版本信息，就能继续。curl 是帮我们发送请求的工具。如果提示找不到命令，请让家长或老师先帮你准备 curl。

第二步：准备通行证

由账号持有人准备 API 密钥。在同一个终端里，将下面的占位文字换成自己的密钥，再执行：

export OPENAI_API_KEY="replace-with-your-api-key"

这一步把密钥放进当前终端的一个“有名字的小盒子”，叫环境变量。后面的命令通过 OPENAI_API_KEY 这个名字取用它。关闭终端后，重新练习需要再设置。

**密钥像能花钱的通行证。**不要写进 request.json，不要发到聊天群、截图或公开代码里，也不要放进网页代码。上面的设置命令可能保存在终端历史里，请在自己的电脑上由账号持有人操作。

将来做网页时，应让服务器保管密钥并调用 AI API。这一课只在自己的电脑终端里练习。

第三步：发送一次请求

确认 request.json 已保存，并且终端仍在同一个文件夹。把下面整段一次复制进终端，按回车，等待返回：

curl https://api.openai.com/v1/responses \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --data-binary @request.json \
  --output response.json \
  --write-out '\nHTTP %{http_code}\n'

不用背命令，按“寄信”的思路读：

每行末尾的反斜杠 \ 表示“下一行还是同一条命令”。它属于终端命令，不属于 JSON。反斜杠后面不要加空格。

密钥和内容类型写在请求的“附加说明”里，叫请求头；request.json 的内容是请求体。它们一起组成请求。

四、收到回信，去哪里找答案？

如果终端显示 HTTP 200，表示这次 HTTP 请求成功。用编辑器打开同一文件夹里的 response.json。

下面是删去其他字段、只保留阅读重点的示意回信。它不是实际调用记录，你收到的内容可能不同：

{
  "id": "resp_example",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Sunlight bends and splits into colors in raindrops. A rainbow can appear when the light reaches your eyes at the right angle."
        }
      ]
    }
  ]
}

为了方便对照，示意答案用英文，意思是：“阳光在雨滴里改变方向，并分成不同颜色。光以合适的角度进入眼睛时，我们就可能看见彩虹。”真实任务要求的是中文；如果实际回复没有遵守，也要检查并改进要求。

像拆信一样，从外到里找：

1. 先看 status。completed 表示生成已完成；如果是其他状态，先检查是否中断或失败。
2. 找到 output，它是一份列表。
3. 在列表中找 type 为 message 的项目。
4. 打开它的 content 列表，找 type 为 output_text 的项目。
5. 里面的 text 才是这一段回答。若有多段文本，按顺序阅读。

别把 output 的第一项永远当作答案。里面也可能有其他类型的项目。官方的文本生成说明也提醒，要按项目类型查找；一些官方 SDK 提供了 output_text 帮助取出文字。

**收到 200，不代表 AI 的答案一定正确。**还要看生成是否完成、有没有按要求回答，以及事实是否可靠。

五、发不出去时，先看哪里？

先看终端的状态码，再打开 response.json 阅读错误说明。错误回信不一定有 output，不要在里面硬找答案。

这些状态码的含义可对照 OpenAI 官方错误说明。

六、用 JSON 发任务，就一定收到 JSON 格式的答案吗？

这里有两层，要分开看：

• 回信的外包装：API 返回 JSON，包含 status、output 等字段。
• AI 写的答案：上面 text 里的内容是普通文字。

就像信封有固定格式，信里的作文仍然可以自由写。用 JSON 发送问题，不会自动让 AI 的答案也变成一张资料清单。

如果只在问题里加一句“请返回 JSON”，模型仍可能没按要求写。正式程序需要固定字段时，可以进一步学习 Structured Outputs（结构化输出）：它用一份叫 JSON Schema 的规则，说明“答案必须有哪些格子、每格是什么类型”。程序仍需处理拒绝回答、生成中断等情况，并检查内容。

现在先记住：请求用 JSON、API 回信用 JSON、答案本身也要符合 JSON，是三个不同的要求。

七、自己换一个问题

把 request.json 里的 input 改成下面的任务。它的意思是：“用中文，用两句短话解释磁铁为什么能吸住一些金属。”

{
  "model": "gpt-6-astra",
  "input": "Explain in Chinese, in two short sentences for a child, why magnets attract some metals."
}

没有密钥时，只练习修改文件就可以。有密钥时，保存文件，再运行一次发送命令。**每次发送都可能计费，并会覆盖旧的 response.json。**想保留两次结果，先给旧回信换一个文件名。

用这四项检查自己的结果：

1. 我只改了 input 的值，保留了接口要求的字段。
2. JSON 的双引号、逗号和括号仍然正确。
3. 如果真实发送，我检查了状态码、生成状态，并找到了回复文字。
4. 我核对了答案是否是中文、是否简短、内容是否合理。

练习后可以关闭终端，并让账号持有人按需撤销练习密钥。