Ollama API 总览

Ollama 的 API 可以驱动本地模型，也可以直连云端模型——两种用法共用同一套接口形态，只是 Base URL 和鉴权不同。这一章是全章的入口，先把地址和边界理清楚，后面 21 篇都是具体端点。

版本基线 v0.40.12，官方 docs.ollama.com/api/introduction。

一、三套 Base URL

这是最容易搞混的地方。Ollama 同时提供三种协议，各自的 Base URL 不同：

Anthropic 那一栏看着奇怪——它的基础地址不带路径，因为客户端自己会拼上 /v1/messages。

三条规则记牢：

• 云端请求需要 API Key，本地请求不需要
• 想通过本地服务用云端模型，先 ollama signin 登录
• 创建模型、删除模型只能走本地服务——云端不支持

二、最快的一次调用

curl https://ollama.com/api/chat \
  -H "Authorization: Bearer $OLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4:31b",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}],
    "stream": false
  }'

答案在 message.content 里。

本地推理则换成 http://localhost:11434/api/chat，去掉鉴权头，并用已下载的模型名：

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}],
    "stream": false
  }'

三、官方库

两个官方 SDK，本地和云端都能用：

• Python：ollama/ollama-python
• JavaScript：ollama/ollama-js

直连云端的配置是：host 设成 https://ollama.com，API Key 放进 Authorization: Bearer 头。

社区维护的库见主仓库 README。

四、版本策略

Ollama 的 API 不做严格版本号管理，但承诺稳定且向后兼容。弃用很少发生，一旦发生会在 release notes 里公告。

实际含义：接口路径不会随版本突然变，但新增字段是常见的（比如 prompt_eval_cached_count、done_reason 都是后加的）。写代码时对未知字段要宽容。

五、本章结构

建议先读 13.2–13.5 这四个通用机制，其他端点都是「通用机制 + 自己的字段」。

动手试

用两条命令确认你的环境支持哪种方式：

## ① 本地服务活着吗
curl http://localhost:11434/api/version

## ② 云端 Key 有效吗（没有 Key 会返回 401）
curl https://ollama.com/api/balance -H "Authorization: Bearer $OLLAMA_API_KEY"

第一条返回版本号，说明本地链路通；第二条返回余额 JSON，说明云端 Key 有效。