OpenRouter 保姆級教程：從0到1接入
GPT/Claude/Gemini 全模型（2026 最新完整指南）

若你是需要同時呼叫 GPT-4o、Claude 3.5、Gemini 的 AI 開發者、獨立駭客或 Agent 自動化團隊，卻被「每家廠商一套 Key、一套 SDK、五張帳單」拖到原型遲遲無法上線，OpenRouter 可能是 2026 年 CP 值最高的解法：一組 API Key 加一個 OpenAI 相容 Endpoint，即可觸達 70+ 供應商、400+ 模型。本文先拆解六大接入痛點，再涵蓋五大優勢與「不該用」場景、OpenRouter vs 直連對照表、curl/Python/Node.js 全套程式碼、≥8 步保姆級接入清單、Fallback 與免費額度技巧、雙語 SEO 打法、分發渠道表、可引用技術參數與 FAQ，最後以7×24 Agent 宿主收束到 Mac Mini 雲端租用路徑。定價見 租用價格頁，下單見 雲端訂購頁；可與 OpenRouter 週調用量排行篇 交叉閱讀。

[ SECTION_01 ] // PAIN_MAP OpenRouter 是什麼？統一 LLM 閘道原理與開發者六大接入痛點

OpenRouter 是一個「統一 LLM API 閘道／聚合層」：用一組 API Key 加一個 OpenAI 相容 Endpoint，即可呼叫來自 70+ 家供應商、400+ 個模型（GPT、Claude、Gemini、Llama、DeepSeek、Qwen、Mistral 等），無須為每家廠商分別註冊帳號、接入 SDK、管理帳單。

• 多 Key 管理地獄：OpenAI、Anthropic、Google 各有一套帳號與帳單，Agent 框架換模型就要改適配層——「OpenRouter API 接入」搜尋量背後正是這個痛點。
• 限流與宕機無容災：單一廠商 429/500 時，業務端得自己寫 retry 與 circuit breaker，正式環境極不穩定。
• 模型命名混亂：各廠商 model ID 格式不同（gpt-4o vs claude-3-5-sonnet-20241022 vs gemini-2.5-pro），多模型 A/B 測試成本常被低估。
• 帳單對帳五套後台：Token 消耗、延遲、成本分散在 5 個 Dashboard，月結對帳耗時且易漏算。
• 免費額度分散：各廠商免費 tier 規則不同，原型階段難以快速「零成本」跑通多模型對比。
• 筆電跑 Agent 斷鏈：即便 API 路由再聰明，本地 Gateway 合蓋 sleep 後 OAuth 過期、長時任務中斷——與 API 選型同等重要卻常被忽視。

技術核心：OpenRouter 統一 Endpoint 為 https://openrouter.ai/api/v1/chat/completions，認證方式為 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。

自動故障轉移（Fallback）：主力供應商限流或報錯時，OpenRouter 自動切換下一個可用供應商或備選模型（models 陣列），業務端通常不會收到 500。

免費模型：平台提供 25+ 免費模型（部分 Llama、Gemma、DeepSeek 免費檔），未儲值約 50 次/天，帳戶儲值 ≥$10 後提升至 1000 次/天、限速 20 次/分鐘。

定價機制：OpenRouter 不在 token 單價上加價，按供應商原價透傳；僅在儲值購買 Credits 時收取 5.5%（最低 $0.80）手續費，加密貨幣支付另收 5%。BYOK（自帶供應商 Key）模式下，每月前 100 萬次請求免費，超出後對等值部分收 5% 服務費。

下列為 OpenRouter 官方文件入口，發版或上游更新後請再次開啟連結核對：

https://openrouter.ai/docs

https://openrouter.ai/docs/faq

https://openrouter.ai/api/v1/chat/completions

[ SECTION_02 ] // ADVANTAGES OpenRouter 五大核心優勢：什麼時候該用、什麼時候不該用

優勢一：一組 Key 打通所有模型，遷移成本幾乎為零

• 不用為 OpenAI、Anthropic、Google、Meta、DeepSeek 各註冊一套帳號、Key、SDK。
• 只需改兩行程式：base_url 和 api_key，其餘請求體、訊息格式、串流處理邏輯完全不變。
• 換模型等於改一個字串（model 參數），不需要重寫業務邏輯。

