Tìm hiểu về các HTTP Header và Endpoint Giao thức Gốc của TokenLab

Endpoint Giao thức Xác định Schema của Payload

TokenLab không sử dụng các header gợi ý định dạng động (như các thẻ gợi ý định dạng độc quyền) để biểu thị schema phản hồi tại thời điểm runtime. Thay vào đó, cấu trúc payload được quản lý nghiêm ngặt bởi endpoint được gọi. Việc phân tích cú pháp (parsing) phản hồi của client đòi hỏi phải định tuyến các request đến endpoint giao thức gốc đích thay vì kiểm tra các response header để tìm kiểu payload:

• Chat Completions (/v1/chat/completions): Sử dụng các schema tương thích với OpenAI, trả về choices, message.content và một khối usage (prompt_tokens, completion_tokens, total_tokens).
• Responses (/v1/responses): Tuân theo định dạng OpenAI Responses API dành cho các tác vụ nền, công cụ phía server (server tools) và các sự kiện phản hồi.
• Anthropic Messages (/v1/messages): Tương tác với các mô hình Anthropic Claude bằng schema gốc của Anthropic (các khối content, thinking và output_tokens). Khi cấu hình Anthropic SDK, hãy đặt base URL thành https://api.tokenlab.sh mà không có tiền tố /v1.
• Gemini (/v1beta/models/:model:generateContent): Chấp nhận các schema gốc của Gemini (contents, parts) và trả về các đối tượng candidate chuẩn của Gemini REST.

Trước khi định tuyến một request mô hình, hãy xác minh các giao thức mà mô hình đó chấp nhận bằng cách gọi Lấy thông tin mô hình (GET /v1/models/{model}) hoặc xem Danh mục mô hình. Kiểm tra danh sách tokenlab.accepted_request_formats trong phản hồi. Hãy tham khảo Hướng dẫn về các định dạng API để biết các quy tắc ánh xạ endpoint toàn diện.

Các Request Header Được Tài Liệu Hóa

Tất cả các lệnh gọi chuẩn đến các endpoint của TokenLab đều yêu cầu các HTTP request header cụ thể:

• Authorization: Truyền thông tin xác thực dưới dạng bearer token (Authorization: Bearer $TOKENLAB_API_KEY). Các endpoint quản trị yêu cầu một management token (Authorization: Bearer mt-...).
• Content-Type: Phải là application/json đối với các request POST có phần thân JSON.

Các Response Header Được Tài Liệu Hóa

TokenLab trả về các HTTP header chuẩn và tùy chỉnh dành cho giới hạn tốc độ, đối soát thanh toán và quản lý tác vụ bất đồng bộ:

Các Header Giới Hạn Tốc Độ (Rate Limiting)

Khi một request vượt quá giới hạn gói tài khoản, TokenLab sẽ trả về trạng thái HTTP 429 rate_limit_exceeded kèm theo hai header:

• Retry-After: Chỉ định khoảng thời gian chờ bắt buộc tính bằng giây trước khi thử lại lệnh gọi.
• X-RateLimit-Limit: Báo cáo giới hạn số request mỗi phút (requests-per-minute) đang hoạt động cho gói đã xác thực của bạn.

Luôn sử dụng giá trị header Retry-After để xử lý các lần thử lại thay vì hardcode các giới hạn backoff. Thông tin chi tiết hơn về cách xử lý phục hồi có trong Hướng dẫn về giới hạn tốc độ.

Các Header Thanh Toán và Khả Năng Quan Sát (Observability)

Đối với các tương tác non-streaming và bất đồng bộ, TokenLab cung cấp các header nhận dạng để theo dõi chi phí và công việc chạy ngầm:

• X-Billing-Transaction-ID: Được trả về khi quá trình thanh toán được quyết toán trước khi HTTP response được gửi đi. Các endpoint tương thích với OpenAI dạng non-streaming bao gồm billing_transaction_id trong phần thân JSON, nhưng Gemini và các endpoint định dạng gốc sẽ hiển thị nó qua header này. Các lệnh gọi streaming có thể quyết toán sau khi kết nối đóng; khi không có header này, hãy truy xuất ID từ bản ghi mức sử dụng của workspace. Xem lại quy trình quyết toán trong Hướng dẫn về thanh toán và định giá.
• X-Task-ID: Được trả về trên các response header khi tạo các job bất đồng bộ cho video, âm nhạc, 3D hoặc tạo hình ảnh theo tác vụ. Header này cung cấp ID tương quan ở cấp header tương ứng với id của tác vụ. Tham khảo Hướng dẫn về log và khắc phục sự cố để biết các tiêu chuẩn ghi log.

Triển Khai: Thu Thập Header và Thử Lại Khi Gặp Lỗi 429

Ví dụ bằng Python sau đây minh họa cách gửi một request đến endpoint Chat Completions, kiểm tra các mã định danh giao dịch và xử lý header Retry-After khi gặp giới hạn tốc độ:

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()

Thực Tiễn Ghi Log và Khả Năng Quan Sát

Khi thiết lập hệ thống giám sát request, hãy ghi log các định danh theo dõi công khai được trả về trong header và payload để đối soát dữ liệu mà không cần lưu trữ prompt của người dùng hoặc thông tin xác thực:

• Lưu giữ request_id, X-Billing-Transaction-ID và X-Task-ID cùng với mã trạng thái (status code) và độ trễ phản hồi (response latency).
• Luôn lọc bỏ (redact) các header Authorization, API key thô và URL riêng tư đã ký (signed URL) khỏi luồng thu thập dữ liệu đo lường từ xa (telemetry).
• Để đối soát tài chính phía server, hãy truy vấn GET /v1/management/api-keys/{keyId}/usage thay vì trích xuất dữ liệu từ trang dashboard hoặc ước tính tổng số chỉ dựa trên các bộ đếm token thô.