功能特色

• 🤖 多端點對話：同時支援 OpenAI Chat Completions、Anthropic Messages、OpenAI Responses 三種相容端點
• 🖼️ 多模態生成：除文字對話外，支援圖像生成、影片生成（文生／圖生／首尾幀／參考素材）非同步任務
• 🔍 模型與帳戶查詢：列出可用模型、查看模型詳情、帳戶餘額、用量扣費明細、儲值交易紀錄
• 🔑 以 header 傳遞金鑰：每次呼叫皆從請求 header 讀取 API 金鑰，同一個部署可供多個不同帳號共用，伺服器不落盤、不快取任何金鑰

快速開始

在 Claude Code 中使用（建議）。加上 -s user 以註冊在 user scope（所有專案皆可使用）。

步驟 1：新增連線

複製claude mcp add --transport http basicrouter https://api.basicrouter.ai/mcp \
  --header "X-Basicrouter-Api-Key: <您的 BasicRouter API key>" \
  -s user

步驟 2：確認連線

複製claude mcp list          # 應顯示 ✓ Connected
claude mcp get basicrouter  # 應顯示 Scope: User config (available in all your projects)

步驟 3：開始使用

在 Claude 中可以這樣提問：

• 「用 BasicRouter 呼叫 claude-sonnet-5，寫一首關於秋天的詩」
• 「列出我 BasicRouter 帳戶中可用的模型」
• 「查一下我 BasicRouter 的餘額與近期用量」
• 「用 BasicRouter 生成一張賽博龐克風格的城市夜景圖」

Claude 會自動呼叫對應的 MCP 工具並回傳結果。

在 Claude Desktop 中使用

在 mcpServers 區塊中新增設定：

複製{
  "mcpServers": {
    "basicrouter": {
      "type": "http",
      "url": "https://api.basicrouter.ai/mcp",
      "headers": {
        "X-Basicrouter-Api-Key": "<您的 BasicRouter API key>"
      }
    }
  }
}

在 Codex CLI 中使用

建議寫法：用 env_http_headers 從環境變數讀取金鑰

先在 shell 中匯出環境變數：

複製export BASICROUTER_API_KEY=<您的 BasicRouter API key>

然後在 ~/.codex/config.toml 中：

