OpenRouter 手把手教學：從零到一接入 GPT / Claude / Gemini 全模型

若你正為每一家大模型供應商分別註冊帳號、維護多套 SDK 與帳單，OpenRouter 可能是 2026 年最省事的解法——一支 API Key ＋ 一個 OpenAI 相容 Endpoint，即可呼叫 GPT-4o、Claude 3.5 Sonnet、Gemini 2.5 Pro、DeepSeek、Qwen 等 400+ 模型。本文面向 AI 應用開發者與技術決策者，涵蓋雙路由機制、五大核心優勢、與直連 API 的對照決策、逐步接入流程，以及 curl / Python / Node.js / OpenAI SDK 全套範例與 Fallback 容災設定。結論先行：中小體量多模型場景選 OpenRouter 遷移成本幾乎為零；超大体量、極致延遲或嚴格資料駐留仍應直連官方 API。

SECTION 01 多模型接入時，開發者最常踩的四類雷

• 帳號與 Key 碎片化：OpenAI、Anthropic、Google、Meta、DeepSeek 各需獨立註冊、計費與 SDK 適配，維運成本隨模型數量線性成長。
• 單點故障無容錯：某一供應商限流或宕機時，業務端需自行實作重試、切換供應商與 circuit breaker，程式碼複雜度陡增。
• 帳單對帳困難：五個後台五份帳單，無法在一個 Dashboard 統一檢視 token 消耗、延遲（TTFT）與吞吐量。
• 模型切換成本高：換模型往往意味著重寫請求適配層；與DeepSeek V4 API 遷移或Kimi K3 多模型對照場景疊加時，適配層維護成為瓶頸。

SECTION 02 OpenRouter 是什麼？雙路由機制一次講清

一句話定義：OpenRouter 是統一 LLM API 閘道／聚合層——用一支 API Key和OpenAI 相容 Endpoint https://openrouter.ai/api/v1/chat/completions，呼叫來自 70+ 供應商、400+ 模型的能力，無需為每一家供應商單獨註冊、接入 SDK、管理帳單。認證方式：Authorization: Bearer $OPENROUTER_API_KEY。模型命名規則為 供應商/模型名，例如 openai/gpt-4o、anthropic/claude-3.5-sonnet、google/gemini-2.5-pro、deepseek/deepseek-chat。

已有 OpenAI SDK 程式碼基本不用改，只需替換 base_url 和 api_key，請求體、訊息格式與串流處理邏輯完全不變。

此外：免費模型有 25+ 個（部分 Llama、Gemma、DeepSeek 免費檔），未儲值約 50 次/天，帳戶儲值 ≥$10 後提升至 1000 次/天（20 次/分鐘）。定價機制：OpenRouter 不在 token 單價上加價，按供應商原價透傳；僅在儲值購買 Credits 時收取 5.5% 手續費（最低 $0.80），加密貨幣支付另收 5%。BYOK（自帶供應商 Key）模式下，每月前 100 萬次請求免費，超出後對等值部分收 5% 服務費。

SECTION 03 OpenRouter 和直接呼叫 OpenAI / Anthropic API 有什麼差別

五大核心優勢：① 一支 Key 打通所有模型，遷移成本幾乎為零；② 跨供應商自動 Failover；③ 統一帳單與用量分析；④ 無 token 加價，定價對使用者友善；⑤ 適合多模型對照、Agent 框架統一跑遍市面模型。

什麼時候不該用 OpenRouter（建立信任的平衡視角）：

• 單一模型、超大体量（月消費數萬美元以上），5.5% 儲值手續費已值得自建供應商直連
• 需要 Anthropic Prompt Caching 計費最佳化、OpenAI Batch API / Assistants API、Google Vertex AI 專屬工具鏈
• 對延遲極度敏感（閘道額外 10–80ms 跳數不可接受）
• 資料合規／資料駐留要求，不允許流量經過美國第三方中間層

OpenRouter 不是要取代 OpenAI／Anthropic 官方 SDK，而是在「多模型場景」和「官方直連」之間提供折中方案。

SECTION 04 實戰教學：逐步接入 OpenRouter API ＋ 全套程式碼範例

1. 註冊 OpenRouter 帳號：造訪 openrouter.ai，使用 Google／GitHub 或電子郵件註冊，進入 Dashboard。
2. 建立 API Key：在 Keys 頁面產生金鑰，存入環境變數 OPENROUTER_API_KEY，切勿提交到版本庫。
3. 發起第一次請求：用下方 curl 或 SDK 範例驗證連線與計費。
4. （建議）設定 HTTP-Referer：OpenRouter 建議攜帶 HTTP-Referer 與 X-Title，用於排行榜統計與用量歸屬。
5. 查詢可用模型：呼叫 GET /api/v1/models 取得即時模型清單與定價。
6. 設定 Fallback 鏈：正式環境建議設定 models 陣列，主力模型限流時自動切換備選。
7. 監控用量與成本：在 Dashboard 檢視各模型 token 消耗、TTFT 與延遲分佈，設定儲值告警。

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": "用一句話解釋什麼是量子計算" }
    ]
  }'

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://vpsnix.com",
        "X-Title": "VPSNIX Blog Demo",
    },
)
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 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);
}

多模型 Fallback 容災設定（體現優勢二的落地程式碼）：

{
  "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 按順序自動嘗試清單中的下一個模型，業務端無需額外重試邏輯。

查詢可用模型清單：

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

SECTION 05 進階用法：免費模型、定價機制與可引用硬核數據

可引用硬核數據：

• 模型規模：70+ 供應商、400+ 模型，統一 Endpoint /v1/chat/completions
• 協定相容：OpenAI Chat Completions 格式，現有 SDK 改兩行即可遷移
• 路由層：Model Routing（model 欄位）+ Provider Routing（provider 物件，價格倒平方加權）
• Failover：models 陣列 + route: "fallback"，主力掛掉自動切換
• 定價：無 token markup；儲值 5.5%；BYOK 前 100 萬次/月免費
• 免費模型：25+ 個，未儲值 50 次/天 → 儲值 ≥$10 後 1000 次/天

官方文件與 FAQ（發版後請再次開啟連結核對）：

OpenRouter 官方文件

OpenRouter 官方 FAQ — 定價與 BYOK 說明

OpenRouter 模型清單與即時定價頁

典型高效組合是：OpenRouter 負責多模型推理與 A/B 對照，VPSNIX M4/M4 Pro 實體節點負責 Xcode 編譯、Metal 除錯與 AI Agent 7×24 部署——雲端 LLM 再強也無法在 Hypervisor 虛擬 macOS 上穩定跑 iOS 憑證鏈；虛擬化方案伴隨 EULA 風險與 20–40% 效能損耗。對於需要零損耗原生算力、穩定 iOS CI/CD 與 AI Agent 自動化的正式環境，VPSNIX 的雲端實體節點通常是更優解：100% 蘋果原裝硬體、完整 Root 權限、無 Hypervisor 損耗、按天／週／月彈性下單。報價見定價頁；若已在用 OpenRouter 跑Kimi K3或DeepSeek V4做程式碼推理，更應將編譯鏈鎖定在合規實體環境。

SECTION 06 常見問題 FAQ