模型發現

使用模型頁面或模型 API 來檢視可用的文字模型。模型中繼資料包含供應商、服務提供商、模態、上下文長度、支援的 API 家族、支援的能力、可用性、帳號層級限制與積分定價。

端點： GET /v1/models 用途：列出當前帳號可用的模型。

複製curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

能力矩陣

API 家族相容性矩陣

驗證

每個 API 請求都使用 bearer token。請將密鑰儲存在伺服器端環境變數中，在團隊存取權限變更時輪替，並記錄請求 ID 以供除錯。

密鑰安全建議

1. 將 API 密鑰保存在伺服器上。切勿在瀏覽器或行動用戶端程式碼中暴露密鑰。
2. 為開發、預備、生產與第三方整合使用不同的密鑰。
3. 在可用時依環境、服務、客戶或租戶為密鑰設定範圍。
4. 在員工離職、供應商存取權限變更或疑似洩漏後輪替密鑰。
5. 將密鑰儲存在密鑰管理器或環境變數中，而非原始碼中。

使用控制台

BasicRouter 控制台是 API 存取、模型可用性、路由策略、使用量可見性與帳單管理的營運控制平面。它為帳號管理員提供密鑰、模型、請求、積分與帳號層級控制的集中檢視，用於生產模型流量。

管理 API 密鑰

從控制台建立、輪替、撤銷與標記 API 密鑰。為開發、預備、生產與個別服務使用不同的密鑰，以便使用量可被稽核並依環境或應用隔離。

模型列表

使用模型頁面檢視帳號可用的模型。每個模型項目可能包含供應商、服務提供商、模態、支援的 API 家族、上下文長度、能力旗標、可用性狀態與定價資訊。

對於生產應用，在啟用流量前請驗證模型能力。部分參數與功能視模型而定，可能無法在所有 API 家族中支援。

使用量與日誌

使用量與日誌檢視提供 API 流量的營運可見性。團隊可以檢視請求量、選定的模型、解析的路由目標、積分消耗、延遲、錯誤碼與請求 ID。

• 疑難排解失敗的請求。
• 識別高成本工作負載。
• 比較跨應用與環境的模型使用量。
• 驗證路由與備援行為。
• 調查延遲或提供商可用性問題。
• 聯繫支援時提供請求 ID。

每個 API 回應包含或暴露 BasicRouter 請求 ID。請將此 ID 儲存在您的應用日誌中，以提升生產除錯與支援升級效率。

備援

備援是 BasicRouter 的韌性機制。當主要模型或路由策略失敗時，系統會自動切換到備援模型以繼續處理請求。這讓您的應用保持回應能力並將服務中斷風險降至最低。

為何備援很重要

在生產環境中，模型服務可能遇到許多無法預測的問題：

• 模型服務故障：上游 API 暫時不可用或逾時。
• 效能波動：模型高負載導致回應緩慢或失敗。
• 路由失敗：智慧路由選擇的所有候選模型都不可用。

備援透過提供可靠的備援路徑來保持您的應用可用。

核心優勢

全域備援模型設定

BasicRouter 支援從控制台後端設定全域備援模型。所有請求在失敗時自動使用此模型作為備援。

如何設定：

1. 前往 BasicRouter 策略設定頁面。
2. 找到預設備援模型設定。
3. 從下拉清單中選擇您的全域備援模型。
4. 儲存設定以立即套用。

全域設定的優勢：

• 無需程式碼變更：設定一次即全域套用，無需在每個請求上重複設定。
• 集中管理：在一處管理備援策略，便於調整與監控。
• 簡化維護：降低程式碼複雜度與設定錯誤的機率。
• 彈性覆寫：請求層級備援設定具有優先權，可為特定情境覆寫全域設定。

請求層級備援設定

對於特定業務情境，您可以在個別請求上指定備援模型以覆寫全域設定。

使用 router.fallBackModels 參數指定備援模型：

