第 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 是 Application Programming Interface 的缩写,中文通常叫“应用程序编程接口”。可以把它理解为:一个程序向另一个程序开放的调用方式,以及使用这种调用方式必须遵守的约定。API 概念参考
这份约定通常会说明:
- 可以请求什么操作。
- 请求应发往哪里。
- 需要提供什么身份凭据。
- 输入应使用什么结构。
- 正常结果和错误怎样返回。
API 不只属于 AI
天气程序可以调用气象服务的 API 查询天气;地图程序可以调用路线服务的 API 规划行程。大模型 API 则把文本生成、图片理解、嵌入计算等能力开放给其他程序使用。
API 本身不是模型,也不是聊天界面。一份 API 文档描述的是调用约定,真正提供服务的程序仍需要运行起来,处理收到的请求。
我们本章讨论的是常见的、通过 HTTP 通信的模型 API。API 这个概念更广,也可以用于同一台电脑上不同程序或软件模块之间的交互。
为什么已经有网页,还需要 API
网页聊天界面主要方便人直接使用。API 主要方便其他程序把模型能力接入自己的流程。
有了 API,Cherry Studio 可以把多个模型服务放在同一个界面里;一个业务程序也可以把“读取资料—请求模型—处理结果”连接起来,而不要求用户每次手动复制粘贴。
但能登录一个聊天网页,不自动说明你已经拥有它的 API 调用权限。网页账号、会员权益、API 凭据和调用额度怎样关联,要看具体服务的规则。
**停下来想一想:**如果你换了一个聊天客户端,但连接的仍是同一个模型服务,发生变化的主要是哪一部分?
2.2 一次请求要发往哪里
通过网络发送的模型请求,常常包含一个网址。它看起来和浏览器地址相似,但用途是让程序访问某项服务。
下面是本章使用的虚构地址:
https://api.example.com/v1/chat/completions把它拆开看:
| 部分 | 本例中的内容 | 表示什么 |
|---|---|---|
| 通信协议 | https | 使用 HTTPS 进行通信 |
| 服务主机 | api.example.com | 请求要到达的主机 |
| 路径 | /v1/chat/completions | 服务提供的一个具体接口路径 |
这里的 example.com 是示例域名,不能提供本课程的模型服务。
路径看起来像文件夹,但不意味着服务器磁盘上有同名文件。服务端程序会根据收到的路径等信息,决定由哪项处理逻辑响应。
基础地址与完整接口地址
服务商可能给出一个基础地址,客户端再为某种操作拼接路径。例如:
基础地址 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 是一种常见的凭据。
它不是模型文件,也不是提示词,不包含让模型突然变聪明的知识。它主要帮助服务识别请求所属的账号或项目,并据此判断能否访问相应资源、使用额度或记录用量。
凭据通常放在哪里
本章的示例使用一种常见写法:
Authorization: Bearer DEMO_KEY_NOT_VALIDAuthorization 是一个请求头字段,后面的内容携带凭据。这里的 DEMO_KEY_NOT_VALID 是无效占位符。
其他接口也可能使用不同字段或鉴权流程,不能假定所有服务都采用这行写法。知道“这是身份凭据”比死记某一个字段名更重要。
密钥有效为什么仍可能调用失败
密钥能够通过身份检查,还需要继续满足其他条件:
- 请求的接口和输入格式正确。
- 账号有权使用所选模型。
- 相关服务可用,并且没有触发服务限制。
- 当前请求使用的参数组合受到支持。
因此,“我的密钥没有填错”不能排除其他问题。
密钥应该放在配置中
在正常使用中,把凭据放进客户端的模型服务设置,由客户端在调用时携带。不要把真实密钥写进提示词、课程笔记、公开截图或分享文件。
提示词是模型处理的任务内容。你把密钥写进提示词,并不等于完成了接口要求的鉴权,反而会把凭据当成普通内容送入处理流程。
如果密钥意外公开,应到服务提供方撤销或更换,再更新客户端设置。仅删除一张公开截图,不能确保凭据已经失效。
2.4 看懂一份完整的简化请求
现在把地址、凭据和任务合起来看。
本例借用一种常见的 Chat Completions 消息格式,帮助你读懂结构。字段含义参考公开接口文档;地址、凭据、模型名和内容都是教学数据,部分非关键字段已省略。不同协议不一定采用相同结构。请求字段参考
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
}先不看全部细节,只分成三块。
第一块 目标与方法
POST /v1/chat/completions HTTP/1.1
Host: api.example.com它说明请求被提交到哪个主机的哪个接口。HTTP/1.1 在这里展示的是一种 HTTP 消息写法,实际通信也可能使用其他 HTTP 版本。
第二块 请求头
Authorization: Bearer DEMO_KEY_NOT_VALID
Content-Type: application/json请求头提供处理请求所需的附加信息。本例中,一项携带凭据,一项说明正文采用 JSON 格式。
JSON 是一种常见的数据表示方式。它用字段名和对应的值组织内容,让程序能够找到自己需要的信息。
例如:
{
"room": "301 室",
"capacity": 30
}这里的 room 对应一段文字,capacity 对应一个数字。双引号、冒号、逗号和大括号都参与构成语法,不是随意添加的装饰。请求正文写成 JSON,并不意味着其中的每一项内容都符合模型接口要求,还需要满足该接口规定的字段和类型。
另外,“请求和响应采用 JSON 传输”与“要求模型把答案写成 JSON”是两件事。前面的响应可以是 JSON,其中的回答内容仍然只是一段普通中文。
第三块 请求正文
正文里有三个本章需要认识的字段:
| 字段 | 本例的值 | 作用 |
|---|---|---|
| model | course-chat-model | 指定请求使用的模型标识 |
| messages | 一组带角色的消息 | 提供任务要求、问题和材料 |
| stream | false | 本例要求使用非流式响应 |
messages 使用方括号,表示它是一组消息。每条消息再说明自己的 role 和 content。
本例中,system 消息提供固定要求,user 消息提供具体材料和问题。后续章节会继续解释不同角色及其在应用中的组织方式;本章先看清楚它们确实是发送给模型的输入内容。
聊天框和请求不是一一对应的一行文字
你在输入框中看见的,可能只是最后一条用户消息。客户端还可能加入助手的固定要求、选入的对话历史、附件处理结果等。
这也解释了为什么同样一段新输入,在两个不同话题中可能得到不同回答:实际组织的请求不一定相同。第 07 章将专门讨论这些信息怎样进入上下文。
模型标识也需要按服务解释
模型字段告诉服务你希望调用哪个模型或服务提供的别名。它不是把一个模型文件上传给服务器,也不是对底层实际模型身份的独立证明。
某些服务会维护别名或进行路由映射。想判断实际提供了什么能力,还需要看服务说明及具体调用证据,不能只凭客户端显示的名字。
2.5 看懂返回结果和错误
服务处理请求后,会返回响应。对本章使用的 HTTP API 来说,可以先看三部分:状态、响应头和响应正文。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 人。
这个答案和本次提供的材料不一致,但请求可以完成接收、处理和返回,响应结构也可以完全正确。
接口检查和事实核验解决的是两个问题。对于这次活动问答,我们至少要依次确认:
- 是否收到了可识别的响应。
- 服务是否正常完成了这次请求,而不是返回错误。
- 所需回答是否已经生成完毕。
- 地点和容量是否与材料一致。
后续做文件任务时,还要检查文件是否真正生成、能否打开、内容是否符合要求。
遇到错误先读什么
常见的 HTTP 状态能帮助缩小排查范围,但还要结合服务返回的错误消息。下面是常见情况,不是所有服务统一的错误字典。
| 状态或现象 | 常见含义 | 优先检查 |
|---|---|---|
| 400 或 422 | 请求格式、字段或参数不符合要求 | 错误正文指出的字段、类型和组合 |
| 401 | 身份认证失败 | 凭据是否有效、是否发给正确服务 |
| 403 | 服务拒绝访问 | 账号、项目或资源权限,及服务说明 |
| 404 | 目标资源或接口不存在 | 地址与路径;也要阅读错误正文,不能只猜是模型名 |
| 429 | 请求触发某种限流或服务限制 | 该服务的具体限制说明和重试建议 |
| 500 或 503 | 服务端处理错误或暂时不可用 | 服务状态及错误记录 |
| 连接失败或超时,没有响应状态 | 没有拿到完整的 HTTP 响应 | 地址、网络连接及本次请求记录 |
例如,DeepSeek 的公开文档将无效凭据、余额不足、限流和服务器错误分为不同错误项。这说明不能见到一种错误就反复更换模型,更不能把所有问题都叫作“网络不好”。错误分类示例
如果没有收到响应,仍不能简单断言服务端一定没有处理请求。请求可能没有到达,也可能已经开始处理但返回过程中出现问题。先看记录和服务说明,再决定是否重试。
一点点出现的回答是怎样返回的
前面的请求采用 "stream": false。另一种常见方式是把它设为 true,让服务在生成过程中分批返回结果。
在本章采用的接口格式中,流式响应可以使用 SSE,也就是服务端发送事件。简化后可能像这样:
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 的两种公开调用格式为例,只看系统要求放在哪里,就已经能看到差异:
一种格式
messages 中包含 role 为 system 的消息
另一种格式
使用单独的 system 字段
messages 中放入用户等消息这两种格式都能表达固定要求与当前消息,但字段组织、鉴权方式、返回结构和部分参数支持需要分别查阅。不能只修改网址,就假定原来的完整请求一定可用。多种格式的调用说明、兼容范围示例
尤其要区分下面三件事:
| 说法 | 实际要检查的问题 |
|---|---|
| 客户端支持一种接口格式 | 它会不会按相应约定组织请求和读取响应? |
| 服务兼容一种接口格式 | 它支持哪些字段、参数和能力,有哪些差异? |
| 当前模型适合一个任务 | 它在所需输入、输出和工具能力上是否满足要求? |
能接收普通文本对话,不自动说明图像、工具调用或每一种高级参数都能按同样方式工作。后面的章节会按能力分别验证。
实验 E03 拆开一份请求
本实验不用发送请求。我们先借助完整示例,把“我在软件里填的内容”和“程序真正准备发出的内容”对应起来。
准备一张实验页
打开一个文本编辑器,新建 E03-请求阅读记录.txt;也可以直接在纸上完成。复制第 2.4 节的请求,保留一份原稿。
本例中的地址、模型名和密钥都是占位符。不要尝试用它们验证连接,更不要为了实验把自己的真实密钥填进共享记录。
第一步 把请求分成三块
在原稿上标出:
- 目标主机、路径和请求方法。
- 请求头。
- 请求正文。
留意请求头和正文之间的空行。在这份便于阅读的 HTTP/1.1 示例中,它帮助我们看清两个区域。实际客户端会负责按所用协议编码,不需要你手工拼出完整网络报文。
第二步 把五项内容翻译成自己的话
填写下表。先不要往下看参考解释。
| 你要找的内容 | 示例中的位置或值 | 用自己的话解释用途 |
|---|---|---|
| 服务主机和操作路径 | ||
| 调用凭据 | ||
| 模型标识 | ||
| 任务要求和材料 | ||
| 是否流式返回 |
然后回答:如果把用户问题从“地点和容量是什么”改成“活动时间是什么”,是否需要更换 API Key?
第三步 只修改一个问题
复制请求,在副本里只把用户消息最后一句改成:
问题:这场活动从几点开始,到几点结束?
比较原稿和副本,记录你改了哪个字段,哪些字段保持不变。
在这份请求设计里,你希望改变的是任务内容,而不是调用身份或模型。至于实际会返回什么,仍要等服务处理;修改了输入,不等于已经获得结果。
第四步 只修改返回方式
重新从原稿复制一份,把:
"stream": false改成:
"stream": true写下你的预测:服务会收到不同的问题吗?客户端接收结果的方式可能有什么变化?
这个修改的意图是请求分批返回,而不是自动更换模型、提高准确率或增加资料。具体服务怎样支持流式,需要看接口说明。
第五步 找出两个不同层面的错误
下面两段都可能让人误以为“已经写了 JSON”。分别判断问题在哪里。
片段一
{
"model": "course-chat-model",
"messages": [],
stream: true
}片段二
{
"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 正常返回
HTTP 状态:200 OK
回答:活动地点是 301 室,场地容量为 30 人。
finish_reason:stop响应卡 B 正常返回了错误事实
HTTP 状态:200 OK
回答:活动地点是 201 室,场地容量为 40 人。
finish_reason:stop响应卡 C 请求正文不符合要求
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": {
"message": "The messages field must be an array of message objects."
}
}响应卡 D 身份认证没有通过
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error": {
"message": "Authentication failed. Check the API credential."
}
}响应卡 E 请求触发限流
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 流式返回正常结束
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 已收到文字 但没有正常结束记录
HTTP 状态:200 OK
data: {"choices":[{"delta":{"content":"活动地点是 "},"finish_reason":null}]}
客户端随后记录:连接中断。
此卡展示的是本次捕获到的全部响应,未收到后续结束事件。响应卡 H 没有拿到 HTTP 响应
客户端记录:Connection timed out.
本次记录中没有收到 HTTP 状态和响应正文。第三步 先判断问题属于哪一层
先不要猜怎么修复。把每张卡归到下面一种或多种情况:
- 没有拿到完整的网络响应。
- 收到了响应,但服务拒绝处理请求。
- 已开始生成,但未确认正常结束。
- 正常结束,需要继续核验答案内容。
- 正常结束,但答案已被材料证实有误。
“收到了错误响应”和“根本没有收到响应”是两种情况。卡 C、D、E 都已经包含服务返回的信息,这些信息正是排查线索。
第四步 为每张卡只选一个优先检查动作
例如,卡 C 的错误正文已经指出 messages 的结构问题,就应先看请求字段,没必要先改写活动提示词。
卡 B 的服务调用已经正常结束,而事实与材料不同。此时应检查本次实际提供的材料、消息内容和回答依据,而不是立刻重新申请密钥。
对卡 H,不要直接写“密钥错误”。现有记录还不足以说明它已经走到身份认证那一步。
第五步 改写一句过早的结论
下面四句话都需要改得更准确。请各写一个替代说法。
- “HTTP 200 说明 AI 回答正确。”
- “屏幕开始出现文字,说明这次任务已经完成。”
- “服务返回错误,说明肯定没联网。”
- “调用超时,说明服务端一定没有处理过这个请求。”
第六步 完成一次可选的真实观察
如果你已经有可用的课程助手,可以在一个新话题中发送:
请只根据以下材料回答,不补充外部信息。
材料:青禾社区 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 状态和正文 | 检查地址、连接与请求记录,暂不能判定鉴权或模型输出 |
四句结论可以改写为:
- “这次请求得到了成功响应,答案仍需对照材料检查。”
- “服务已经开始返回内容,还需要观察是否完整结束。”
- “服务返回了具体错误,应先依据状态与正文缩小排查范围。”
- “客户端没有在限定时间内拿到响应,服务端处理到哪一步仍需进一步确认。”
自检题
先尝试用自己的话回答,再点开题目查看参考解释。
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 日:
- MDN API 术语解释:程序接口的基本概念。
- MDN HTTP 概述:客户端、服务端、请求和响应。
- Cherry Studio 模型服务:服务接入和协议类型。
- DeepSeek 首次 API 调用:具体服务如何提供模型调用。
- DeepSeek Chat Completions 字段说明:消息、流式返回、停止原因和用量字段。
- DeepSeek 错误码说明:一家服务的错误分类实例,不代表全部服务统一采用相同规则。
- DeepSeek 兼容格式说明:不同请求格式与部分能力支持差异。
后续加入真实界面截图或实测记录时,应单独注明软件版本、服务、模型与观察范围。本章的示例与响应卡均为教学材料,不是实际模型调用的记录。