OpenRouter API 生產檢查清單

驗證 API 相容性與端點

使用標準的 OpenAI 相容端點以確保整合的穩定性。

主要端點是 POST /v1/chat/completions. 這負責處理聊天歷史的文字產生。另一個次要端點， GET /v1/models列出可用模型。您不需要嵌入或圖像生成端點即可進行純文字任務。許多開發者認為他們需要複雜的路由層。OpenRouter 透過暴露單一入口點簡化了這一點。您發送包含模型 ID 和系統提示的 JSON 負載。服務返回包含內容和使用數據的結構化 JSON。此設計符合官方 OpenAI SDK 的預期。您可以在不更改客戶端程式碼的情況下交換模型。只需在配置中更新模型 ID。確保您的客戶端支援最新的 JSON 架構。較舊版本可能會拒絕新參數。在部署到生產環境之前測試您的連接。驗證回應格式是否符合您的解析器。

設定認證與金鑰

產生後立即將 API 金鑰安全地儲存在環境變數中。

透過供應商儀表板產生金鑰。將其存放在安全的位置，切勿將其硬編碼至您的程式碼儲存庫中。透過以下方式傳遞： Authorization: Bearer <key> 標頭。每個金鑰都綁定到特定帳戶。如果您懷疑金鑰洩漏，可以進行輪換。某些供應商允許每個帳戶擁有多個金鑰。這允許您區分開發和生產流量。監控每個金鑰的使用情況以檢測異常。定期撤銷未使用的金鑰。為臨時腳本使用短生命週期的金鑰。這可以減少洩漏時的影響範圍。確保您的 SDK 版本支援 bearer token 驗證。較舊的程式庫可能需要不同的標頭格式。請檢查您特定 SDK 的文件。驗證金鑰是否有足夠的餘額。過期的金鑰會返回 401 錯誤。餘額為零的金鑰會返回 402 錯誤。在您的邏輯中區分這兩種狀態。

處理串流與 Token 使用量

啟用串流以降低延遲並獲得即時使用者回饋。

設定 stream: true 在您的請求主體中。伺服器發送一系列伺服器發送事件（SSE）。每個事件包含部分文字區塊。您必須組裝這些區塊以形成完整回應。最後一個區塊通常包含 token 使用統計數據。這使您能夠即時追蹤成本。如果不使用串流，您需要等待整個回應。這會顯著增加感知延遲。串流對於聊天介面至關重要。它創造了一種感覺響應迅速的打字效果。在串流期間要小心錯誤處理。如果連線中斷，您會失去當前區塊。重新連線邏輯應保留對話狀態。某些 SDK 自動處理串流。其他則需要手動事件監聽器。選擇適合您架構的方法。確保您的解析器處理不完整的 JSON 區塊。不要假設每個事件都是完整的物件。緩衝資料直到獲得有效結構。

監控速率限制與併發性

追蹤您的每分鐘請求數量，以避免服務中斷。

OpenRouter 對每個 API 金鑰實施嚴格的速率限制。超過這些限制會觸發 429 Too Many Requests 錯誤。您必須在重試邏輯中實現指數退避。並行請求也會計入您的限制。請檢查回應標頭以查看剩餘配額。某些供應商會直接公開這些標頭。其他供應商則需要您從錯誤中推斷限制。高並發性可能會耗盡您的連線池。確保您的客戶端有效管理連線。使用連線池以減少開銷。在高峰負載期間監控您的佇列深度。如果您達到限制，請在重試前等待。隨機化您的等待時間以避免雷擊問題。記錄所有速率限制事件以進行除錯。這有助於識別您使用模式中的規律。根據這些日誌調整您的並發設定。不要假設單一金鑰可以處理無限流量。如有必要，請將負載分佈到多個金鑰上。這需要仔細的狀態管理。確保每個金鑰在需要時保持其自己的上下文。

管理加密貨幣計費和充值

使用預付信用額度支付 token 使用量，無需月費。

