TokenLab HTTP 헤더 및 네이티브 프로토콜 엔드포인트 이해하기

프로토콜 엔드포인트가 페이로드 스키마를 결정합니다

TokenLab은 런타임에 응답 스키마를 나타내기 위해 동적 형식 힌트 헤더(예: 독점 형식 힌트 태그)를 사용하지 않습니다. 대신, 페이로드 구조는 호출된 엔드포인트에 의해 엄격하게 제어됩니다. 클라이언트 응답을 파싱하려면 페이로드 유형에 대한 응답 헤더를 검사하는 대신 대상 네이티브 프로토콜 엔드포인트로 요청을 라우팅해야 합니다:

• 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을 /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은 HTTP 429 rate_limit_exceeded 상태와 함께 두 개의 헤더를 반환합니다:

• Retry-After: 호출을 다시 시도하기 전 필요한 대기 시간(초)을 지정합니다.
• X-RateLimit-Limit: 인증된 티어에 대해 활성화된 분당 요청 수(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은 항상 마스킹(redact) 처리합니다.
• 서버 측 재무 정산 시에는 대시보드 페이지를 스크래핑하거나 원시 토큰 카운터만으로 총계를 추정하는 대신 GET /v1/management/api-keys/{keyId}/usage를 쿼리하세요.