核心指南
建立可靠的 TokenLab 整合
控管成本、重試機制、API 金鑰與請求紀錄
良好的整合應能讓價格與模型選擇透明化、在一般網路故障中保持穩定,且絕不在瀏覽器中暴露 API 金鑰。以下實踐適用於 chat、image、video、audio 以及其他 TokenLab API。
選擇具備最新數據的模型
模型名稱、功能與價格會隨時變動。請閱讀 Models API 或模型頁面,而非在程式碼或文件中保留永久列表。
針對新的使用案例:
- 根據產品所需的功能篩選模型。
- 比較它們目前的 TokenLab 價格。
- 使用具代表性的使用者請求進行小規模測試。
- 在每個請求中明確指定模型 ID。
請勿在未經通知的情況下切換模型。替換模型可能會改變輸出品質、價格、上下文長度、可用工具或媒體支援。
設定成本上限
對於文字模型,請將輸出限制在產品實際可用的長度內。參數名稱取決於 API 與模型,因此在發送 max_tokens 或 max_output_tokens 之前,請先查閱模型頁面。
較短的指令並不一定更好,但重複的上下文與樣板文字總是會增加輸入 token。請保持穩定的指令簡潔,並僅發送下一個回答所需的歷史紀錄。
對於 image、video、music、3D 與 Worlds 請求,成本通常取決於輸出數量、持續時間、解析度或其他媒體選項。當 API 提供估算值時,請在使用者確認昂貴的生成任務前顯示該預估費用。
串流長文字回應
串流(Streaming)會在答案產生時即時顯示,避免使用者等待完整回應。這並不會減少 token 成本。
如需包含客戶端設定與完成檢查的完整範例,請參閱 串流 (Streaming)。
請將斷線視為不完整的答案。不要將部分輸出呈現為已成功完成,也不要在可能導致二次副作用或重複收費的情況下自動重複請求。
僅在安全時進行重試
在收到 429 回應後,請根據 Retry-After 或 retry_after 進行重試。針對暫時性的 5xx 回應,使用短暫的指數退避(exponential backoff)是適當的。身份驗證、驗證、餘額與上下文長度錯誤需要應用程式或使用者進行調整;再次發送相同的請求無法解決這些問題。
請參閱 速率限制 以獲取遵守 Retry-After 並停用重複 SDK 重試的限制重試範例。
設定重試次數上限與總時間限制。對於媒體創作,請儲存回傳的 task ID。對於 Retry safely with an idempotency key 中列出的請求,請發送 Idempotency-Key,以確保逾時後的重試不會執行或對同一個請求重複收費。
將 API 金鑰保留在伺服器端
切勿將 TokenLab API 金鑰嵌入瀏覽器 JavaScript、行動應用程式套件、公開儲存庫或客戶端可見的日誌中。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
)請為開發、生產與獨立應用程式使用不同的 API 金鑰。僅賦予每個金鑰所需的模型存取權限與消費上限。若金鑰可能已外洩,請立即撤銷。
保留有用的請求紀錄
儲存能將使用者操作與使用量及支援紀錄連結起來的識別碼:
request_id(用於 API 請求)task_id(用於非同步生成)billing_transaction_id(若有回傳)- 模型 ID 與端點
- 您自己的使用者、專案或工作 ID
請勿記錄 API 金鑰、管理 token、完整的私有提示詞(prompts)、私有媒體或簽名 URL。Console 與 Management API 中的使用紀錄是計費金額的來源;僅憑模型回應的 token 數量可能無法反映最終收費。
為非同步工作進行設計
Image、video、music、3D 與 Worlds API 可能會在結果準備好之前就回傳。請儲存 task ID,輪詢 GET /v1/tasks/{id},並僅在狀態為 completed 或 failed 時停止。失敗的狀態查詢並不代表生成任務本身失敗。
請參閱 非同步任務與輪詢 以了解取消、逾時與重複請求的處理方式。
上線前檢查
- 使用您即將發布的確切模型與 API 格式執行具代表性的請求。
- 檢查成功與常見的錯誤回應。
- 確認產品中顯示的價格與目前的 TokenLab 價格一致。
- 確保重新整理、網路逾時與重複點擊的操作是安全的。
- 確保能夠將使用者可見的結果追溯回其 Request ID。