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

若你正在同時對接 OpenAI、Anthropic、Google 三家 API，卻苦於金鑰管理、帳單分散、模型切換要改程式碼——OpenRouter 可能是 2026 年最省心的統一閘道方案。AI 開發者、獨立部落格站長與多模型 Agent 工程團隊若需快速接入 GPT/Claude/Gemini 全模型，本文完整涵蓋：OpenRouter 定義與雙路由機制、OpenRouter vs 直連對照、6 步實操與 curl/Python/Node/串流/fallback 程式碼、定價與 BYOK、繁簡雙語 SEO 實戰、英文頁面流量診斷、P0–P2 行動清單與 FAQ，協助你在一天內完成從註冊到生產級呼叫的全流程。

SECTION 01 多廠商 LLM API 接入痛點：金鑰爆炸、帳單分散與容災缺失

2026 年中，前沿模型幾乎「每月一更」——GPT-5.6、Claude Fable 5、Gemini 3、Kimi K3、Grok 4.5 各有優勢。工程團隊在實際落地時仍面臨結構性矛盾：

• 金鑰與 SDK 碎片化：每家廠商 Base URL、認證標頭、模型 ID 格式不同，Agent 框架切換模型往往要改多處設定；
• 帳單與額度分散：OpenAI、Anthropic、Google 各自預付/後付，財務對帳與成本歸因困難；
• 單點故障無 fallback：某廠商限流或當機時，生產 Agent 直接中斷，缺少自動降級鏈；
• 免費試用門檻高：各平台免費額度政策不一，快速 A/B 測試新模型需反覆註冊；
• 雙語站點 SEO 陷阱：繁體頁有流量、英文頁長期零曝光——往往並非內容差，而是 hreflang、canonical 與索引策略未對齊（後文 §07–§09 詳述）。

OpenRouter 一句話定位：一個 API Key、一個 OpenAI 相容端點，即可呼叫 70+ 供應商 400+ 模型——模型 ID 統一為 provider/model 格式，Bearer Token 認證，零 SDK 遷移成本。

SECTION 02 OpenRouter 是什麼？統一閘道、OpenAI 相容與 model 命名規則

OpenRouter（openrouter.ai）是 LLM API 聚合閘道，將 OpenAI、Anthropic、Google、Meta、Mistral、Moonshot 等供應商的模型統一暴露為單一 REST 介面。核心契約如下：

建議請求標頭（便於 OpenRouter 統計與排行）：HTTP-Referer（你的站點 URL）與 X-Title（應用程式名稱）。官方文件詳見 openrouter.ai/docs。

SECTION 03 雙路由決策表：Model Routing vs Provider Routing、fallback 與 BYOK

OpenRouter 有兩層路由邏輯，理解差異是生產級呼叫的關鍵：

• 免費模型 25+：如 meta-llama/llama-3.3-70b-instruct:free，適合原型驗證，但有 RPM/TPM 頻率限制；
• 定價機制：多數模型 pass-through 官方價，OpenRouter 頁面即時顯示 input/output 單價；部分模型有小幅平台 markup；
• BYOK（Bring Your Own Key）：綁定各廠商自有 Key，費用走原廠帳戶，仍享受統一閘道與 fallback；
• 頻率限制：免費檔與未儲值帳戶有請求上限，儲值後按 Tier 提升；詳見 OpenRouter FAQ。

SECTION 04 OpenRouter vs 直連 API：五大優勢與什麼時候不該用

五大優勢：① 統一帳單與 Key 管理；② OpenAI SDK 零遷移；③ 400+ 模型一行切換；④ 內建 fallback 容災；⑤ 25+ 免費模型降低試錯成本。

什麼時候不該用 OpenRouter：

• 超低延遲場景：即時語音、高頻交易輔助——額外 10–80ms 不可接受；
• 超大体量生產：月消耗百萬美元級 Token，直連談判價更優；
• 嚴格合規：醫療 HIPAA、金融資料駐留——需原廠 BAA 與區域 endpoint；
• 廠商專屬功能：如 OpenAI Assistants API、Anthropic Computer Use 等未完全透傳的特性；
• 已有 BYOK 企業合約：若原廠已給深度折扣，OpenRouter 中間層價值有限。

SECTION 05 從 0 到 1 接入 OpenRouter：6 步實操 + 全端程式碼範例

1. 註冊 OpenRouter 帳號：造訪 openrouter.ai，用 GitHub 或 Google 登入，完成電子郵件驗證。
2. 建立 API Key：進入 Dashboard → Keys → Create Key，複製 Key 並勿提交至公開 Repo。
3. 設定環境變數：在本機或 CI 設定 OPENROUTER_API_KEY=sk-or-v1-...，可選 OPENROUTER_BASE_URL=https://openrouter.ai/api/v1。
4. 傳送首次請求：用 curl 或 Python 呼叫 /chat/completions，確認回傳 choices[0].message.content。
5. 啟用串流輸出：設定 stream: true，處理 SSE 事件流，降低首 Token 感知延遲。
6. 設定 fallback 鏈：在 body 傳入 models 陣列，測試主模型不可用時的自動降級。
7. 查詢模型列表：呼叫 GET /models，篩選免費模型與即時定價，寫入應用程式設定。

