Skip to content

第 02 章 API 请求与响应 ​

Cherry Studio 实操演练课程 · 第一层 接入大模型
完整样章 0.1 · 2026 年 10 月 14 日

你在 Cherry Studio 里输入一句话,按下发送,过一会儿便看到了回答。这个过程很容易让人产生一种感觉:大模型就装在聊天窗口里面。

如果你使用的是远程模型,实际发生的事情通常是:Cherry Studio 把你的输入整理成服务商规定的格式,发送到模型服务,收到结果后,再把它显示在窗口里。

两个程序怎样约定“发什么、发到哪里、怎样返回”?这就涉及本章的主角:API。

读完这一章,你应该能够看懂一次简化的模型请求,解释 API 地址、API Key 和模型名称各自的作用,并分清“请求被接收”“回答生成完毕”和“回答正确”这几件事。

本章先理解调用过程,第 03 章再实际配置模型服务。两个主实验都能使用文内材料完成,不需要提前购买服务或准备密钥。章内地址、密钥、模型标识和返回记录均为教学示例,不是可用账号或真实调用记录;不要将它们填入软件作为实际配置。

2.1 API 是两个程序约定好的调用方式 ​

从同一条消息看两个界面 ​

假设你正在筹备一次社区活动,需要确认场地安排。你给 AI 的问题是:

请根据这段活动说明,告诉我活动地点和场地容量。

在你这一侧,交互对象是一个聊天窗口。你只需要输入文字、添加材料、点击发送。

在模型服务这一侧,它需要收到更具体的信息:这是谁发来的请求,要使用哪个模型,消息是什么,还带了哪些设置。

Cherry Studio 在中间做了一次转换:把便于人操作的界面输入,组织成便于程序处理的请求。

一次提问怎样完成 API 往返
一次提问的 API 请求与响应 你输入问题和材料,Cherry Studio 组织请求,经 API 发送给模型服务。服务校验请求并生成结果,再将响应返回 Cherry Studio,供你阅读和核对。 01 你输入问题 提出这一次的任务 附上需要参考的材料 02 客户端组织请求 Cherry Studio 整理输入 按接口约定携带调用信息 03 模型服务处理 校验身份、格式与权限 通过后安排模型生成 04 客户端展示响应 收到生成结果或错误 你阅读并核对内容 输入 API 请求 响应 从问题到回答 请求与响应,各有约定
沿着连线看输入、请求、处理和响应。动画只表示先后关系,不代表实际耗时;收到回答后仍需核对内容。查看原图 →

API 是 Application Programming Interface 的缩写,中文通常叫“应用程序编程接口”。可以把它理解为:一个程序向另一个程序开放的调用方式,以及使用这种调用方式必须遵守的约定。API 概念参考

这份约定通常会说明:

  • 可以请求什么操作。
  • 请求应发往哪里。
  • 需要提供什么身份凭据。
  • 输入应使用什么结构。
  • 正常结果和错误怎样返回。

API 不只属于 AI ​

天气程序可以调用气象服务的 API 查询天气;地图程序可以调用路线服务的 API 规划行程。大模型 API 则把文本生成、图片理解、嵌入计算等能力开放给其他程序使用。

API 本身不是模型,也不是聊天界面。一份 API 文档描述的是调用约定,真正提供服务的程序仍需要运行起来,处理收到的请求。

我们本章讨论的是常见的、通过 HTTP 通信的模型 API。API 这个概念更广,也可以用于同一台电脑上不同程序或软件模块之间的交互。

为什么已经有网页,还需要 API ​

网页聊天界面主要方便人直接使用。API 主要方便其他程序把模型能力接入自己的流程。

有了 API,Cherry Studio 可以把多个模型服务放在同一个界面里;一个业务程序也可以把“读取资料—请求模型—处理结果”连接起来,而不要求用户每次手动复制粘贴。

但能登录一个聊天网页,不自动说明你已经拥有它的 API 调用权限。网页账号、会员权益、API 凭据和调用额度怎样关联,要看具体服务的规则。

**停下来想一想:**如果你换了一个聊天客户端,但连接的仍是同一个模型服务,发生变化的主要是哪一部分?

2.2 一次请求要发往哪里 ​

通过网络发送的模型请求,常常包含一个网址。它看起来和浏览器地址相似,但用途是让程序访问某项服务。

