OpenRouter 完整指南：從零到一用一個 Key 呼叫 GPT、Claude、Gemini 全模型

OpenRouter 是什麼——用一組 Key 統一呼叫 GPT / Claude / Gemini / DeepSeek

OpenRouter 是一個統一 LLM API 閘道：用一組 API Key + 一個 OpenAI 相容 Endpoint（https://openrouter.ai/api/v1/chat/completions），即可呼叫 GPT、Claude、Gemini、Llama、DeepSeek、Qwen、Mistral 等來自 70+ 家供應商的 400+ 模型，而不必為每個廠商分別註冊、接入 SDK、管理帳單。

• 認證方式：Authorization: Bearer $OPENROUTER_API_KEY
• 相容協定：OpenAI Chat Completions 格式——已有 OpenAI SDK 程式碼基本不用改，只需換 base_url 和 api_key
• 模型命名：供應商/模型名，例如 openai/gpt-4o、anthropic/claude-3.5-sonnet、google/gemini-2.5-pro、deepseek/deepseek-chat

多模型整合的真正摩擦往往不在 API 本身，而在帳號分散、SDK 版本衝突、帳單對帳與故障切換——OpenRouter 把這些運維負擔收斂到單一閘道層。代價是請求多經過一層路由，延遲通常增加約 10–80ms，且部分廠商專屬能力（如 Prompt Caching、Batch API）無法完整透傳。

OpenRouter 內部做兩層獨立路由決策，這是理解它行為的關鍵：

如果主力供應商限流或報錯，OpenRouter 會自動切換到下一個可用供應商或備選模型（models 陣列），業務側通常不會收到 500——這套容錯邏輯內建在閘道層，不需要你在業務程式碼裡手寫 circuit breaker。

OpenRouter 與直接呼叫 OpenAI / Anthropic API 有什麼差別

OpenRouter 不是要取代官方 SDK，而是在「多模型場景」和「官方直連」之間提供折衷。下面這張表幫你快速判斷差異。

OpenRouter 的 5 個核心優勢（含什麼時候不該用）

優勢一：一組 Key 打通所有模型，遷移成本幾乎為零。換模型 = 改一個 model 字串，不需要重寫業務邏輯或為每個廠商寫適配層。

優勢二：跨供應商自動故障轉移。可以明確設定 fallback 鏈，主力掛了自動依序嘗試備選模型，業務程式碼無需額外重試邏輯。

優勢三：統一帳單和用量分析。一個 Dashboard 看所有模型的消耗、成本、延遲（TTFT）、吞吐量。

優勢四：定價對使用者友善——無 token 加價。OpenRouter 官方 FAQ 明確不在 token 單價上加價，只在儲值環節收 5.5% 手續費。中大体量使用者可用 BYOK（自帶供應商 Key）模式：每月前 100 萬次請求免費，超出後對等值部分收 5% 服務費。

優勢五：場景定位清晰。適合快速原型驗證、多模型 A/B 測試、中小體量應用（月消費幾千美元以內）、需要多模型 fallback 提升可用性的場景，以及用同一套 Prompt / Agent 框架跑遍市面所有模型。

實戰教學——6 步接入 OpenRouter API

下面是從註冊到發出第一次請求的完整路徑。建議在一台乾淨的 macOS 開發機上操作——避免 Python 版本衝突和舊 SDK 殘留干擾排查。

1. 註冊 OpenRouter 帳號：造訪 openrouter.ai，用 GitHub 或電子郵件註冊。
2. 建立 API Key：在 Dashboard → Keys 頁面產生金鑰，存入環境變數 OPENROUTER_API_KEY，不要硬編碼進版本庫。
3. （可選）儲值 Credits：呼叫付費模型需要帳戶有餘額；儲值時收取 5.5% 手續費（最低 $0.80）。未儲值也可使用 25+ 免費模型，但有頻率限制。
4. 查詢可用模型：用 GET /api/v1/models 確認目標模型 ID 和當前定價。
5. 發出第一次請求：用 curl 或 SDK 呼叫 /v1/chat/completions，指定 model 參數。
6. 驗證串流與 Fallback：在正式接入前，分別測試 stream: true 和 models 陣列的容災鏈路，確認業務側能正確處理。

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

程式碼範例——curl / Python / Node.js / OpenAI SDK 相容寫法

以下四種寫法涵蓋最常見的接入場景。OpenRouter 建議攜帶 HTTP-Referer 和 X-Title 請求標頭，用於排行榜統計。

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3.5-sonnet",
    "messages": [
      { "role": "user", "content": "用一句話解釋什麼是量子計算" }
    ]
  }'

import requests
import os

response = requests.post(
    url="https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "google/gemini-2.5-pro",
        "messages": [
            {"role": "user", "content": "幫我寫一個快速排序的 Python 實作"}
        ],
    },
)
print(response.json()["choices"][0]["message"]["content"])

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "HTTP-Referer": "https://your-app-domain.com",
        "X-Title": "My App",
    },
)
print(completion.choices[0].message.content)

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const completion = await openai.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Explain OpenRouter in one sentence" }],
});

console.log(completion.choices[0].message.content);

const stream = await openai.chat.completions.create({
  model: "anthropic/claude-3.5-sonnet",
  messages: [{ role: "user", content: "寫一首關於秋天的短詩" }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

{
  "model": "anthropic/claude-3.5-sonnet",
  "models": [
    "anthropic/claude-3.5-sonnet",
    "openai/gpt-4o",
    "google/gemini-2.5-pro"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello" }]
}

主模型被限流或報錯時，OpenRouter 會依序自動嘗試列表裡的下一個模型，業務側無需額外重試邏輯。

進階用法——免費模型、Fallback 容災與成本控制

• 免費模型：OpenRouter 提供 25+ 免費模型（如部分 Llama、Gemma、DeepSeek 免費檔）。未儲值帳戶約 50 次/天；帳戶儲值 ≥$10 後提升到 1000 次/天、20 次/分鐘。
• BYOK 模式：自帶各廠商 API Key，每月前 100 萬次請求免 OpenRouter 服務費，超出後對等值部分收 5%。適合已有大量官方 Key 的中大体量使用者。
• 定價機制：Token 按供應商原價透傳，無 markup；僅在儲值購買 Credits 時收 5.5% 手續費（最低 $0.80），加密貨幣支付另收 5%。
• 成本監控：在 Dashboard 按模型查看 prompt / completion 單價和實際消耗，避免多模型 A/B 測試時帳單失控。

定價檔位、免費模型列表和限流規則可能隨時間調整——請以官方文件為準，而不是本文轉述。

OpenRouter 官方文件

OpenRouter 官方 FAQ（定價與 BYOK 說明）

OpenRouter 官方 —— Provider Routing 機制說明

常見問題 FAQ

OpenRouter 解決的是「多模型 API 統一接入」的問題，但它管不了你的本地開發環境：Python 虛擬環境衝突、Node.js 版本不匹配、Agent 框架寫到一半把主力機弄髒——這些摩擦點在多模型實驗階段尤其常見。一台可以隨時清空、按天起租的真實 Apple Silicon Mac mini，用來跑 OpenRouter 接入腳本、Next.js 原型或長期掛著的 Agent 程序，比共用筆電更可控。我們在 Kimi K3 模型測試指南和 Xcode CI Runner 建置指南裡寫過類似的「乾淨機器」思路——OpenRouter 多模型聯調同樣適用。