TokenLab Delivery Tier 선택하기: Auto, Verified, 또는 Official

모델 ID가 완벽하게 유효함에도 불구하고 503 오류로 요청이 실패할 수 있는데, 그 원인은 종종 고정해 둔 배달 티어(delivery tier) 때문입니다. 저희 파이프라인에서도 해당 옵션을 제공하지 않는 모델에 특정 옵션을 강제로 적용했을 때 이 문제를 겪었습니다. 이 가이드에서는 세 가지 배달 티어 옵션, 설정이 적용되는 순서, 그리고 각 옵션이 청구서에 미치는 의미를 설명합니다. 아래의 모든 사실은 2026년 10월 3일 관찰된 TokenLab 문서 및 라이브 모델 API를 기반으로 합니다.

핵심 요약

• 배달 티어에는 auto, verified, official 세 가지 값이 있습니다.
• 요청 헤더는 API 키 설정을 재정의하며, API 키 설정은 워크스페이스 기본값을 재정의합니다.
• 요청한 옵션의 공급이 없는 경우 503 delivery_tier_unavailable이 발생합니다. retryable이 false인 경우 동일한 요청을 다시 보내지 마십시오.
• 요청을 완료한 옵션에 대해 한 번만 결제합니다.
• 티어를 고정하기 전에 GET /v1/models/{model}을 확인하십시오. 이 정보는 공개되어 있으며 키가 필요하지 않습니다.

세 가지 배달 티어 옵션

API 참조(2026년 10월 3일 관찰)는 세 가지 옵션을 정의합니다:

• Auto는 가능할 경우 TokenLab Verified를 사용하고, 필요하면 Official을 사용합니다. 요청을 완료한 옵션에 대해 비용을 지불합니다.
• TokenLab Verified는 TokenLab이 검증한 배달 방식입니다. TokenLab 가격이 적용됩니다.
• Official은 모델 제작사의 공개 가격을 기준으로 합니다. TokenLab에 표시된 가격이 지불할 금액입니다.

생성 요청은 X-TokenLab-Delivery-Policy: auto | verified | official 헤더를 허용합니다. 유효하지 않은 헤더 값은 400을 반환합니다.

설정 적용 우선순위

배달 티어는 세 곳에서 설정할 수 있습니다. 문서화된 적용 순서는 다음과 같습니다:

1. 요청 헤더
2. API 키 설정
3. 워크스페이스 기본값

헤더가 키를 재정의하고, 키가 워크스페이스를 재정의합니다. 실시간 세션은 예외입니다. 실시간 세션은 API 키 또는 워크스페이스 설정을 사용하며 쿼리 문자열 재정의를 허용하지 않습니다.

요청 시 배달 티어 설정

다음은 Official 배달을 고정한 Chat Completions 호출 예시입니다. 모델 ID claude-sonnet-5는 라이브 모델 API에 두 옵션 모두 사용 가능한 것으로 나열되어 있습니다. 모델 페이지를 참조하십시오.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: official" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

동일한 헤더가 Anthropic Messages 엔드포인트에서도 작동합니다. /v1/messages의 경우 키 헤더는 Anthropic Messages가 허용하는 x-api-key일 수 있습니다.

curl https://api.tokenlab.sh/v1/messages \
  -H "x-api-key: $TOKENLAB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: verified" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

API 키에 배달 티어 설정

특정 키에 배달 티어를 기본값으로 설정하려면 관리 토큰(mt-...)을 사용하여 관리 API를 사용하십시오. API 키 생성 및 API 키 업데이트 페이지(둘 다 2026년 10월 3일 관찰)는 deliveryPolicy 필드를 문서화하고 있습니다. 값은 auto, verified, official 또는 null입니다. null 값은 워크스페이스 정책을 상속합니다.

이 스케치는 문서화된 PATCH 형식을 따릅니다. 키 ID는 문서 예시 값입니다.

curl -X PATCH "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456" \
  -H "Authorization: Bearer mt-your-management-token" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryPolicy": "verified"
  }'

업데이트 시 최소 하나의 필드가 필요하므로 이 본문은 그 자체로 유효합니다. 응답은 설정을 delivery_policy로 보고하며, null은 키가 워크스페이스 기본값을 상속함을 의미합니다. 생성 엔드포인트도 요청 본문에서 동일한 deliveryPolicy 필드를 허용합니다. 생성 시 이를 생략하는 것은 문서화된 null 상속과 일치하며, 생성 예시 응답에 delivery_policy: null이 표시됩니다.

요청한 옵션을 사용할 수 없는 경우

요청한 옵션의 공급이 없는 경우, TokenLab은 503 delivery_tier_unavailable과 요청 ID를 반환합니다. 오류 처리 가이드(2026년 10월 3일 관찰)에서 retryable을 읽는 방법을 설명합니다.

5xx 상태가 항상 일시적인 중단을 의미하는 것은 아닙니다. 선택한 작업이 해당 티어에 공급이 없는 경우 retryable은 false이며 retry_after는 생략됩니다. 동일한 요청을 변경 없이 반복하지 마십시오. 대신 다음을 수행하십시오:

1. 사람이 읽을 수 있는 message가 아닌 code와 retryable을 읽으십시오.
2. 응답 헤더에서 요청 ID를 저장하십시오.
3. 다른 모델이나 티어를 선택하기 전에 GET /v1/models로 모델의 배달 가능 여부를 확인하십시오.

가이드는 유사한 모델 이름이 가용성을 보장하지 않는다고 경고합니다. 클라이언트는 code에 따라 분기해야 하며, retryable이 true일 때만 retry_after를 준수하고 시도 횟수를 제한하며 5xx 오류를 재시도해야 합니다.