下面是本章使用的虚构地址:

text
https://api.example.com/v1/chat/completions

把它拆开看:

部分本例中的内容表示什么
通信协议https使用 HTTPS 进行通信
服务主机api.example.com请求要到达的主机
路径/v1/chat/completions服务提供的一个具体接口路径

这里的 example.com 是示例域名,不能提供本课程的模型服务。

路径看起来像文件夹,但不意味着服务器磁盘上有同名文件。服务端程序会根据收到的路径等信息,决定由哪项处理逻辑响应。

基础地址与完整接口地址 ​

服务商可能给出一个基础地址,客户端再为某种操作拼接路径。例如:

text
基础地址     https://api.example.com/v1
操作路径     /chat/completions
完整地址     https://api.example.com/v1/chat/completions

这是一个示意,并非所有客户端都按这个规则拼接。有的设置接受基础地址,有的允许固定完整路径;有的服务根本不使用 /v1。

因此,在 Cherry Studio 里填“API 地址”时,应同时看服务商说明和该客户端的配置要求。机械地把一份教程里的完整网址粘到另一个服务里,可能造成路径重复或访问到错误接口。Cherry Studio 模型服务说明

地址之外还有请求方法 ​

HTTP 请求还会说明准备进行什么类型的操作,这叫请求方法。常见的有:

方法常见用途在本章中的理解
GET获取某项信息例如获取服务公开的模型列表,是否支持以服务文档为准
POST提交数据让服务处理例如提交一组消息,请服务生成回答

仅知道一个网址还不够。地址、方法和输入结构需要符合接口约定。 把生成接口的网址贴进浏览器地址栏,通常也不等同于客户端向它提交一次完整的生成请求。

2.3 API Key 说明谁有权调用 ​

服务收到请求后,通常需要确认调用者的身份和权限。API Key 是一种常见的凭据。

它不是模型文件,也不是提示词,不包含让模型突然变聪明的知识。它主要帮助服务识别请求所属的账号或项目,并据此判断能否访问相应资源、使用额度或记录用量。

凭据通常放在哪里 ​

本章的示例使用一种常见写法:

http
Authorization: Bearer DEMO_KEY_NOT_VALID

Authorization 是一个请求头字段,后面的内容携带凭据。这里的 DEMO_KEY_NOT_VALID 是无效占位符。

其他接口也可能使用不同字段或鉴权流程,不能假定所有服务都采用这行写法。知道“这是身份凭据”比死记某一个字段名更重要。

密钥有效为什么仍可能调用失败 ​

密钥能够通过身份检查,还需要继续满足其他条件:

  • 请求的接口和输入格式正确。
  • 账号有权使用所选模型。
  • 相关服务可用,并且没有触发服务限制。
  • 当前请求使用的参数组合受到支持。

因此,“我的密钥没有填错”不能排除其他问题。

密钥应该放在配置中 ​

在正常使用中,把凭据放进客户端的模型服务设置,由客户端在调用时携带。不要把真实密钥写进提示词、课程笔记、公开截图或分享文件。

提示词是模型处理的任务内容。你把密钥写进提示词,并不等于完成了接口要求的鉴权,反而会把凭据当成普通内容送入处理流程。

如果密钥意外公开,应到服务提供方撤销或更换,再更新客户端设置。仅删除一张公开截图,不能确保凭据已经失效。

2.4 看懂一份完整的简化请求 ​

现在把地址、凭据和任务合起来看。

本例借用一种常见的 Chat Completions 消息格式,帮助你读懂结构。字段含义参考公开接口文档;地址、凭据、模型名和内容都是教学数据,部分非关键字段已省略。不同协议不一定采用相同结构。请求字段参考

http
POST /v1/chat/completions HTTP/1.1
Host: api.example.com
Authorization: Bearer DEMO_KEY_NOT_VALID
Content-Type: application/json

{
  "model": "course-chat-model",
  "messages": [
    {
      "role": "system",
      "content": "仅依据用户给出的材料回答。材料未提供的信息,请明确说明。"
    },
    {
      "role": "user",
      "content": "活动说明:青禾社区 AI 体验日于 2026 年 11 月 21 日 10:00—12:00 在 301 室举行,场地容量 30 人。问题:活动地点和容量分别是什么?"
    }
  ],
  "stream": false
}