優勢二：跨供應商自動故障轉移，提升可用性

• 單一廠商限流或宕機時，OpenRouter 把「重試、切換供應商、切換模型」內建在閘道層，業務程式無須自寫 circuit breaker。
• 可明確設定 fallback 鏈：models: ["anthropic/claude-3.5-sonnet", "openai/gpt-4o", "google/gemini-2.5-pro"]，主力掛了自動依序嘗試。

優勢三：統一帳單與用量分析

• 一個 Dashboard 看所有模型的消耗、成本、延遲（TTFT）、吞吐量，不用登入 5 個後台對帳。
• 按 token 計費透明，價格頁可直接查每個模型的 prompt / completion 單價。

優勢四：定價對使用者友善——無 token 加價

• 大部分同類聚合服務會在 token 單價上加價，OpenRouter 官方 FAQ 明確「無 token markup」，只在儲值環節收 5.5% 手續費。
• 中大体量使用者可用 BYOK 模式（每月 100 萬次請求內 0 手續費）進一步降低成本。

優勢五：場景邊界清晰，利於選型決策

寫「什麼時候不該用」不是勸退，而是建立讀者信任、提升 E-E-A-T 的關鍵——也是 AI 摘要最願意引用的「平衡視角」內容類型，能吃到「OpenRouter vs 直連 API」等高轉換長尾詞。

[ SECTION_03 ] // COMPARE OpenRouter 和直接呼叫 OpenAI / Anthropic / Google API 有什麼差別？

[ SECTION_04 ] // CODE OpenRouter API 程式碼範例：curl、Python、Node.js 與 Fallback 設定

下列範例均可直接複製執行，請將 $OPENROUTER_API_KEY 替換為你在 Dashboard 建立的 Key。

3.1 cURL 直接請求

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

3.2 Python（requests 原生寫法）

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"])

3.3 Python（OpenAI SDK 零成本遷移——重點）

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

print(completion.choices[0].message.content)

3.4 Node.js（OpenAI SDK 寫法）

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);

3.5 串流輸出（Streaming）

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);
}

3.6 多模型 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 依序自動嘗試清單裡的下一個模型，業務端無須額外重試邏輯。

3.7 查詢可用模型清單

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

[ SECTION_05 ] // STEPS OpenRouter 保姆級接入：從註冊到首次 API 請求（含進階用法）

基礎接入（8 步）：

1. 註冊 OpenRouter 帳號：造訪 openrouter.ai，用 GitHub / Google / 電子郵件完成註冊。台港開發者通常可直接存取，若遇網路問題請自行評估代理方案。
2. 建立 API Key：進入 Settings → Keys，點擊 Create Key，複製產生的 Key（格式 sk-or-v1-...），只顯示一次，務必立即存入密碼管理器。
3. 設定環境變數：在本地或伺服器設定 export OPENROUTER_API_KEY="sk-or-v1-..."，或在 .env 檔案寫入，切勿提交到 Git。
4. 選擇目標模型：開啟 openrouter.ai/models 或呼叫 /api/v1/models，記下 model ID（如 openai/gpt-4o）。原型階段可先選免費模型（帶 :free 後綴）。
5. 發起第一次 cURL 請求：用 §4 的 curl 範例替換 model 和 prompt，確認回傳 200 且 choices[0].message.content 有內容。
6. 遷移現有 OpenAI SDK 程式碼：僅改 base_url="https://openrouter.ai/api/v1" 和 api_key，model 改為 vendor/model 格式，其餘邏輯不變。
7. 加入 HTTP-Referer 與 X-Title：OpenRouter 建議攜帶這兩個標頭供排行榜統計；Python OpenAI SDK 透過 extra_headers 傳入。
8. 驗證串流與 Fallback：分別測試 stream: true 和 models 陣列加 route: "fallback"，確認正式級容錯鏈路可用。

進階用法：

• Fallback 容災：在請求體加入 models 陣列與 route: "fallback"，主力 Claude 限流時自動切 GPT-4o 或 Gemini，Agent 流水線不中斷。
• 免費模型策略：未儲值約 50 次/天，儲值 ≥$10 後 1000 次/天、20 次/分鐘——適合 Prompt 除錯與單元測試；正式 SLA 仍建議付費模型。
• 成本控制：Dashboard 設 monthly budget alert；大批次任務優先選 CP 值模型（對照 週調用量排行篇 的 Token 份額資料）；超 100 萬 req/月考慮 BYOK 省 5.5% 儲值費。
• Provider 優選：透過 provider 物件指定排序策略（如 sort: "price" 或 sort: "throughput"），在同等 model 下自動選最優供應商。