모델이 가진 옵션 확인

모델 엔드포인트는 delivery availability by option을 보고합니다. 다음 값들은 2026년 10월 3일 관찰된 라이브 모델 API에서 가져온 것입니다:

모델 ID	Verified	Official	모델 페이지
claude-sonnet-5	true	true	/models/claude-5/claude-sonnet-5
gpt-5.6-terra	true	true	/models/gpt-5-6/gpt-5.6-terra
deepseek-v4-flash	false	true	/models/deepseek-v4/deepseek-v4-flash

예를 들어, deepseek-v4-flash에 verified를 고정하는 것은 API가 현재 Verified 공급을 보고하지 않으므로 delivery_tier_unavailable 오류를 발생시키는 요청 유형입니다. 해당 모델에서는 Official과 Auto만 유효합니다.

직접 모델을 확인해 보십시오:

curl "https://api.tokenlab.sh/v1/models/deepseek-v4-flash"

가용성은 각 요청이 실행될 때 확인되며, 청구 가이드에 따르면 배달 라벨은 지원되는 옵션을 설명합니다. 모델 API를 스냅샷으로 취급하고 티어를 고정하기 전에 다시 읽으십시오.

선택이 지불 금액에 미치는 영향

청구 가이드(2026년 10월 3일 관찰)에 따르면 완료된 각 요청은 결과를 생성한 옵션에 대해 한 번 청구됩니다:

• TokenLab Verified는 TokenLab 공개 가격을 사용합니다.
• Official은 모델 제작사의 공개 가격을 기반으로 한 Official 가격 계층을 사용합니다.
• Auto는 요청을 완료하는 옵션에 따라 요금을 부과합니다.

유료 생성의 경우, 콘솔은 확인 전에 최대 예상 금액을 표시하며, 사용량(Usage)에서 최종 요금을 확인할 수 있습니다. 사용되지 않은 예약 금액은 해제됩니다. 모델 페이지에서 TokenLab 가격 열의 대시는 현재 Verified 제공이 없음을 의미합니다. 무료라는 뜻은 아닙니다.

가이드는 Verified와 Official 간의 고정된 가격 차이를 문서화하지 않으므로, 저희도 주장하지 않겠습니다. 2026년 10월 2일 업데이트된 claude-sonnet-5의 라이브 TokenLab 가격은 100만 토큰당 입력 0.9 USD, 출력 4.5 USD입니다. 추정치로 100,000 입력 토큰과 10,000 출력 토큰은 0.09 + 0.045 = 0.135 USD입니다. 이 수치는 나열된 TokenLab 가격만 사용한 것입니다. 비교하기 전에 모델 페이지에서 Official 가격을 읽어보십시오.

간단한 결정 가이드

• 요청이 완료되기를 원하고 두 가격 계층 중 하나를 수용할 수 있다면 Auto를 기본값으로 사용하십시오.
• TokenLab 가격이 필요하고 모델이 verified: true를 보고하는 경우 Verified를 고정하십시오.
• 모델 제작사의 공개 가격 기준이 필요하거나 모델에 Verified 공급이 없는 경우 Official을 고정하십시오.
• 항상 동일한 티어가 필요한 작업자에게는 키 기본값을 설정하고, 일회성 예외에는 헤더를 사용하십시오.

고정하기 전에 GET /v1/models/{model}을 읽으십시오. 작은 테스트를 실행하고 사용량(Usage)에서 요금을 확인하십시오.

다음 단계: 배달 정책이 포함된 키 생성

콘솔에서 API 키를 생성하거나, 관리 토큰으로 POST /v1/management/api-keys를 호출하여 API 키 생성 페이지에 설명된 대로 본문에 deliveryPolicy를 설정하십시오. 그런 다음 위 헤더를 사용하여 작은 요청을 하나 보내고 사용량(Usage)에서 요금을 확인하십시오.

FAQ

헤더, API 키, 워크스페이스 설정이 서로 다르면 무엇이 우선합니까?

요청 헤더가 우선합니다. API 키 설정은 워크스페이스 기본값을 재정의합니다. 실시간 세션은 헤더를 건너뛰고 키 또는 워크스페이스 설정을 사용합니다.

왜 503 delivery_tier_unavailable 오류가 발생했으며 재시도해야 합니까?

요청한 티어에 해당 작업에 대한 공급이 없습니다. retryable을 읽으십시오. false인 경우 동일한 요청을 다시 보내지 마십시오. GET /v1/models로 가용성을 확인하고 티어나 모델을 변경하십시오.

Official이 TokenLab Verified보다 비쌉니까?

문서에는 고정된 차이가 명시되어 있지 않습니다. Verified는 TokenLab 공개 가격을 사용하고, Official은 모델 제작사의 공개 가격 기준을 사용합니다. 모델 페이지에서 두 가격을 비교하고 사용량(Usage)에서 최종 요금을 확인하십시오.

모델이 지원하는 배달 옵션을 어떻게 확인합니까?

키가 필요 없는 GET /v1/models/{model}을 호출하십시오. 현재 claude-sonnet-5와 gpt-5.6-terra는 Verified와 Official을 보고하며, deepseek-v4-flash는 Official만 보고합니다.

실시간 세션에 대한 배달 옵션을 설정할 수 있습니까?

네, API 키나 워크스페이스 설정을 통해 가능합니다. 실시간 세션은 쿼리 문자열 재정의를 허용하지 않습니다.

콘솔에서 TokenLab API 키 생성하기