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 數量。

常見問題