了解 TokenLab HTTP 標頭與原生協議端點

協議端點決定有效負載結構描述

TokenLab 不會使用動態格式提示標頭（例如專有的 format-hint 標籤）在運行時指示回應結構描述。相反地，有效負載結構嚴格由所呼叫的端點決定。解析客戶端回應需要將請求路由至目標原生協議端點，而不是透過檢查回應標頭來判斷有效負載類型：

• Chat Completions (/v1/chat/completions)：使用相容於 OpenAI 的結構描述，返回 choices、message.content 以及 usage 區塊（prompt_tokens、completion_tokens、total_tokens）。
• Responses (/v1/responses)：遵循 OpenAI Responses API 格式，用於背景任務、伺服器工具和回應事件。
• Anthropic Messages (/v1/messages)：使用原生 Anthropic 結構描述（content 區塊、thinking 和 output_tokens）與 Anthropic Claude 模型進行互動。設定 Anthropic SDK 時，請將基礎 URL 設為 https://api.tokenlab.sh，且不包含 /v1 前綴。
• Gemini (/v1beta/models/:model:generateContent)：接受原生 Gemini 結構描述（contents、parts）並返回標準 Gemini REST candidate 物件。

在路由模型請求之前，請先透過呼叫 Get a Model（GET /v1/models/{model}）或查閱 Models catalog 來驗證該模型支援哪些協議。檢查回應中的 tokenlab.accepted_request_formats 清單。有關完整的端點對應規則，請參閱 API Formats guide。

記載的請求標頭

對 TokenLab 端點的所有標準呼叫都需要特定的 HTTP 請求標頭：

• Authorization：以 Bearer 權杖形式傳遞憑證（Authorization: Bearer $TOKENLAB_API_KEY）。管理端點需要管理權杖（Authorization: Bearer mt-...）。
• Content-Type：包含 JSON 本文的 POST 請求必須為 application/json。

記載的回應標頭

TokenLab 會返回用於速率限制、計費對帳和非同步任務管理的標準及自訂 HTTP 標頭：

速率限制標頭

當請求超過帳戶層級限制時，TokenLab 會返回 HTTP 429 rate_limit_exceeded 狀態，並附帶兩個標頭：

• Retry-After：指定重試呼叫前所需的等待時間（秒）。
• X-RateLimit-Limit：回報通過驗證之層級的有效每分鐘請求數（requests-per-minute）限制。

請務必使用 Retry-After 標頭值來處理重試，而不是寫死退避限制（backoff limits）。有關復原處理的更多詳細資訊，請參閱 Rate Limits guide。

計費與可觀測性標頭

對於非串流和非同步互動，TokenLab 提供識別標頭以追蹤費用和背景工作：

• X-Billing-Transaction-ID：在 HTTP 回應發送前已完成計費結算時返回。非串流且相容於 OpenAI 的端點會在 JSON 本文中包含 billing_transaction_id，但 Gemini 和原生格式端點則透過此標頭公開。串流呼叫可能會在連線關閉後才完成結算；若未提供此標頭，請從工作區用量記錄中擷取該 ID。請在 Billing and Pricing guide 中檢閱結算工作流程。
• X-Task-ID：建立影片、音樂、3D 或基於任務的圖片生成非同步作業時，會在回應標頭中返回。它提供了對應於任務 id 的標頭層級關聯 ID。請參閱 Logs and Troubleshooting guide 以了解記錄標準。

實作：擷取標頭並在 429 時重試

以下 Python 範例說明如何向 Chat Completions 端點發送請求、檢查交易識別碼，以及在遇到速率限制時處理 Retry-After 標頭：

import os
import time
import requests

API_KEY = os.environ["TOKENLAB_API_KEY"]
ENDPOINT = "https://api.tokenlab.sh/v1/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Summarize system status."}]
}

max_attempts = 3
for attempt in range(max_attempts):
    response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=30)

    if response.status_code == 200:
        # Check for billing transaction header on settled non-streaming calls
        billing_id = response.headers.get("X-Billing-Transaction-ID")
        data = response.json()
        print(f"Settled Transaction ID: {billing_id}")
        print(data["choices"][0]["message"]["content"])
        break

    elif response.status_code == 429:
        retry_after = response.headers.get("Retry-After")
        limit = response.headers.get("X-RateLimit-Limit")
        wait_seconds = float(retry_after) if retry_after else 2 ** attempt
        print(f"Rate limit reached ({limit} req/min). Retrying in {wait_seconds}s...")
        time.sleep(wait_seconds)
    else:
        response.raise_for_status()

記錄與可觀測性實務

在建置請求監控檢測時，請記錄標頭與有效負載中返回的公開追蹤識別碼以進行資料對帳，而無需保留使用者提示或憑證：

• 將 request_id、X-Billing-Transaction-ID 和 X-Task-ID 與狀態碼及回應延遲一同保留。
• 務必從遙測管線中遮蔽 Authorization 標頭、原始 API 金鑰以及私人簽署 URL。
• 進行伺服器端財務對帳時，請查詢 GET /v1/management/api-keys/{keyId}/usage，而不是爬取資訊主頁頁面或僅從原始權杖計數器估算總額。