API 到底是什么？用点餐窗口讲明白

API 这词听着唬人，其实是日常生活里天天在做的事。这篇把它讲到你不用记也能复述出来。

一、API 就是"服务窗口"

API 全称 Application Programming Interface，翻译过来是**"程序之间的接口"**。别背定义，看餐厅就懂了：

你（或某个软件） = 顾客；
大模型（Ollama 里的 qwen2.5、云端的通义千问）= 后厨，真正干活做菜的地方；
API = 前台的点餐窗口。

你 ──递单子：帮我查北京天气──→ [API 窗口] ──→ 后厨（大模型）
你 ←──取餐：北京今天晴 5℃─── [API 窗口] ←── 后厨（大模型）

你从头到尾不需要知道后厨怎么炒菜------模型内部几百亿参数怎么算的、显存怎么调度，你不用懂。你只要按窗口的规矩递单子，它按规矩把结果递出来。

窗口的"规矩"是什么

点餐得有固定格式：菜单编号、份数、辣度。API 也一样，它规定了三件事：

用什么方式递（GET 还是 POST，好比"堂食单"还是"外送单"）；
单子上写什么（参数：要查哪个城市、问什么问题）；
餐怎么端出来（返回格式：一般是 JSON）。

只要按这个约定来，谁的软件来点餐都能点成------这就是 API 存在的意义：让互不相识的软件能对上话。

二、一次 API 调用，完整长什么样

拿本地 Ollama 举例。它提供的"聊天窗口"地址是：

复制代码

http://localhost:11434/api/chat

拆开看：

部分	内容	作用
地址	`http://localhost:11434`	后厨在哪
路径	`/api/chat`	窗口办什么业务：聊天
方法	`POST`	我要提交内容（递单子），不是单纯查询
请求体	`{"model":"qwen2.5","messages":[...]}`	单子内容：用哪个模型、说了什么话
响应体	`{"message":{"content":"你好！"}}`	端出来的餐：模型的回答

用命令行实际点一次单，就是长这样：

bash 复制代码

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:latest",
  "messages": [{"role": "user", "content": "用一句话解释什么是API"}],
  "stream": false
}'

返回的就是一段 JSON，里面的 content 字段就是模型的回答。

看到这里你就明白了：所谓"调用大模型"，剥掉所有包装，就是往一个网址 POST 一段 JSON，然后收一段 JSON 回来。

三、API Key 是什么

本地 Ollama 是自己家厨房：你点自己家的菜，不用出示任何卡。

云端大模型（DeepSeek、通义千问、OpenAI）的后厨在别人家服务器上，人家得知道：

你是谁？（验证身份）
你这个月点了多少单？（计费）
该不该让你点？（权限、余额）

所以给你发一张"点餐卡"------一串字母数字，就是 API Key。每次点单都带上它，服务器认卡不认人。

三条实用提醒：

API Key 等于钱。泄露了别人就能刷你的余额，别发群里、别传 GitHub、别贴截图不遮；
本地服务一般不用 Key ，但有些软件强制要求这个字段非空，随便填个 ollama 就行；
Key 泄露了立刻去后台删掉重建，旧的自然失效。

四、Ollama 有两套窗口，别走错门

这个细节很多人踩坑。Ollama 同时提供两套 API：

接口	地址示例	谁在用
自家原生接口	`/api/chat`、`/api/generate`、`/api/tags`	Ollama 自己的界面、一些专为 Ollama 写的工具
OpenAI 兼容接口	`/v1/chat/completions`、`/v1/models`	绝大多数第三方软件、Agent 客户端

为什么会有第二套？ 因为"OpenAI 的接口格式"事实上成了行业通用语言。Ollama 也提供一份一模一样的，这样全世界的软件只要支持 OpenAI，就能直接连本地模型，不用为 Ollama 单独开发。

所以：

接 Dify 的 Ollama 供应商 → 走原生接口，基础 URL 填到 11434 就行；
接 认 OpenAI 格式的客户端 （很多桌面 Agent 工具）→ 基础 URL 要填到 .../v1。

五、把三个词串起来

这几个词你这两天一直在混着用，放一起就清楚了：

复制代码

基础 URL = 后厨在哪栋楼          http://host.docker.internal:11434
API      = 那栋楼的服务窗口      按约定递单子、接餐的那套规矩
API Key  = 点餐卡               云端后厨认人记账用，自家厨房不用

放到具体场景里看：

场景	窗口在哪	后厨是谁	要不要卡
Dify 连本地 Ollama	`http://host.docker.internal:11434`	你电脑上的 qwen2.5	不用
Dify 连通义千问	阿里云百炼的云端地址	通义千问	要（百炼申请）
Agent 客户端连本地 Ollama	`http://localhost:11434/v1`	你电脑上的 qwen2.5	不用（但字段得填）

六、顺便说清两个容易混的概念

API ≠ 大模型。 API 是窗口，模型是后厨。同一个窗口后面可以换不同的模型（Ollama 一个端口后面就装着好几个），同一个模型也可以开好几个窗口（百炼给通义千问开了 API，也支持 OpenAI 兼容格式）。

API ≠ Function Calling。 API 是"人和软件去调服务"；Function Calling 是"大模型自己决定去调某个服务"。前者是你点餐，后者是模型看了你的问题后说"这单得叫后厨做"。但底层用的是同一套东西------Function Calling 调工具，本质还是在调一个 API。

七、这一篇要记住的三句话

API 就是服务窗口：按约定递单子，按约定收结果，不用管后厨怎么做的。
一次调用 = 一个地址 + 一个方法 + 一段参数，返回一段 JSON，仅此而已。
API Key 是点餐卡，等于钱，泄露了要立刻作废重建。