複製[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
env_http_headers = { "X-Basicrouter-Api-Key" = "BASICROUTER_API_KEY" }

備選寫法：用 http_headers 把金鑰直接寫入設定（不想單獨管理環境變數時可以把金鑰靜態寫死，請注意金鑰會以明文儲存在設定檔中）：

複製[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
http_headers = { "X-Basicrouter-Api-Key" = "<您的 BasicRouter API key>" }

若透過 Codex 設定介面新增：

• 類型：HTTP / Streamable HTTP
• 名稱：basicrouter
• URL：https://api.basicrouter.ai/mcp
• Header 名稱：X-Basicrouter-Api-Key
• Header 值：您的 BasicRouter API key

驗證連線

啟動 Codex CLI 後，/mcp 指令可以列出已設定的 MCP server 及其連線狀態，確認連線已正常載入即可。使用方式與 Claude 一致——Codex 會自動選用對應的工具。

如果設定檔中已有其他 MCP server，依同一層級追加即可。修改完成後請完全退出 Claude Desktop 再重新開啟。

工具說明

這個 MCP server 提供了 14 個工具。依用途分五組：

一、對話端點

1. chat_completion — Chat Completions

發送一次對話請求，回傳模型完整回覆（不支援串流）。除純文字外，還支援傳入圖片和影片做多模態理解（需模型支援對應 vision/video 能力，可先 list_models 查看 input_modalities）——把訊息的 content 從字串改為內容塊陣列，混合 text 與 image_url / video_url。

多模態輸入（text / image / video）

圖片輸入(URL 方式)：

複製{"role": "user", "content": [
  {"type": "text", "text": "這張圖片裡有什麼？"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

圖片輸入（Base64 方式）：

複製{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64_STRING>"}}

支援的圖片格式：PNG、JPEG、GIF（僅首幀）、WebP。單張圖片大小限制 20MB。

注意：大圖片的 Base64 編碼字串非常長，可能因請求體過大而失敗，建議優先使用 URL 方式傳入。

detail 參數(可選，寫在 image_url 物件上)控制圖片處理精度："auto"（預設，模型按圖片大小自動決定）/ "low"（512x512 縮圖，快、省，適合簡單分類）/ "high"（全解析度，適合讀小字、摳細節）。一條訊息的 content 陣列裡可放多個 image_url 塊傳入多張圖片。

影片輸入（URL 方式）：

複製{"role": "user", "content": [
  {"type": "text", "text": "描述這個影片裡的內容。"},
  {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}
]}

影片輸入（Base64 方式）：

複製{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_STRING>"}}

BasicRouter 上支援 video 輸入的模型包括 Qwen、Doubao（dola-seed）、Kimi、MiniMax 等系列的部分模型，具體以 list_models 回傳的 input_modalities 為準。OpenAI 官方 Chat Completions 標準不原生支援影片，但 BasicRouter 閘道透過

複製{"type": "video_url", "video_url": {"url": "..."}}

擴充格式支援影片輸入，該格式與 OpenRouter、NVIDIA NIM、vLLM 等平台的 video_url 格式一致。

2. create_message — Anthropic Messages 相容

呼叫 Anthropic Messages 相容介面（不支援串流）。內容塊支援 text、image、tool_use、tool_result、thinking、redacted_thinking。圖片透過

複製{"type": "image", "source": {...}}

內容塊傳入。

多模態輸入（text / image / video）

圖片輸入支援三種 source 類型：

1. Base64 編碼(注意：data 欄位為純 Base64 字串，不含 data: 前綴)，media_type 支援 image/jpeg、image/png、image/gif、image/webp：

複製{"type": "image", "source": {
  "type": "base64",
  "media_type": "image/jpeg",
  "data": "<BASE64_STRING>"
}}

2. URL 參照：

複製{"type": "image", "source": {
  "type": "url",
  "url": "https://example.com/image.jpg"
}}

3. File ID（需先透過 Files API 以 purpose="vision" 上傳圖片取得 file_id）：

複製{"type": "image", "source": {
  "type": "file",
  "file_id": "<file_id>"
}}

一條訊息的 content 陣列裡可放多個 image 塊傳入多張圖片。

注意：大圖片的 Base64 編碼字串非常長，可能因請求體過大而失敗，建議優先使用 URL 方式傳入。

影片輸入：Anthropic Messages API 不支援影片檔案。如需影片理解，先用 ffmpeg 等工具抽取關鍵幀，把每幀作為 image 內容塊傳入。BasicRouter 上支援影片輸入的模型（可透過 list_models 查看 input_modalities 中是否包含 video）建議改用 chat_completion 或 create_response 介面以原生支援影片。

3. create_response — OpenAI Responses 相容

用 input 代替 messages，用 instructions 代替系統訊息，用 text.format 代替 response_format。除純文字外，還支援傳入圖片和影片做多模態理解（需模型支援對應 vision/video 能力，可先 list_models 查看 input_modalities）——把 input 設為訊息物件陣列，content 用內容塊陣列，混合文字與圖片/影片。

多模態輸入（text / image / video）

注意：Responses API 的內容塊類型用 input_text / input_image / input_video（而非 Chat Completions 的 text / image_url / video_url），且 image_url / video_url 直接為字串而非巢狀物件。

圖片輸入(URL 方式)：

複製[{"role": "user", "content": [
  {"type": "input_text", "text": "這張圖片裡有什麼？"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

圖片輸入（Base64 方式）：

複製{"type": "input_image", "image_url": "data:image/jpeg;base64,<BASE64_STRING>"}

支援的圖片格式：PNG、JPEG、GIF（僅首幀）、WebP。單張圖片大小限制 20MB。

注意：大圖片的 Base64 編碼字串非常長，可能因請求體過大而失敗，建議優先使用 URL 方式傳入。

圖片輸入(File ID 方式)：

複製{"type": "input_image", "file_id": "<file_id>"}

，file_id 需透過 Files API 以 purpose="vision" 上傳圖片取得。

detail 參數(可選，寫在 input_image 物件上)控制圖片處理精度："auto"（預設）/ "low"（512x512 縮圖，快、省）/ "high"（全解析度，讀小字、摳細節）/ "original"（原始解析度，僅部分新模型支援）。一條訊息的 content 陣列裡可放多個 input_image 塊傳入多張圖片。

影片輸入（URL 方式）：

複製[{"role": "user", "content": [
  {"type": "input_text", "text": "描述這個影片裡的內容。"},
  {"type": "input_video", "video_url": "https://example.com/video.mp4"}
]}]

影片輸入（Base64 方式）：

複製{"type": "input_video", "video_url": "data:video/mp4;base64,<BASE64_STRING>"}

影片輸入（File ID 方式）：

複製{"type": "input_video", "file_id": "<file_id>"}

BasicRouter 上支援 video 輸入的模型包括 Qwen、Doubao（dola-seed）、Kimi、MiniMax 等系列的部分模型，具體以 list_models 回傳的 input_modalities 為準。OpenAI 官方 Responses API 標準不原生支援影片，但 BasicRouter 閘道透過

複製{"type": "input_video", "video_url": "..."}

擴充格式支援影片輸入，該格式與 BytePlus/Volcengine 等平台的 input_video 格式一致。

二、模型與帳戶查詢

4. list_models — 列出可用模型

回傳目前帳戶可用模型，含廠商、模態、支援的能力與定價等中繼資料。無參數。列表每項含 price_tiers 價格檔位，回傳的是當前呼叫方的有效計費價，與實際扣費一致（見價格檔位欄位說明）。

5. get_model — 查詢單個模型詳情

出參含 price_tiers 價格檔位（見價格檔位欄位說明）；模型不存在時回傳 404，不含價格欄位。

6. get_balance — 查詢帳戶餘額

回傳目前帳戶的用量與餘額。無參數。

三、帳單流水

7. list_usage — 模型呼叫扣費明細

分頁查詢模型呼叫計費詳情，依訂單建立時間倒序。僅含正常用量扣費，不含儲值／調整。

8. list_transactions — 儲值／方案交易紀錄

分頁查詢已支付的儲值 / 方案購買交易紀錄，依建立時間倒序。

四、圖像生成

9. list_image_models — 列出圖像模型

回傳支援的圖像生成模型，含解析度、寬高比、單次最大圖片數（maxCount）、最大參考圖片數（fileMax）。無參數。呼叫圖像生成前請先查詢，只能傳入規格中公布的值。列表每項含 priceTiers 價格檔位（見價格檔位欄位說明）。

10. create_image_generation — 提交圖像生成任務

非同步提交，立即回傳 taskId，會消耗帳戶額度。

11. get_image_generation — 輪詢圖像任務

回傳：status 為 pending（進行中）/ success（成功）/ failed（失敗）；images 是圖片 URL 陣列的 JSON 字串；text 攜帶模型附加的描述（如 Gemini 多模態輸出）。

五、影片生成

12. list_video_models — 列出影片模型

回傳支援的影片生成模型，含 allowedVideoTypes、時長範圍（videoDurationMin/Max）、解析度、寬高比、參考素材上限（fileMax）。無參數。呼叫影片生成前請先查詢。列表每項含 priceTiers 價格檔位（見價格檔位欄位說明）。

13. create_video_generation — 提交影片生成任務

非同步提交，立即回傳 taskId，會消耗帳戶額度。

video_type 含義：

14. get_video_generation — 輪詢影片任務

價格檔位欄位說明

list_models、get_model、list_image_models、list_video_models 這 4 個模型查詢工具的出參會回傳當前呼叫方（API Key 使用者）的有效計費價，與實際扣費完全一致，且回傳該模型的全部價格檔位。

欄位命名差異：list_models / get_model 沿用 OpenAI 風格下底線命名（price_tiers）；list_image_models / list_video_models 沿用 camelCase 命名（priceTiers）。兩者結構完全相同。

price_tiers / priceTiers 為陣列，每個元素是一個價格檔位：

三種模型型別共用同一結構，僅描述欄位填充不同，不適用欄位為 null：

價格含義：回傳的 inputPrice / outputPrice / cacheReadPrice / cacheWritePrice 等，是經價格鏈（chain）→ guidance → 基礎價逐級解析後，針對當前 API Key 使用者的最終計費單價，與實際扣費一致。呼叫方看到的單價會因自身所屬的定價鏈（reseller / distributor / 企業 / 使用者級設定）不同而不同。

實際扣費額 = 用量 ÷ quantity × 對應單價 × ratio。影片按秒計費時，實際扣費 = duration × outputPrice × ratio。

邊界與例外處理（唯讀介面不會因價格設定問題回傳 500）：

回應範例（list_models，文字模型）：

複製{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "display_name": "gpt-4o",
      "context_length": 128000,
      "description": "...",
      "price_tiers": [
        {
          "region": "GLOBAL",
          "bandMin": null,
          "bandMax": null,
          "resolution": null,
          "clarity": null,
          "unit": "token",
          "quantity": 1000,
          "description": "每千 token",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

回應範例（list_image_models，圖片模型，priceTiers 結構同上，unit 為 image）：

複製{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "每張",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

使用範例

範例 1：一次普通對話

提問：「用 BasicRouter 呼叫 claude-sonnet-5，問它 Python 的 GIL 是什麼」

AI 會呼叫 chat_completion，參數為：

複製{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "Python 的 GIL 是什麼？"}]
}

範例 2：用 Anthropic Messages 端點帶工具呼叫

提問：「用 BasicRouter 的 Messages 端點，讓模型自己決定要不要查天氣」

AI 會呼叫 create_message，傳入 tools 定義與 tool_choice，回應中會包含 tool_use 內容區塊。

範例 3：查可用模型

提問：「列出我 BasicRouter 帳戶中有哪些模型」

AI 會呼叫 list_models，回傳所有可用模型的 ID、廠商、模態、定價等資訊。

範例 4：查餘額與用量

提問：「查一下我 BasicRouter 這個月的用量明細」

AI 會呼叫 get_balance 查餘額，再呼叫 list_usage（帶 start_time 限定本月）查扣費明細。

範例 5：生成圖片

提問：「用 BasicRouter 生成一張賽博龐克風格的城市夜景圖」

AI 會先呼叫 list_image_models 查規格，再呼叫 create_image_generation 取得 taskId，最後輪詢 get_image_generation 取得圖片 URL。

範例 6：文生影片

提問：「用 BasicRouter 生成一段 5 秒的太空星雲影片」

AI 會先呼叫 list_video_models 查規格，再呼叫 create_video_generation（video_type=1，duration=5），取得 taskId 後輪詢 get_video_generation。

常見問題

呼叫工具時報「缺少 BasicRouter API Key」

• 使用 claude mcp add 時沒帶 --header，或金鑰寫錯了
• 直接編輯 JSON 設定時，headers 欄位名稱寫錯（應為 X-Basicrouter-Api-Key）
• 本機執行時未設定環境變數 BASICROUTER_API_KEY

呼叫工具報「BasicRouter 回傳 401 未授權」

API Key 本身不正確或已失效，請到 BasicRouter 控制台重新產生。

Claude 沒有呼叫 BasicRouter 工具怎麼辦？

• 用 claude mcp list 確認連線為 ✓ Connected
• 確認連線狀態：claude mcp get basicrouter
• 嘗試明確要求：「用 BasicRouter 的 chat_completion 工具呼叫 claude-sonnet-5 …」

圖像／影片生成一直 pending

• 圖像任務用 get_image_generation、影片任務用 get_video_generation 輪詢，請注意影片任務進行中時 status 是 "running" 不是 "pending"
• 生成需要時間，通常幾秒到幾十秒，影片更久
• 若帶了 callback_url，任務完成會主動回呼，不需要輪詢

list_image_models / list_video_models 報錯

這兩個工具本身不會消耗額度，報錯通常是金鑰或網路問題。請先確認 list_models 能正常回傳。

注意事項

• Header 名稱：MCP 用 X-Basicrouter-Api-Key 傳遞金鑰。
• 額度消耗：chat_completion / create_message / create_response / create_image_generation / create_video_generation 都會消耗帳戶額度，呼叫前可以先 get_balance 查看一下餘額。
• 先查規格再生成：圖像／影片生成的 model、resolution、ratio、count、duration、video_type 等參數只能傳入 list_image_models / list_video_models 公布的值，否則會報錯。
• 不支援串流：三個對話端點皆不支援串流回應，一次性回傳完整結果。
• 無狀態設計：每次請求皆為獨立，不保存對話資訊；多輪對話請靠 create_response 的 previous_response_id 或自行在 messages 中維護歷史紀錄。