先不看全部细节,只分成三块。

第一块 目标与方法 ​

http
POST /v1/chat/completions HTTP/1.1
Host: api.example.com

它说明请求被提交到哪个主机的哪个接口。HTTP/1.1 在这里展示的是一种 HTTP 消息写法,实际通信也可能使用其他 HTTP 版本。

第二块 请求头 ​

http
Authorization: Bearer DEMO_KEY_NOT_VALID
Content-Type: application/json

请求头提供处理请求所需的附加信息。本例中,一项携带凭据,一项说明正文采用 JSON 格式。

JSON 是一种常见的数据表示方式。它用字段名和对应的值组织内容,让程序能够找到自己需要的信息。

例如:

json
{
  "room": "301 室",
  "capacity": 30
}

这里的 room 对应一段文字,capacity 对应一个数字。双引号、冒号、逗号和大括号都参与构成语法,不是随意添加的装饰。请求正文写成 JSON,并不意味着其中的每一项内容都符合模型接口要求,还需要满足该接口规定的字段和类型。

另外,“请求和响应采用 JSON 传输”与“要求模型把答案写成 JSON”是两件事。前面的响应可以是 JSON,其中的回答内容仍然只是一段普通中文。

第三块 请求正文 ​

正文里有三个本章需要认识的字段:

字段本例的值作用
modelcourse-chat-model指定请求使用的模型标识
messages一组带角色的消息提供任务要求、问题和材料
streamfalse本例要求使用非流式响应

messages 使用方括号,表示它是一组消息。每条消息再说明自己的 role 和 content。

本例中,system 消息提供固定要求,user 消息提供具体材料和问题。后续章节会继续解释不同角色及其在应用中的组织方式;本章先看清楚它们确实是发送给模型的输入内容。

聊天框和请求不是一一对应的一行文字 ​

你在输入框中看见的,可能只是最后一条用户消息。客户端还可能加入助手的固定要求、选入的对话历史、附件处理结果等。

这也解释了为什么同样一段新输入,在两个不同话题中可能得到不同回答:实际组织的请求不一定相同。第 07 章将专门讨论这些信息怎样进入上下文。

模型标识也需要按服务解释 ​

模型字段告诉服务你希望调用哪个模型或服务提供的别名。它不是把一个模型文件上传给服务器,也不是对底层实际模型身份的独立证明。

某些服务会维护别名或进行路由映射。想判断实际提供了什么能力,还需要看服务说明及具体调用证据,不能只凭客户端显示的名字。

2.5 看懂返回结果和错误 ​

服务处理请求后,会返回响应。对本章使用的 HTTP API 来说,可以先看三部分:状态、响应头和响应正文。HTTP 交互参考

正常返回时看哪里 ​

下面是与前面请求对应的一份教学响应:

http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "teaching-response-001",
  "model": "course-chat-model",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "活动地点是 301 室,场地容量为 30 人。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 80,
    "completion_tokens": 16,
    "total_tokens": 96
  }
}

这些数值和标识都是为阅读结构设置的,不是对前面中文材料的实际 Token 测量。

先找什么示例中的位置能帮助判断什么
HTTP 状态200 OK本次 HTTP 请求获得成功响应
模型返回的正文message.content模型具体说了什么
生成停止原因finish_reason服务为什么结束这次生成
用量统计usage服务记录了多少输入输出用量,具体口径看服务说明

在这种格式中,stop 常表示正常停止或遇到规定的停止条件;length 常表示碰到了长度限制。其他协议和接口可能使用不同字段。停止原因不评价答案的事实正确性。

200 OK 为什么不能证明答案正确 ​

假设服务仍然返回 200 OK,正文却是:

活动地点是 201 室,场地容量为 40 人。

这个答案和本次提供的材料不一致,但请求可以完成接收、处理和返回,响应结构也可以完全正确。

接口检查和事实核验解决的是两个问题。对于这次活动问答,我们至少要依次确认:

  1. 是否收到了可识别的响应。
  2. 服务是否正常完成了这次请求,而不是返回错误。
  3. 所需回答是否已经生成完毕。
  4. 地点和容量是否与材料一致。

后续做文件任务时,还要检查文件是否真正生成、能否打开、内容是否符合要求。

遇到错误先读什么 ​

常见的 HTTP 状态能帮助缩小排查范围,但还要结合服务返回的错误消息。下面是常见情况,不是所有服务统一的错误字典。

