TokenLab

核心指南

建立可靠的 TokenLab 整合

控管成本、重試機制、API 金鑰與請求紀錄

良好的整合應能讓價格與模型選擇透明化、在一般網路故障中保持穩定,且絕不在瀏覽器中暴露 API 金鑰。以下實踐適用於 chat、image、video、audio 以及其他 TokenLab API。

選擇具備最新數據的模型

模型名稱、功能與價格會隨時變動。請閱讀 Models API 或模型頁面,而非在程式碼或文件中保留永久列表。

針對新的使用案例:

  1. 根據產品所需的功能篩選模型。
  2. 比較它們目前的 TokenLab 價格。
  3. 使用具代表性的使用者請求進行小規模測試。
  4. 在每個請求中明確指定模型 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。

本頁內容