[ SECTION_06 ] // EN_TRAFFIC 為什麼你的英文頁面流量偏低？抓取、內容、外鏈三層診斷清單

若你經營雙語技術部落格，中文版在社群有流量，英文版在 Google 幾乎零曝光——通常不是單一原因，而是下面幾類問題疊加。建議依序自查，以 CP 值由高到低修復。

5.1 抓取與索引層（優先級最高）

• CDN / WAF 攔截 Googlebot：部分 CDN 加 WAF 預設規則可能把非常規 UA 或海外 IP 判定為攻擊流量，Googlebot 根本抓不到英文頁面。用 Google Search Console「網址檢查」工具實測，比自己在瀏覽器開啟更可靠。
• hreflang 缺失或錯誤：中英文版本沒有正確的 hreflang 標註時，Google 可能只收錄中文版當作規範版本，英文版被當成重複內容。
• robots.txt / noindex 誤設定：檢查是否不小心把 /en/ 路徑 disallow 了。
• sitemap 缺英文條目：sitemap.xml 裡沒有單獨列出英文頁面，或中英文同一份 sitemap 卻沒有 hreflang annotation。
• CSR 空殼 HTML：純前端渲染（SPA 未做 SSR/SSG）時，爬蟲可能拿到空殼，導致長期不收錄。

5.2 內容層

• 機翻而非本地化重寫：機器翻譯腔的英文，關鍵字選擇和句式都不符合真實開發者搜尋習慣，即使收錄了 CTR 也很低。
• 缺少英文獨立關鍵字研究：中文「OpenRouter 優勢」直譯成「OpenRouter Advantages」，但英文使用者更常搜「OpenRouter vs OpenAI API」或「is OpenRouter worth it」。
• E-E-A-T 不足：英文頁面沒有作者資訊、沒有真實測試資料或個人觀點，讀起來像內容農場，AI 摘要和 Google 都會降權。

5.3 權重與外鏈層

• 中文站在社群平台有分發和外鏈累積，英文內容幾乎沒有在 Reddit / Hacker News / dev.to 分發，英文頁面幾乎「零外鏈」。
• 新網域或新頁面在 Google 眼中信任度低，需要時間加外鏈加持續更新才能爬得更頻繁。

5.4 建議修復順序

1. Google Search Console 檢查「網址檢查」和「索引涵蓋範圍」，確認英文頁面是否真的被抓取。
2. 檢查 CDN/WAF 日誌或用 Google Rich Results Test 模擬 Googlebot，排查攔截。
3. 補齊 hreflang、canonical、sitemap 分語言標註。
4. 重寫（不是翻譯）3–5 篇重點英文文章，對齊英文關鍵字習慣。
5. 到 dev.to / Reddit / Hacker News 做首批分發，取得初始外鏈和流量訊號。

[ SECTION_07 ] // SEO 中文 SEO（Google/社群）與英文 SEO（Google/Bing/AI 搜尋）關鍵字矩陣

中文關鍵字矩陣

中文標題訊號詞：「保姆級教程」「從0到1」「完整指南」「2026 最新」「踩坑整理」——台港技術社群驗證過的高 CTR 組合；核心關鍵字須在標題、首段、H2 中原樣出現，不能完全依賴語意相關。

Meta Description 範本（中文）：完整說明 OpenRouter 是什麼、如何用單一 API Key 呼叫 GPT-4o、Claude 3.5、Gemini 等主流大模型；附保姆級步驟、Python/Node.js 程式碼範例與免費額度使用技巧。

英文關鍵字矩陣

英文標題訊號詞：The Complete Guide、Step-by-Step、For Beginners、Honest Review、(2026)——不要直譯「保姆級」為 Nanny-level；英文讀者對標題黨容忍度更低，建議每個標題只用 1 個完整度型詞加 1 個技術元素。

