OpenRouter 保姆級教程
從 0 到 1 接入 GPT/Claude/Gemini 全模型

多廠商 API 碎片化：接入統一閘道前的五類痛點

OpenRouter 本質是統一 LLM API 閘道（Unified LLM Gateway）：你只需維護一把 API Key，即可透過 OpenAI 相容協定存取 OpenAI、Anthropic、Google、DeepSeek 等廠商模型，無需為每家單獨寫鑑權與 SDK 適配層。但在決定遷移前，應先認清「直連多廠商」在生產裡常見的五類隱性成本。

1. 01

   多 Key 輪換稅：GPT、Claude、Gemini 各需獨立帳號與帳單，Key 外洩輪換、配額監控與告警分散在三套控制台，維運面指數膨脹。

2. 02

   SDK 方言稅：雖多數支援 OpenAI 格式，但 base_url、Header（如 Anthropic 版本號）、串流欄位與 tool call schema 仍有差異，Agent 框架切換模型時要改多處。

3. 03

   Failover 手寫稅：主模型 429 或宕機時需自寫重試鏈、指數退避與備模型映射；缺統一路由層時，每次加新模型都要改業務程式碼。

4. 04

   定價對帳稅：各廠商計價單位、快取折扣與 batch 規則不同，FinOps 難以在一張表裡對比「同一 prompt 換模型貴多少」。

5. 05

   免費額度分散稅：各平台免費 tier 規則不一；OpenRouter 聚合 25+ 免費模型並統一配額（未儲值 50 次/日，儲值 $10 後 1000 次/日，20 次/分鐘），但需理解平台費與 BYOK 邊界。

認清以上痛點後，再對照下一節的路由機制與對比表，判斷 OpenRouter 是否匹配你的延遲、合規與呼叫量級假設。

六步 Runbook：從註冊到 fallback 鏈驗證

以下六步可在 30 分鐘內完成首次呼叫；每步產出可寫入團隊 README，便於 onboarding 新成員。

1. 01

   註冊帳號：造訪 openrouter.ai，用 GitHub 或信箱建立帳戶。

2. 02

   建立 API Key：進入 Keys 頁面產生 Key，立即複製；生產環境勿提交到 Git，用金鑰管理服務託管。

3. 03

   設定環境變數：export OPENROUTER_API_KEY="sk-or-..."，CI/CD 與本機 .env 保持一致命名。

4. 04

   首次 curl 驗證：對 /v1/chat/completions 發 POST，確認 200 與 choices[0].message 結構。

5. 05

   設定 OpenAI SDK：Python/Node 中將 base_url 指向 OpenRouter，可選加 HTTP-Referer 與 X-Title 參與排行榜統計。

6. 06

   測試 fallback 鏈：用 models 陣列或故意指定不可用模型，驗證 auto failover 到備模型並記錄日誌。

curl 首次請求

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello from OpenRouter"}]
  }'

Python requests

import os, requests

resp = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "anthropic/claude-sonnet-4",
        "messages": [{"role": "user", "content": "Explain Model Routing vs Provider Routing"}],
    },
)
print(resp.json()["choices"][0]["message"]["content"])

Python OpenAI SDK（含 HTTP-Referer / X-Title）

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    default_headers={
        "HTTP-Referer": "https://your-app.example.com",
        "X-Title": "My Agent App",
    },
)

completion = client.chat.completions.create(
    model="google/gemini-2.5-pro-preview",
    messages=[{"role": "user", "content": "Summarize OpenRouter pricing"}],
)
print(completion.choices[0].message.content)

Node.js OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": "https://your-app.example.com",
    "X-Title": "My Agent App",
  },
});

const res = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(res.choices[0].message.content);

JavaScript 串流輸出

const stream = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Stream this response" }],
  stream: true,
});

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

Fallback 模型鏈（JSON）

{
  "model": "openai/gpt-4o",
  "models": [
    "openai/gpt-4o",
    "anthropic/claude-sonnet-4",
    "google/gemini-2.5-flash-preview"
  ],
  "messages": [{"role": "user", "content": "If primary fails, try fallbacks"}]
}

curl 拉取模型列表

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | jq '.data[] | {id, pricing}'

可引用硬數據、開發者 SEO 與生產部署收束

下列參數可直接引用進技術方案或 README；來源為 OpenRouter 官方文件與平台公開資料（2026 年 7 月）。

• 提供商規模：70+ inference 提供商聚合在同一閘道後。
• 模型數量：400+ 模型，命名規範 vendor/model。
• 免費模型：25+ 模型；未儲值 50 次/日，儲值 $10 後 1000 次/日，20 次/分鐘。
• 平台費：儲值 5.5%（最低 $0.80）；BYOK 100 萬 req/月免費檔，超出 5%。
• 延遲 overhead：相較直連，通常增加 10–80ms（視區域與 provider 而定）。

面向開發者的雙語 SEO / 英文流量診斷

若你的 Agent 產品或技術部落格需要同時觸達中英文開發者，OpenRouter 類 API 文件的 SEO 需注意以下工程實踐（而非簡單機翻）：

• hreflang 矩陣：中英頁面應互指 canonical 與 hreflang；避免同一 URL 混兩種語言導致 Google 判 duplicate。
• CDN / WAF 與 Googlebot：部分 CDN 預設規則會誤攔海外爬蟲；用 Search Console「URL 檢查」確認英文頁可被 Googlebot 抓取，而非僅 200 給人看。
• 禁止機翻英文：英文頁應用母語技術寫作重寫（術語、程式碼註解風格、搜尋詞），不要用中文正文一鍵翻譯——EEAT 與 bounce rate 會同時受損。
• 關鍵字矩陣：中文偏「OpenRouter 教程 / 接入 / 免費模型」；英文偏 “OpenRouter API guide”, “unified LLM gateway”, “OpenAI compatible multi-model”；程式碼示例中的 model ID 保持全球一致。

OpenRouter 解決了「多模型 API 統一接入」，但本機開發機在休眠、系統更新與行程被殺時會讓 7×24 Agent、cron 與 webhook 回呼中斷——API Key 再穩定，宿主不穩定仍會導致 failover 鏈空轉。筆電合蓋後 OpenClaw、LangGraph 或自研 daemon 無法保證 SLA；純 Linux VPS 又缺 Apple Silicon 與 macOS 工具鏈。對需要長期在線的 AI Agent 與自動化流水線，VpsMesh 的 Mac Mini 雲端租用通常是更優解：專用節點、彈性租期、可稽核環境，讓 OpenRouter 路由策略跑在真正 7×24 在線的宿主上，而不是賭本機機器今晚不合蓋。