状态或现象常见含义优先检查
400 或 422请求格式、字段或参数不符合要求错误正文指出的字段、类型和组合
401身份认证失败凭据是否有效、是否发给正确服务
403服务拒绝访问账号、项目或资源权限,及服务说明
404目标资源或接口不存在地址与路径;也要阅读错误正文,不能只猜是模型名
429请求触发某种限流或服务限制该服务的具体限制说明和重试建议
500 或 503服务端处理错误或暂时不可用服务状态及错误记录
连接失败或超时,没有响应状态没有拿到完整的 HTTP 响应地址、网络连接及本次请求记录

例如,DeepSeek 的公开文档将无效凭据、余额不足、限流和服务器错误分为不同错误项。这说明不能见到一种错误就反复更换模型,更不能把所有问题都叫作“网络不好”。错误分类示例

如果没有收到响应,仍不能简单断言服务端一定没有处理请求。请求可能没有到达,也可能已经开始处理但返回过程中出现问题。先看记录和服务说明,再决定是否重试。

一点点出现的回答是怎样返回的 ​

前面的请求采用 "stream": false。另一种常见方式是把它设为 true,让服务在生成过程中分批返回结果。

在本章采用的接口格式中,流式响应可以使用 SSE,也就是服务端发送事件。简化后可能像这样:

text
HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"choices":[{"delta":{"content":"活动地点是 "},"finish_reason":null}]}

data: {"choices":[{"delta":{"content":"301 室,"},"finish_reason":null}]}

data: {"choices":[{"delta":{"content":"场地容量为 30 人。"},"finish_reason":null}]}