使用加密貨幣充值您的帳戶。支援的網路包括 TRC20 上的 USDT 和 Base 上的 USDC。最低充值金額從 $20 起。較大金額適用贈送。$50 獲得 5% 額外贈送，$100 獲得 10%，$200 獲得 15%。信用額度永不過期。這非常適合長期專案。您僅為實際使用的 token 付費。錯誤與拒絕請求免費。這能保護您的預算免受意外成本影響。新帳戶可獲得 $0.50 用於測試。標準購買不退款。重複扣款將透過客服修正。確保您的錢包支援所需的網路。發送前請驗證合約地址。錯誤的網路可能導致資金損失。請定期檢查您的餘額。餘額過低可能會意外中斷服務。如果可能，請自動化充值。這可確保關鍵任務的持續可用性。

測試內容過濾器與拒絕機制

確認模型對無防護機制的提示詞反應符合預期。

Uncensored 模型仍可能應用硬性限制。請檢查特定內容類型的限制。使用已知的觸發短語進行測試。確保模型做出適當的響應。一些提供者出於法律原因保留過濾器。在依賴模型處理敏感數據之前，請驗證這些情況。在您的領域中測試邊界情況。發送通常會觸發拒絕的提示。觀察響應格式。它是返回拒絕原因，還是靜默生成內容？將這些行為記錄在您的集成測試中。這可防止生產環境中的意外情況。如果模型改變行為，請更新您的測試。通知團隊任何重大變化。一致性對於用戶信任至關重要。確保您的應用程序能優雅地處理拒絕。不要假設每個響應都是有效的。驗證輸出結構。檢查幻覺或格式錯誤。這確保了可靠的用戶體驗。

為免費請求實施錯誤處理

優雅地處理錯誤以維持流暢的用戶體驗。

網路錯誤、超時和伺服器錯誤可能會發生。請實作帶有指數退避的重試邏輯。區分暫時性錯誤和永久性錯誤。429 錯誤是暫時性的。等待並重試。400 錯誤是永久性的。檢查您的輸入資料。500 錯誤是伺服器端的。謹慎重試。記錄所有錯誤以進行除錯。包含請求載荷和回應主體。這有助於快速重現問題。不要向使用者暴露原始錯誤。將其格式化為使用者友善的訊息。謹慎處理串流錯誤。斷開事件串流連線。清理資源。確保您的應用程式不會洩漏記憶體。徹底測試錯誤情境。模擬網路中斷。模擬伺服器超時。驗證您的恢復邏輯是否運作。這可確保在惡劣條件下的可靠性。

使用 JSON 模式和工具調用進行擴展

使用結構化輸出以進行可靠的資料擷取和函式執行。

透過設定啟用 JSON 模式 response_format: {type: "json_object"}. 這可強制模型輸出有效的 JSON。適用於解析資料或產生設定檔。工具呼叫功能允許模型執行函數。在請求主體中定義您的工具。模型會自行決定何時呼叫這些工具。將結果回傳給模型，它可根據輸出產生最終回應。這為複雜任務建立了一個循環。請確保您的工具定義清晰，含糊的工具會導致錯誤的呼叫。在解析之前請驗證 JSON 輸出，這能防止程式碼中的執行階段錯誤。將工具呼叫用於資料擷取任務，可顯著提高準確性。請使用各種輸入格式進行測試，確保模型能處理邊緣情況。為您的團隊記錄可用的工具，這能確保專案間的使用一致性。

審查隱私與資料使用政策

了解供應商如何儲存和使用您的資料。

查看隱私政策中的數據保留詳情。某些供應商會將您的數據用於訓練。其他供應商則保持數據私密。如果這對您很重要，請確保您的數據不會用於模型改進。驗證加密標準。數據在傳輸中和靜態時都應進行加密。檢查是否存儲日誌。日誌可能包含您的提示詞。確保這些日誌是安全的。查看服務條款中的責任條款。了解生成內容的歸屬權。某些供應商聲稱對您輸出的權利。確保這符合您的需求。如果您不再使用該服務，請刪除帳戶。驗證您的數據是否已刪除。如有疑慮，請聯繫支持團隊。記錄您的隱私設置以供審計。這有助於符合內部政策。