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

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

一、三套 Base URL

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

API	直连云端	本地服务
Ollama 原生	https://ollama.com/api	http://localhost:11434/api
OpenAI 兼容	https://ollama.com/v1	http://localhost:11434/v1
Anthropic 兼容	https://ollama.com	http://localhost:11434

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	认证、流式、用量、错误
协议兼容	13.6 – 13.7	OpenAI / Anthropic 兼容层
推理端点	13.8 – 13.11	generate / chat / embed / systemone
模型管理	13.12 – 13.20	列举、查看、创建、复制、拉推、删除、版本
云端计费	13.21 – 13.22	用量统计、余额查询

建议先读 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 有效。