API：一次模型请求与响应

API 解决的是软件怎样调用另一种能力

API是软件之间约定好的通信接口。一个天气应用可以通过天气API取得预报，一个AI应用也可以通过模型API提交输入并取得生成结果。使用API不一定意味着自己训练或部署模型，可以直接调用服务方已经运行的模型。

你在聊天网页里输入问题时，网页背后的应用已经替你完成了调用。自己开发一个AI功能，就是把“收集输入、发送请求、处理结果”放进自己的产品。对非程序员来说，先理解这三个环节，比先记命令行语法更有帮助。

一次模型调用怎样往返

假设做一个“消息改写器”。用户在页面输入“今天三点前发报告”。应用把这段原文与改写规则打包，发送给模型服务；服务运行模型，返回一段改写结果；应用读取返回内容并显示给用户。

这里有两次网络通信的可能：浏览器与应用后端通信，应用后端再与模型服务通信。许多产品会这样安排，以便保护凭据、控制用量和处理权限。具体架构可以不同，但模型密钥不应该作为公开网页里的普通文本暴露。

请求里通常有什么

下面是教学用的请求结构示意。它采用常见的消息形式帮助阅读，不代表所有服务都接受这些字段，也不能直接当作可运行命令。

{
  "model": "所选模型",
  "messages": [
    {"role": "system", "content": "礼貌改写，只用原有事实。"},
    {"role": "user", "content": "今天三点前发报告。"}
  ]
}

model说明希望调用哪个模型。messages包含本次消息；role标出消息来源与用途，content是具体内容。真正发送请求时，还需要正确的服务地址、身份凭据和符合接口要求的其他信息。下一课会详细解释消息角色。

响应里不只有一段文字

成功响应通常会包含生成结果，也可能带有请求编号、结束原因和用量信息。应用需要从结构里提取实际内容，而不是把所有字段直接展示给使用者。失败时可能得到权限、额度、格式或服务错误，而不是模型回答。

在改写例子中，返回文字可能是：“报告方便今天下午三点前发我吗？谢谢！”此时完成的是生成草稿，应用没有因此自动发送消息，收件人也没有因此同意期限。API返回什么能力的结果，就应按那个能力理解。

API Key、模型和额度分别是什么

API Key通常是一种调用凭据，服务用它识别或授权调用方，并关联相应账户与用量。模型是要运行的能力，额度是账户允许的使用范围。拥有一个密钥，并不代表可以免费使用所有模型或访问所有数据。

可视化平台把许多接口细节封装成节点：输入节点收材料，LLM节点调用模型，输出节点显示结果。课后可以用Dify体验这一过程。即使用了节点界面，底层的请求、响应与错误处理仍然存在。