TokenLabのデリバリーティアの選び方：Auto、Verified、Official

モデルIDが完全に有効であってもリクエストが503エラーで失敗することがありますが、その原因は多くの場合、指定した配信ティアにあります。私たちのパイプラインでは、そのティアを提供していないモデルに対して特定のオプションを強制した際にこの問題が発生しました。本ガイドでは、3つの配信ティアオプション、設定が適用される優先順位、およびそれぞれが請求に与える影響について解説します。以下の事実はすべて、2026年10月3日に確認されたTokenLabのドキュメントおよびライブモデルAPIに基づいています。

重要なポイント

• 配信ティアには auto、verified、official の3つの値があります。
• リクエストヘッダーはAPIキーの設定を上書きし、APIキーの設定はワークスペースのデフォルトを上書きします。
• 要求したオプションに供給がない場合、503 delivery_tier_unavailable が返されます。retryable が false の場合、同じリクエストを再送しないでください。
• 支払いは、リクエストを完了したオプションに対して一度だけ発生します。
• ティアを固定する前に GET /v1/models/{model} を確認してください。これは公開されており、キーは不要です。

3つの配信ティアオプション

APIリファレンス（2026年10月3日確認）では、3つのオプションが定義されています。

• Auto: 利用可能な場合はTokenLab Verifiedを使用し、必要に応じてOfficialを使用します。リクエストを完了したオプションに対して料金が発生します。
• TokenLab Verified: TokenLabによって検証された配信です。TokenLabの価格が適用されます。
• Official: モデル提供元の公開価格に基づきます。TokenLabに表示されている価格が支払額となります。

生成リクエストでは、ヘッダー X-TokenLab-Delivery-Policy: auto | verified | official を受け付けます。無効なヘッダー値を指定すると 400 が返されます。

設定の適用順序

配信ティアは以下の3箇所で設定できます。ドキュメント上の優先順位は以下の通りです：

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 の場合、キーヘッダーは x-api-key となることがあり、APIリファレンスによるとAnthropic Messagesはこれを受け付けます。

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-...）を使用してManagement APIを使用します。Create API KeyおよびUpdate API Keyページ（いずれも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"
  }'

更新には少なくとも1つのフィールドが必要なため、このボディ単体で有効です。レスポンスでは設定が 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"

可用性は各リクエストの実行時にチェックされます。また、Billingガイドには、配信ラベルはサポートされているオプションを説明するものだと記載されています。モデルAPIをスナップショットとして扱い、ティアをハードコードする前に再読み込みしてください。

選択が支払いに与える影響

Billingガイド（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とリストされています。見積もりとして、入力10万トークン＋出力1万トークンは 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 を呼び出し、Create API Keyページで説明されているようにボディに deliveryPolicy を設定します。その後、上記のヘッダーを使用して小さなリクエストを1つ送信し、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キーを作成する