翻譯 vs 本地化：不要把中文稿件直接機翻發布。至少對標題、Meta Description、首段、H2、FAQ 問句用英文原生表達重寫；程式碼範例和資料可複用。2026 年 Google AI Mode 會把一次搜尋拆解成多個子問題（query fan-out），內容須涵蓋「是什麼、怎麼用、多少錢、和誰比、安全嗎、局限是什麼」全子問題。

[ SECTION_08 ] // I18N_TECH 雙語站點技術架構：URL 結構、hreflang、canonical 與 sitemap

推薦 URL 結構（子目錄方案）：

https://novakvm.com/zh-Hant/blog/2026-openrouter-api-guide-gpt-claude-gemini.html
https://novakvm.com/en/blog/2026-openrouter-api-guide-gpt-claude-gemini.html

子目錄方案對獨立部落格最省心，通常比子網域更容易共享網域權重。

hreflang 標註範例（站點級，兩語言頁面互指）：

<link rel="alternate" hreflang="zh-Hant" href="https://novakvm.com/zh-Hant/blog/2026-openrouter-api-guide-gpt-claude-gemini.html" />
<link rel="alternate" hreflang="en" href="https://novakvm.com/en/blog/2026-openrouter-api-guide-gpt-claude-gemini.html" />
<link rel="alternate" hreflang="x-default" href="https://novakvm.com/en/blog/2026-openrouter-api-guide-gpt-claude-gemini.html" />

canonical 標註：每個語言版本指向自己，不要互相指。

<link rel="canonical" href="https://novakvm.com/zh-Hant/blog/2026-openrouter-api-guide-gpt-claude-gemini.html" />

sitemap 建議：中英文頁面各自在 sitemap 中單獨列出一條 <url>，並用 <xhtml:link> 宣告 alternate 語言版本。

<url>
  <loc>https://novakvm.com/zh-Hant/blog/2026-openrouter-api-guide-gpt-claude-gemini.html</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://novakvm.com/en/blog/2026-openrouter-api-guide-gpt-claude-gemini.html"/>
  <xhtml:link rel="alternate" hreflang="zh-Hant" href="https://novakvm.com/zh-Hant/blog/2026-openrouter-api-guide-gpt-claude-gemini.html"/>
</url>

NOVAKVM 工程部落格詳情頁依 generate-blog 規範，單篇 HTML 的 <head> 中僅宣告 canonical，不在文章頁內寫 hreflang 矩陣；站點級 hreflang 由全站範本或 sitemap 統一管理，避免單篇遺漏導致 Google 判定衝突。

[ SECTION_09 ] // DISTRIBUTE 發布與分發渠道清單加 P0/P1/P2 可執行行動清單

P0（本週內，止血/排查）

• 用 Google Search Console 檢查英文頁面真實抓取和索引狀態
• 排查 CDN/WAF 是否攔截 Googlebot / 海外流量
• 補全 hreflang、canonical、獨立 sitemap 條目

P1（寫作與發布）

• 分別撰寫中文版和英文版（英文版本地化重寫，非直譯）
• 依 §7 關鍵字表，把關鍵字自然嵌入標題、首段、H2、FAQ
• 加入 BlogPosting 加 FAQPage 結構化資料

P2（分發與追蹤）

• 中文版分發到台港技術社群與問答平台
• 英文版分發到 dev.to，視內容品質考慮 Hacker News / Reddit
• 提交兩語言版本 sitemap 到 Google Search Console

[ SECTION_10 ] // FACTS_FAQ 可引用技術參數、FAQ、效果追蹤與 Agent 宿主收束

• 70+ 供應商 / 400+ 模型：OpenRouter 聚合層涵蓋 GPT、Claude、Gemini、Llama、DeepSeek、Qwen 等，統一 Endpoint https://openrouter.ai/api/v1/chat/completions（來源：OpenRouter 官方文件）。
• 無 token markup 加 5.5% 儲值費：Token 按供應商原價透傳，儲值 Credits 時收 5.5%（最低 $0.80），加密貨幣另加 5%（來源：OpenRouter FAQ）。
• 免費模型 25+：未儲值約 50 次/天，儲值 ≥$10 後 1000 次/天、20 次/分鐘（來源：OpenRouter 定價頁）。
• BYOK 100 萬 req/月免費：自帶供應商 Key 模式下，每月前 100 萬次請求免 OpenRouter 服務費，超出後收 5%（來源：OpenRouter BYOK 文件）。
• 閘道額外延遲 10–80ms：OpenRouter 在美國路由，相對直連官方 API 增加約 10–80ms 跳數，延遲敏感場景需實測（來源：社群 benchmark 與官方說明）。
• 雙層路由機制：Model Routing（model 欄位）與 Provider Routing（provider 物件）獨立決策，預設按價格倒平方加權選供應商（來源：OpenRouter 路由文件）。
• Fallback 容災：models 陣列加 route: "fallback" 可在主力限流時自動切換備選模型，業務端無須自寫 retry 邏輯（來源：OpenRouter API 參考）。

