OpenAI 兼容 API 指南 — 从 Ollama 本地端点到托管前沿模型

“OpenAI 兼容”表示 API 使用与 OpenAI 的/v1/chat/completions相同的线路格式——因此任何 OpenAI SDK 或工具都可以使用它，只需更改base_url。Ollama 为在你的机器本地运行的模型提供 OpenAI 兼容端点。Kunavo 为托管的前沿模型——Claude、GPT 以及图像、视频和音频模型——提供一个统一 bearer token。本指南将介绍这种模式，以及如何在两者之间切换而无需重写代码。

“OpenAI 兼容”是什么意思

OpenAI Chat Completions 格式已成为事实标准：输入一个messages数组，输出一个choices[].message，使用 Server-Sent Events 进行流式传输，并通过tools实现函数调用。任何遵守这一契约的端点都属于“OpenAI 兼容”，官方openai SDK（Python、Node 以及所有社区移植版本）只需设置base_url即可指向它。

Ollama 模式（本地）

Ollama 在本地运行开放模型，并通过http://localhost:11434/v1提供服务：

from openai import OpenAI

# Ollama exposes an OpenAI-compatible endpoint on localhost
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

相同代码，托管的前沿模型（Kunavo）

将完全相同的 SDK 指向 Kunavo，并选择一个前沿模型。只有base_url、api_key和model会改变——调用逐字节相同：

import os
from openai import OpenAI

# Same SDK, same call shape — only base_url, api_key and model change
client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-haiku-4-5, gpt-5-5, gpt-5-6-terra...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

在/app/keys获取密钥；快速入门提供 Node 和 curl 示例。

本地与托管——何时使用哪一种

一种常见配置是：离线开发时在localhost使用 Ollama，生产环境使用 Kunavo 的托管质量——只需切换一个环境变量。关于两端共同实现的逐字段契约——参数、流式增量、tool_calls、usage对象，以及与 Ollama 的v1接口的对照表——请参见/v1/chat/completions 参考及其 Ollama OpenAI 兼容性部分。

在运行时发现模型

与 Ollama 的/api/tags类似，Kunavo 提供 OpenAI 形状的模型目录。请在运行时解析 slug，而不要硬编码：

# Discover every enabled model (OpenAI-shaped, like Ollama's /api/tags)
curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

不止聊天

同一个密钥可以访问图像（/v1/images/generations）、视频（/v1/video/generations）和音频端点——它们都采用 OpenAI 形状。请参见多模态 AI 指南和OpenRouter 对比，了解 Kunavo 与其他网关的区别。

有一个超出通常“兼容”定义的接口，值得了解：POST /v1/responses。Codex CLI 仅通过 Responses API 接受自定义供应商，这就是为什么大多数 OpenAI 兼容网关根本无法驱动它——Codex 每 token 的成本通过一个可运行的配置块解决了这一点。若要计算包含缓存输入的 GPT 工作负载价格，OpenAI API 价格计算器会使用你自己的 token 数量。

常见问题