curl 最小範例

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://your-app.com" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "用三句話解釋 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']}",
        "HTTP-Referer": "https://your-app.com",
    },
    json={
        "model": "openai/gpt-4o",
        "messages": [{"role": "user", "content": "Hello"}],
    },
)
print(resp.json()["choices"][0]["message"]["content"])

OpenAI SDK 零遷移

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="your_openrouter_api_key",
)

response = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "對比 GPT 與 Claude 的程式設計能力"}],
)

Node.js（fetch）

const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "anthropic/claude-sonnet-4",
    messages: [{ role: "user", content: "Hi" }],
  }),
});
const data = await res.json();

串流輸出（stream: true）

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "寫一首關於 API 閘道的詩"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

fallback JSON（models 陣列）

{
  "models": [
    "anthropic/claude-sonnet-4",
    "openai/gpt-4o",
    "google/gemini-2.5-flash"
  ],
  "messages": [{"role": "user", "content": "若主模型不可用，自動降級"}]
}

Models API（GET /models）

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  | jq '.data[] | select(.pricing.prompt == "0") | .id'

第三方教學可參考 dev.to：OpenRouter API 多模型整合完整指南。

SECTION 06 OpenRouter 定價、免費模型與 BYOK：2026 費用決策矩陣

SECTION 07 英文頁面流量低？抓取 / 索引 / 內容 / 外鏈三層診斷清單

雙語站點常見現象：繁體頁有自然流量，英文頁長期 impressions ≈ 0。按以下三層 + 修復順序排查：

SECTION 08 繁體中文 SEO 實戰：關鍵字矩陣、標題訊號詞與分發渠道

內容結構：H1 含核心詞 → 首段 Snippet-Ready → H2 模擬真實搜尋詞 → 對照表 + 程式碼區塊 + FAQ。

繁體中文分發渠道：Medium 繁體專欄（技術教學）、Facebook 開發者社團（問答引流）、PTT Soft_Job（開發者社群）、iThome（工具向）、Line 官方帳號（摘要 + 外鏈）。

SECTION 09 英文 SEO + hreflang / canonical / sitemap 技術專項

hreflang / URL / canonical / sitemap 建議：

• URL 結構：https://macnox.com/{lang}/blog/{slug}.html，slug 各語系統一英文；
• canonical：每頁僅宣告自身 URL，禁止跨語系 canonical 到繁體頁；
• hreflang：在站點級 sitemap 或 head 宣告 zh-Hant / en 互指（MACNOX 博文頁目前僅用 canonical，hreflang 建議在 sitemap 層統一維護）；
• sitemap：各語系獨立 sitemap，新文發布後立即 ping Search Console；
• 技術 SEO 專項：Core Web Vitals、行動端可讀性、JSON-LD 結構化資料、內部連結密度。

SECTION 10 Schema 建議、發布分發渠道與 P0–P2 行動清單

Article + FAQPage Schema 建議：在 BlogPosting JSON-LD 的 mainEntity 嵌套 FAQPage，將 FAQ 問答同步寫入（本頁 head 已植入）。同時保留 datePublished、dateModified、author、publisher。

發布分發渠道清單：

• 繁體中文：Medium 繁體、PTT、iThome、Facebook 開發者社團、Line 官方帳號；
• 英文：dev.to、Hacker News、Reddit r/LocalLLaMA、X/Twitter thread；
• 站內：更新 blog index、相關文互鏈、sitemap ping。

SECTION 11 效果追蹤指標與可引用技術資料

• 閘道規模：70+ 供應商、400+ 模型、25+ 免費模型（以 openrouter.ai/models 即時為準）。
• API 相容：OpenAI /v1/chat/completions 格式，Bearer 認證，model ID 為 provider/model。
• 額外延遲：閘道轉發約 10–80ms，取決於地理距離與 Provider 負載。
• fallback：請求 body models 陣列按優先順序自動降級。
• BYOK：綁定原廠 Key，費用走原廠帳戶，仍享統一路由。

以下權威來源可在發版後再次開啟連結核對技術細節：

OpenRouter 官方文件

OpenRouter FAQ

dev.to：OpenRouter API Complete Guide

OpenRouter 解決了「多模型統一呼叫」的工程問題，但對需要整合 LLM Agent、Xcode 編譯鏈與 macOS CI/CD 的團隊，仍有三類現實短板：① 雲端 API 閘道無法替代本機 Metal / Core ML 編譯驗證；② 虛擬機跑 macOS CI 存在 Hypervisor 損耗與簽章鏈相容問題；③ 本機 Mac 關機即斷流，難以 7×24 跑 Agent 流水線。對於需要零損耗原生 Apple 算力、穩定 iOS CI/CD 與 AI Agent 7×24 自動化的生產環境，MACNOX 的雲端實體 Mac 節點通常是更優解：100% 蘋果原裝實體機、開放完整 Root 權限、無 Hypervisor 損耗、按天/週/月彈性下單。可參考Kimi K3 深度評測、Grok 4.5 評測，以及Mac Mini M4 租 vs 買費用對比。

SECTION 12 常見問題 FAQ