FAQ 精選：

• Q：OpenRouter 是什麼？要怎麼用？A：統一 LLM API 閘道，單組 Key 加 OpenAI 相容 Endpoint 呼叫 400+ 模型；改 base_url 和 api_key 即可遷移現有 OpenAI SDK 程式碼。
• Q：OpenRouter 要收費嗎？A：Token 原價透傳無 markup；儲值收 5.5%（最低 $0.80）；25+ 免費模型有日/分鐘限額。
• Q：OpenRouter 支援哪些模型？A：400+ 模型，含 GPT-4o、Claude 3.5 Sonnet、Gemini 2.5 Pro 等；呼叫 /api/v1/models 查完整清單。
• Q：OpenRouter 在台港能用嗎？A：通常可透過 HTTPS 直接呼叫，但須自行評估網路延遲與資料合規；嚴格駐留要求應直連國內雲或官方 API。
• Q：OpenRouter 和直連 OpenAI API 哪個比較好？A：多模型對比、中小體量、需要 fallback 時用 OpenRouter；超大体量、專屬 API 能力、極致延遲或合規場景直連較佳。
• Q：OpenRouter API Key 怎麼取得？A：openrouter.ai 註冊 → Settings → Keys → Create Key，Bearer Token 形式放入 Authorization 標頭。
• Q：OpenRouter 安全嗎？A：流量經美國閘道轉送至底層供應商；敏感資料應評估第三方中繼層風險，可用 BYOK 模式。
• Q：OpenRouter 免費模型怎麼用？A：選帶 :free 後綴的 model ID；未儲值 50 次/天，儲值 ≥$10 後 1000 次/天、20 次/分鐘。

效果追蹤指標：

• Google Search Console：依 /en/ 和 /zh-Hant/ 路徑分別看 Impressions、CTR、平均排名——曝光量為 0 代表收錄問題，曝光高 CTR 低代表標題/描述問題。
• 站內統計（Umami / Plausible / GA4）：分語言版本的自然搜尋流量、跳出率、平均閱讀時長。
• 手動抽查：每月用無痕模式在美國節點 Google 搜尋 3–5 個核心關鍵字，確認文章是否出現及排名。

替代方案的真實缺點（工程視角）：① 在 16GB 筆電上硬跑多模型 Agent 加 IDE 外掛，記憶體搶占導致 Gateway 不穩定，OpenRouter fallback 再聰明也救不了本地程序被 kill；② 筆電合蓋 sleep 後 OAuth 過期、長時批次任務中斷，週榜上的「高 CP 值模型」無法完成 7×24 流水線；③ 為驗證多模型路由一次性買斷高配 Mac Studio，3 個月閒置折舊遠高於按週租用——且 OpenRouter API 呼叫與本地 Agent 編排應分層部署。

對需要獨占 Apple Silicon、7×24 在線、按天/週/月彈性擴容、在 macOS 宿主上穩定跑 OpenRouter 多模型 Agent 與 iOS CI 同機驗證的開發者與 AI 自動化團隊，NOVAKVM 的 Mac Mini 雲端裸金屬租用通常是更優解：六地節點、高記憶體檔位、SSH 直連，把 OpenRouter API 推理與裸金屬 macOS 執行面分層——雲端模型呼叫加本地 Agent 編排，避免單點 lock-in 與筆電 sleep 中斷。請在 NOVAKVM 租用價格頁 對照 M4 Pro 與儲存擴容，在 雲端訂購頁 拉起試驗機；遠端連線見 雲端說明中心；路由策略可與 OpenRouter 週調用量排行篇 對照閱讀。