data: {"choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

这份教学记录省略了不影响阅读的字段。客户端接到各段内容后,把它们逐步拼到聊天窗口里。流式响应字段参考

流式返回让你可以更早看到一部分内容,但不保证整项任务更早完成。开始出现文字,也不说明最后一定能正常结束。若连接中途断开,你看到的可能只是一段不完整结果。

一条事件、一次网络传输和屏幕刷新,也不必然对应一个 Token。第 07 章再详细解释 Token,本章先避免把这几个单位混在一起。

2.6 接口兼容意味着什么 ​

Cherry Studio 可以接入多种服务,一个原因是它理解不同服务的调用格式。同样,一个服务也可能提供多种兼容格式。

兼容格式帮助客户端用已有的请求组织方式访问另一个服务,但它不表示所有行为完全相同。

以 DeepSeek 的两种公开调用格式为例,只看系统要求放在哪里,就已经能看到差异:

text
一种格式
messages 中包含 role 为 system 的消息

另一种格式
使用单独的 system 字段
messages 中放入用户等消息

这两种格式都能表达固定要求与当前消息,但字段组织、鉴权方式、返回结构和部分参数支持需要分别查阅。不能只修改网址,就假定原来的完整请求一定可用。多种格式的调用说明、兼容范围示例

尤其要区分下面三件事:

说法实际要检查的问题
客户端支持一种接口格式它会不会按相应约定组织请求和读取响应?
服务兼容一种接口格式它支持哪些字段、参数和能力,有哪些差异?
当前模型适合一个任务它在所需输入、输出和工具能力上是否满足要求?

能接收普通文本对话,不自动说明图像、工具调用或每一种高级参数都能按同样方式工作。后面的章节会按能力分别验证。

实验 E03 拆开一份请求 ​

本实验不用发送请求。我们先借助完整示例,把“我在软件里填的内容”和“程序真正准备发出的内容”对应起来。

准备一张实验页 ​

打开一个文本编辑器,新建 E03-请求阅读记录.txt;也可以直接在纸上完成。复制第 2.4 节的请求,保留一份原稿。

本例中的地址、模型名和密钥都是占位符。不要尝试用它们验证连接,更不要为了实验把自己的真实密钥填进共享记录。

第一步 把请求分成三块 ​

在原稿上标出:

  1. 目标主机、路径和请求方法。
  2. 请求头。
  3. 请求正文。

留意请求头和正文之间的空行。在这份便于阅读的 HTTP/1.1 示例中,它帮助我们看清两个区域。实际客户端会负责按所用协议编码,不需要你手工拼出完整网络报文。

第二步 把五项内容翻译成自己的话 ​

填写下表。先不要往下看参考解释。

你要找的内容示例中的位置或值用自己的话解释用途
服务主机和操作路径
调用凭据
模型标识
任务要求和材料
是否流式返回

然后回答:如果把用户问题从“地点和容量是什么”改成“活动时间是什么”,是否需要更换 API Key?

第三步 只修改一个问题 ​

复制请求,在副本里只把用户消息最后一句改成:

问题:这场活动从几点开始,到几点结束?

比较原稿和副本,记录你改了哪个字段,哪些字段保持不变。

在这份请求设计里,你希望改变的是任务内容,而不是调用身份或模型。至于实际会返回什么,仍要等服务处理;修改了输入,不等于已经获得结果。

第四步 只修改返回方式 ​

重新从原稿复制一份,把:

json
"stream": false

改成:

json
"stream": true

写下你的预测:服务会收到不同的问题吗?客户端接收结果的方式可能有什么变化?

这个修改的意图是请求分批返回,而不是自动更换模型、提高准确率或增加资料。具体服务怎样支持流式,需要看接口说明。

第五步 找出两个不同层面的错误 ​

下面两段都可能让人误以为“已经写了 JSON”。分别判断问题在哪里。

片段一

text
{
  "model": "course-chat-model",
  "messages": [],
  stream: true
}

片段二

json
{
  "model": "course-chat-model",
  "messages": "请告诉我活动地点",
  "stream": false
}

在实验页写下:哪个片段首先存在 JSON 语法问题?哪个片段虽然是合法 JSON,但不符合本章示例要求的 messages 结构?

修正时注意,本章采用的接口还要求消息列表中有可处理的消息。仅把字段名补上引号,并不能自动把一个空列表变成完整有效的生成请求。

第六步 对照 Cherry Studio 的配置入口 ​

如果电脑上已经安装 Cherry Studio,可以只查看“设置—模型服务”,不修改已有配置:

  • 哪项对应服务地址?
  • 哪项负责保存调用凭据?
  • 在哪里选择或添加模型?

当前问题和材料一般来自对话输入,而不是模型服务的密钥设置。至于客户端还会加入哪些消息和默认设置,后面的助手与上下文章节会继续说明。

未安装软件时,按前文解释完成字段对应即可。真正添加账号、配置服务和完成调用,留到第 03 章。

本实验完成标准 ​

你应当能够不看字段表,说明下面这句话:

我向某个服务的某个接口,使用一份调用凭据,请求一个指定模型,处理这组消息,并按约定方式返回结果。

交出五项对应表、两份单项修改记录和两段错误片段的解释。这里的完成指“读懂并正确改写请求示例”,不表示你已经成功接入服务。

实验 E04 从响应判断发生了什么 ​

这次我们站到接收结果的一侧。你会看到八张教学响应卡,它们来自同一个虚构活动问答场景。

判断标准仍然是:活动地点为 301 室,容量为 30 人。每张卡都只保留与问题相关的内容,并非完整网络记录。

第一步 建立自己的判断表 ​

新建 E04-响应判断记录.txt,为每张卡填写:

响应卡已经能确认的事情还不能确认的事情下一步最应该检查什么
A
B
C
D
E
F
G
H

第二步 阅读八张响应卡 ​

响应卡 A 正常返回

text
HTTP 状态:200 OK
回答:活动地点是 301 室,场地容量为 30 人。
finish_reason:stop

响应卡 B 正常返回了错误事实

text
HTTP 状态:200 OK
回答:活动地点是 201 室,场地容量为 40 人。
finish_reason:stop

响应卡 C 请求正文不符合要求

http
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "The messages field must be an array of message objects."
  }
}

响应卡 D 身份认证没有通过

http
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "message": "Authentication failed. Check the API credential."
  }
}

响应卡 E 请求触发限流

http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "message": "Too many requests. Retry later."
  }
}

这里的 Retry-After: 60 是教学例子,表示本响应建议等待 60 秒后再尝试。真实服务是否返回这个字段、采用什么限制,要读实际响应与服务说明。不要把它当成所有限流的统一处理时间。

响应卡 F 流式返回正常结束

