Memahami HTTP Header dan Endpoint Protokol Native TokenLab

Endpoint Protokol Menentukan Skema Payload

TokenLab tidak menggunakan header petunjuk format dinamis (seperti tag petunjuk format khusus) untuk menunjukkan skema respons pada saat runtime. Sebaliknya, struktur payload diatur secara ketat oleh endpoint yang dipanggil. Penguraian respons klien memerlukan perutean permintaan ke endpoint protokol native target alih-alih memeriksa header respons untuk tipe payload:

• Chat Completions (/v1/chat/completions): Menggunakan skema yang kompatibel dengan OpenAI yang mengembalikan choices, message.content, dan blok usage (prompt_tokens, completion_tokens, total_tokens).
• Responses (/v1/responses): Mematuhi format OpenAI Responses API untuk tugas latar belakang, alat server, dan event respons.
• Anthropic Messages (/v1/messages): Berinteraksi dengan model Anthropic Claude menggunakan skema native Anthropic (content blocks, thinking, dan output_tokens). Saat mengonfigurasi Anthropic SDK, atur URL dasar ke https://api.tokenlab.sh tanpa awalan /v1.
• Gemini (/v1beta/models/:model:generateContent): Menerima skema native Gemini (contents, parts) dan mengembalikan objek kandidat REST standar Gemini.

Sebelum merutekan permintaan model, verifikasi protokol mana yang diterima dengan memanggil Dapatkan Model (GET /v1/models/{model}) atau meninjau katalog Model. Periksa daftar tokenlab.accepted_request_formats dalam respons. Buka panduan Format API untuk aturan pemetaan endpoint yang lengkap.

Header Permintaan Terdokumentasi

Semua panggilan standar ke endpoint TokenLab memerlukan HTTP header permintaan tertentu:

• Authorization: Meneruskan kredensial sebagai token bearer (Authorization: Bearer $TOKENLAB_API_KEY). Endpoint manajemen memerlukan token manajemen (Authorization: Bearer mt-...).
• Content-Type: Harus berupa application/json untuk permintaan POST yang berisi bodi JSON.

Header Respons Terdokumentasi

TokenLab mengembalikan HTTP header standar dan kustom untuk batas laju, rekonsiliasi penagihan, dan manajemen tugas asinkron:

Header Pembatasan Laju (Rate Limiting)

Ketika permintaan melebihi batas tingkat akun, TokenLab mengembalikan status HTTP 429 rate_limit_exceeded disertai dengan dua header:

• Retry-After: Menentukan periode tunggu yang diperlukan dalam detik sebelum mencoba kembali panggilan tersebut.
• X-RateLimit-Limit: Melaporkan batas permintaan-per-menit aktif Anda untuk tingkat yang diautentikasi.

Selalu gunakan nilai header Retry-After untuk menangani percobaan ulang daripada melakukan hardcoding pada batas backoff. Detail lebih lanjut mengenai penanganan pemulihan dapat dilihat di panduan Batas Laju.

Header Penagihan dan Observabilitas

Untuk interaksi non-streaming dan asinkron, TokenLab menyediakan header identifikasi untuk melacak biaya dan pekerjaan latar belakang:

• X-Billing-Transaction-ID: Dikembalikan saat penagihan diselesaikan sebelum respons HTTP dikirimkan. Endpoint non-streaming yang kompatibel dengan OpenAI menyertakan billing_transaction_id dalam bodi JSON, tetapi Gemini dan endpoint format native mengeksposnya melalui header ini. Panggilan streaming mungkin diselesaikan setelah koneksi ditutup; jika tidak ada, ambil ID dari catatan penggunaan ruang kerja. Tinjau alur kerja penyelesaian di panduan Penagihan dan Harga.
• X-Task-ID: Dikembalikan pada header respons saat membuat tugas asinkron untuk video, musik, 3D, atau pembuatan gambar berbasis tugas. Header ini menyediakan ID korelasi tingkat header yang sesuai dengan id tugas. Buka panduan Log dan Pemecahan Masalah untuk standar pencatatan log.

Implementasi: Menangkap Header dan Mencoba Ulang pada 429

Contoh Python berikut mengilustrasikan cara mengirimkan permintaan ke endpoint Chat Completions, memeriksa pengidentifikasi transaksi, dan menangani header Retry-After selama pembatasan laju:

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

Praktik Pencatatan Log dan Observabilitas

Saat mengonfigurasi pemantauan permintaan, catat pengidentifikasi pelacakan publik yang dikembalikan dalam header dan payload untuk merekonsiliasi catatan tanpa menyimpan prompt pengguna atau kredensial:

• Pertahankan request_id, X-Billing-Transaction-ID, dan X-Task-ID bersama dengan kode status dan latensi respons.
• Selalu lakukan redaksi terhadap header Authorization, API key mentah, dan URL bertanda tangan pribadi dari pipeline telemetri.
• Untuk rekonsiliasi keuangan di sisi server, lakukan kueri GET /v1/management/api-keys/{keyId}/usage alih-alih melakukan scraping halaman dasbor atau memperkirakan total dari penghitung token mentah saja.