複製{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

優先權規則

當存在多個備援設定時，優先權從高到低為：

1. 請求層級 router.fallBackModels：在個別請求上指定的備援模型。
2. 全域預設備援模型：在控制台設定的全域備援模型。
3. 無備援：若兩者皆未設定，請求失敗時回傳錯誤。

帳號管理

依帳號類型而定，控制台可能包含帳號層級模型啟用、經銷商或分銷商控制、帳單設定與存取設定。管理員可使用這些控制，使模型存取、使用量可見性與帳單責任與應用、客戶帳號或業務單位一致。

生產營運檢查清單

帳單與積分

BasicRouter 在文字、圖像、影片與其他支援的模型工作負載中使用基於積分的計費模型。積分為多模型與多提供商使用量提供統一單位，讓團隊能跨模態與 API 家族一致地管理消耗。

詳細的模型定價可在模型頁面或透過模型中繼資料 API 取得。定價可能因模型、提供商、模態、解析度、token 類型、輸出長度、任務時長、帳號類型與商業協議而異。

儲值與錢包

帳號可新增按量付費錢包積分以獲得彈性使用量。除非帳號套用了自訂帳單規則，否則錢包積分會在月費方案積分與資源包消耗完畢後使用。

除非適用的商業條款另有規定，錢包積分不會過期。儲值按量付費錢包時會收取服務費。

月費方案與資源包

每個使用者或帳號可選擇一個有效的月費方案。月費方案為計費週期提供定義的使用量容量、商業條款與帳號層級存取設定。

使用者也可購買多個資源包以獲得額外使用量容量。資源包可將承諾使用量與按量付費錢包餘額分開，適用於大量文字、圖像、影片或專用工作負載使用量。

扣費順序

除非設定了自訂帳單規則，否則積分按以下順序扣費：

對於具有自訂商業條款的帳號，扣費順序、過期規則、包含的使用量與定價可能不同。帳號專屬規則會顯示在控制台或透過商業協議提供。

自訂定價

可為每個使用者或帳號自訂定價。企業客戶、經銷商帳號、分銷商帳號與高用量客戶可能符合自訂定價資格。請聯繫業務團隊取得報價。

自訂定價可依帳號、模型、提供商、模態、地區、使用量或商業協議設定。啟用自訂定價時，控制台與帳單 API 會在可用時反映帳號專屬定價與扣費規則。

定價單位

不同模型模態使用不同的計量單位。BasicRouter 依據模型的定價規則將這些單位轉換為積分。

定價單位可能因模型而異。在生產環境中啟用模型前，請務必參考模型詳情頁或定價中繼資料。

使用量歸因

BasicRouter 使用量可依帳號、API 密鑰、模型、模態或時間範圍檢視。這讓團隊能將成本歸因於應用、環境、客戶或內部業務單位。

積分餘額

查看您帳號中可用的積分數量。餘額分為三個按順序扣費的錢包：月費方案積分、購買的資源包與按量付費錢包。另提供合併資源總額（月費方案 + 資源包，不含按量付費），以便將包含使用量與儲值支出分開追蹤。

若要以程式方式取得此資訊，請參見 API 參考中的 GET /v1/billing/balance。

使用量詳情

檢視個別使用量記錄的分頁時間序列清單，用於報告、監控與內部成本分攤。每筆記錄顯示模型、模型類型（文字、圖像或影片）、扣減的積分，以及每筆扣費從哪個錢包提取的明細。結果可篩選至特定時間範圍。

若要以程式方式取得此資訊，請參見 API 參考中的 GET /v1/usage。

交易紀錄

使用交易紀錄檢視積分變動，包含儲值、方案分配、資源包授予、使用量扣費、調整與管理修正。

若要以程式方式取得此資訊，請參見 API 參考中的 GET /v1/billing/transactions。

失敗請求與退款

驗證錯誤、身分驗證錯誤與權限錯誤通常不予計費，因為未發生模型執行。到達上游模型或產生部分輸出的請求可能會消耗積分，視模型、提供商與回應狀態而定。

對於非同步圖像與影片任務，計費行為取決於任務是否已被接受、啟動、完成、失敗或取消。任務詳情回應在已消耗積分時包含使用量資訊。

儲值、月費方案、資源包與已消耗積分不可退費，除非適用的商業協議另有規定或法律要求。

營運

錯誤

BasicRouter 回傳穩定的錯誤代碼，方便應用程式一致地處理重試、後援、帳務問題與除錯。

相容供應商的端點會盡可能保留原始 API 家族的錯誤結構。BasicRouter 原生端點使用 BasicRouter 錯誤物件。

HTTP 狀態與錯誤代碼對應

常見錯誤代碼