text
HTTP 状态:200 OK
data: {"choices":[{"delta":{"content":"活动地点是 301 室,"},"finish_reason":null}]}
data: {"choices":[{"delta":{"content":"场地容量为 30 人。"},"finish_reason":null}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

响应卡 G 已收到文字 但没有正常结束记录

text
HTTP 状态:200 OK
data: {"choices":[{"delta":{"content":"活动地点是 "},"finish_reason":null}]}

客户端随后记录:连接中断。
此卡展示的是本次捕获到的全部响应,未收到后续结束事件。

响应卡 H 没有拿到 HTTP 响应

text
客户端记录:Connection timed out.
本次记录中没有收到 HTTP 状态和响应正文。

第三步 先判断问题属于哪一层 ​

先不要猜怎么修复。把每张卡归到下面一种或多种情况:

  • 没有拿到完整的网络响应。
  • 收到了响应,但服务拒绝处理请求。
  • 已开始生成,但未确认正常结束。
  • 正常结束,需要继续核验答案内容。
  • 正常结束,但答案已被材料证实有误。

“收到了错误响应”和“根本没有收到响应”是两种情况。卡 C、D、E 都已经包含服务返回的信息,这些信息正是排查线索。

第四步 为每张卡只选一个优先检查动作 ​

例如,卡 C 的错误正文已经指出 messages 的结构问题,就应先看请求字段,没必要先改写活动提示词。

卡 B 的服务调用已经正常结束,而事实与材料不同。此时应检查本次实际提供的材料、消息内容和回答依据,而不是立刻重新申请密钥。

对卡 H,不要直接写“密钥错误”。现有记录还不足以说明它已经走到身份认证那一步。

第五步 改写一句过早的结论 ​

下面四句话都需要改得更准确。请各写一个替代说法。

  1. “HTTP 200 说明 AI 回答正确。”
  2. “屏幕开始出现文字,说明这次任务已经完成。”
  3. “服务返回错误,说明肯定没联网。”
  4. “调用超时,说明服务端一定没有处理过这个请求。”

第六步 完成一次可选的真实观察 ​

如果你已经有可用的课程助手,可以在一个新话题中发送:

text
请只根据以下材料回答,不补充外部信息。

材料:青禾社区 AI 体验日于 2026 年 11 月 21 日 10:00—12:00
在 301 室举行,场地容量为 30 人。

问题:活动地点和容量分别是什么?

记录自己的实际回答,并核对两个事实。如果只能看到最终聊天内容,就将 HTTP 状态、请求正文和停止原因写为“当前界面未提供”,不要凭界面表现补填。

本实验不要求开启开发者工具,不要求拦截流量,也不需要故意输入错误密钥或制造大量请求。没有可用账号时,完成响应卡即可;实际接入将在下一章进行。

本实验完成标准 ​

交出八张卡的判断表,解释四句过早结论的问题。最重要的是能把“请求传输与处理”和“内容是否可靠”分开判断。

两个实验的参考解释 ​

建议先完成记录,再对照这里的解释。参考解释帮助检查判断依据,不要求逐字一致。

完成实验后 展开参考解释

E03 请求阅读参考 ​

内容在本例中的位置用途
目标Host 与 /v1/chat/completions指向服务主机上的具体接口
凭据Authorization 请求头让服务识别调用者并检查授权
模型正文中的 model指定服务接受的模型标识或别名
任务与材料正文中的 messages提供固定要求和当前问题
返回方式正文中的 stream请求非流式或流式返回

更改问题,一般是在消息内容中修改,不因为问题不同就自动需要更换凭据。把 stream 改成 true,意图是改变返回方式,不是增加知识或保证生成质量。

错误片段一中的 stream 没有双引号,首先不符合 JSON 对象字段名的语法要求。即使补上引号,本例的空消息列表仍不能构成完整有效的生成请求。

错误片段二本身是合法 JSON,但 messages 写成了字符串。本章示例要求它是一组消息对象。这说明“文本能被 JSON 解析”和“符合这个 API 的要求”是两次不同的检查。

E04 响应判断参考 ​

卡片可以确认什么下一步
A本例调用正常结束,两个被问到的事实与材料一致若任务还有其他要求,继续按要求检查;不要外推为模型总是正确
B本例调用正常结束,但两个事实都不符合材料检查实际输入、来源与答案,再修订内容
C已收到 HTTP 错误响应,正文指出 messages 结构问题检查该字段类型与接口约定
D已收到身份认证失败的响应核对正确服务、有效凭据和鉴权方式,不公开凭据
E服务报告限流,并给出了本例的等待建议减少请求,按本次响应和服务说明安排重试
F在本例格式下收到正常停止和流结束标记,内容与材料相符核对拼接后的完整回答及任务要求
G开始收到内容,但本次记录没有正常完成证据先保留部分结果,检查中断记录,再决定是否重试
H客户端没有拿到 HTTP 状态和正文检查地址、连接与请求记录,暂不能判定鉴权或模型输出

四句结论可以改写为:

  1. “这次请求得到了成功响应,答案仍需对照材料检查。”
  2. “服务已经开始返回内容,还需要观察是否完整结束。”
  3. “服务返回了具体错误,应先依据状态与正文缩小排查范围。”
  4. “客户端没有在限定时间内拿到响应,服务端处理到哪一步仍需进一步确认。”

自检题 ​

先尝试用自己的话回答,再点开题目查看参考解释。

01为什么输入一段中文,还要把它放进 JSON?
参考答案

中文是任务内容,JSON 是本例约定的数据组织方式。程序需要分别找到模型、消息、返回方式等字段,才能按接口要求处理请求。

还要分清:合法 JSON 只说明语法可被解析,其中的字段和类型是否符合这个 API 的要求,需要继续检查。

02API 地址、API Key 和模型名称可以互相替代吗?
参考答案

不能。地址决定请求发往哪里,凭据帮助服务检查调用者的身份与权限,模型名称指定想使用的模型标识。它们分别回答不同问题。

例如,密钥有效并不能修复错误的接口路径,地址正确也不代表账号有权使用所有模型。

03我能登录某个聊天网页,为什么客户端仍可能无法调用?
参考答案

网页使用权限与 API 调用权限不一定相同,还可能涉及独立的凭据、项目、额度或接口要求。应查看对应服务的 API 说明,不能把网页登录状态直接当成客户端的调用授权。

04HTTP 状态是 200,但活动容量答错了,应先改密钥吗?
参考答案

不应先改密钥。本例已经成功返回内容,应优先检查实际输入和答案依据,再对照材料修订错误。请求成功与事实正确是两项不同的判断。

05响应的 Content-Type 是 application/json,是否代表模型必须输出 JSON 答案?
参考答案

不代表。整个响应可以用 JSON 包装,而其中的 content 字段仍然是一段普通中文。要求模型把答案组织成 JSON,是另一个输出约束问题。

06流式响应里一次收到三个字,能否说明生成了三个 Token?
参考答案

不能。事件分段、网络传输、界面刷新和 Token 不是同一个单位。一次收到的内容可能包含不同数量的 Token,不能直接按看到的字数换算。

07两个服务都声称兼容一种接口,能否保证支持同样的参数和工具能力?
参考答案

不能。需要分别确认必填字段、参数含义、能力支持和返回结构。某些字段可能被忽略、限制或拒绝,普通文本对话可用也不能证明其他能力都可用。

08把 API Key 写进提示词,能否代替请求头中的鉴权?
参考答案

不能把两者当作同一种操作。提示词属于任务输入,请求头属于调用约定。真实凭据应该由客户端保存在相应配置中,并按服务要求携带;写入提示词既不等于完成鉴权,也可能泄露凭据。

进入下一章前 ​

现在,你应当能把一次调用说完整:我使用客户端,向某个接口发送符合约定的请求;服务检查身份和输入,调用模型处理,再返回内容或错误;客户端接收并展示,而我继续检查结果。

第 03 章将把这条链条落到 Cherry Studio 的实际配置里:选择服务、填写正确配置、添加模型,然后完成一次真实调用。到那时,设置页面里的地址、密钥和模型名,就不再只是需要照着填写的几个空格。

资料与样章说明 ​

本章的请求和响应借用公开 Chat Completions 格式讲解,采用虚构主机、无效密钥和占位模型名。响应卡为教学构造,不能作为服务可用性、模型表现或计费的实测证据。

概念和字段参考以下资料,查阅日期为 2026 年 10 月 14 日:

后续加入真实界面截图或实测记录时,应单独注明软件版本、服务、模型与观察范围。本章的示例与响应卡均为教学材料,不是实际模型调用的记录。

微信联系

李不凯的个人微信二维码,扫码添加好友

使用微信扫一扫,手机上可长按保存二维码