TokenLabのHTTPヘッダーとネイティブプロトコルエンドポイントの理解

プロトコルエンドポイントによるペイロードスキーマの決定

TokenLabは、実行時にレスポンススキーマを示すための動的なフォーマットヒントヘッダー（独自のフォーマットヒントタグなど）を使用しません。代わりに、ペイロード構造は呼び出されたエンドポイントによって厳格に制御されます。クライアントレスポンスのパースでは、ペイロードタイプを確認するためにレスポンスヘッダーを検査するのではなく、ターゲットとなるネイティブプロトコルエンドポイントへリクエストをルーティングする必要があります。

• Chat Completions (/v1/chat/completions): choices、message.content、および usage ブロック（prompt_tokens、completion_tokens、total_tokens）を返すOpenAI互換スキーマを使用します。
• Responses (/v1/responses): バックグラウンドタスク、サーバーツール、およびレスポンスイベント用のOpenAI Responses APIフォーマットに準拠します。
• Anthropic Messages (/v1/messages): ネイティブのAnthropicスキーマ（content ブロック、thinking、output_tokens）を使用してAnthropic Claudeモデルと対話します。Anthropic SDKを設定する際は、ベースURLを /v1 プレフィックスなしの https://api.tokenlab.sh に設定してください。
• 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: ベアラートークンとしてクレデンシャルを渡します（Authorization: Bearer $TOKENLAB_API_KEY）。管理エンドポイントには管理トークン（Authorization: Bearer mt-...）が必要です。
• Content-Type: JSONボディを含むPOSTリクエストの場合、application/json である必要があります。

文書化されたレスポンスヘッダー

TokenLabは、レート制限、課金消し込み、および非同期タスク管理のための標準およびカスタムHTTPヘッダーを返します。

レート制限ヘッダー

リクエストがアカウントティアの制限を超えると、TokenLabは2つのヘッダーを伴う HTTP 429 rate_limit_exceeded ステータスを返します。

• Retry-After: 呼び出しを再試行するまでに必要な待機時間を秒単位で指定します。
• X-RateLimit-Limit: 認証されたティアに対するアクティブな1分あたりのリクエスト数（requests-per-minute）の制限を報告します。

バックオフ制限をハードコーディングするのではなく、常に Retry-After ヘッダー値を使用して再試行を処理してください。リカバリ処理の詳細については、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 をクエリしてください。