Choisir un niveau de livraison TokenLab : Auto, Verified ou Official

Une requête peut échouer avec une erreur 503 même si l'ID du modèle est parfaitement valide, et la cause est souvent le niveau de livraison que vous avez verrouillé. Dans notre pipeline, nous avons rencontré ce problème lorsque nous avons imposé une option sur un modèle qui ne la proposait pas. Ce guide explique les trois options de niveau de livraison, l'ordre d'application des paramètres et ce que chacun signifie pour votre facture. Tous les faits ci-dessous proviennent de la documentation TokenLab et de l'API de modèle en direct, observés le 03/10/2026.

Points clés à retenir

• Un niveau de livraison possède trois valeurs : auto, verified et official.
• Un en-tête de requête remplace le paramètre de la clé API, qui remplace lui-même la valeur par défaut de l'espace de travail (Workspace).
• Si l'option demandée n'est pas disponible, vous recevrez 503 delivery_tier_unavailable. Lorsque retryable est false, ne renvoyez pas la même requête.
• Vous payez une seule fois, pour l'option qui a permis de finaliser la requête.
• Vérifiez GET /v1/models/{model} avant de verrouiller un niveau. C'est public et ne nécessite aucune clé.

Les trois options de niveau de livraison

La référence de l'API (observée le 03/10/2026) définit trois options :

• Auto utilise TokenLab Verified si disponible, puis Official si nécessaire. Vous payez pour l'option qui finalise votre requête.
• TokenLab Verified est une livraison vérifiée par TokenLab. Les prix TokenLab s'appliquent.
• Official est basé sur le prix public du créateur du modèle. Le prix affiché sur TokenLab est ce que vous payez.

Les requêtes de génération acceptent l'en-tête X-TokenLab-Delivery-Policy: auto | verified | official. Une valeur d'en-tête invalide renvoie 400.

Quel paramètre s'applique en premier

Trois endroits permettent de définir le niveau de livraison. L'ordre documenté est le suivant :

1. L'en-tête de la requête.
2. Le paramètre de la clé API.
3. La valeur par défaut de l'espace de travail (Workspace).

L'en-tête remplace la clé, et la clé remplace l'espace de travail. Les sessions en temps réel font exception : elles utilisent le paramètre de la clé API ou de l'espace de travail et n'acceptent pas de remplacement via une chaîne de requête (query-string).

Définir le niveau de livraison sur une requête

Voici un appel Chat Completions qui verrouille la livraison Official. L'ID du modèle claude-sonnet-5 est listé dans l'API de modèle en direct avec les deux options disponibles. Voir la page du modèle.

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!"}
    ]
  }'

Le même en-tête fonctionne sur le point de terminaison Anthropic Messages. Pour /v1/messages, l'en-tête de clé peut être x-api-key, ce que la référence de l'API indique comme étant accepté par 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!"}]
  }'

Définir le niveau de livraison sur une clé API

Pour faire d'un niveau de livraison la valeur par défaut pour une clé, utilisez l'API de gestion avec un jeton de gestion (mt-...). Les pages Create API Key et Update API Key (toutes deux observées le 03/10/2026) documentent un champ deliveryPolicy. Ses valeurs sont auto, verified, official ou null. Une valeur null hérite de la politique de l'espace de travail.

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"
  }'

La mise à jour nécessite au moins un champ, donc ce corps est valide en soi. Les réponses indiquent le paramètre sous le nom delivery_policy, où null signifie que la clé hérite de la valeur par défaut de l'espace de travail. Le point de terminaison de création accepte le même champ deliveryPolicy dans son corps de requête. L'omettre lors de la création est cohérent avec l'héritage null documenté, comme le montre l'exemple de réponse de création delivery_policy: null.

Lorsque l'option demandée n'est pas disponible

Si l'option que vous demandez n'est pas disponible, TokenLab renvoie 503 delivery_tier_unavailable et un ID de requête. Le guide de gestion des erreurs (observé le 03/10/2026) explique comment lire retryable.

Un statut 5xx ne signifie pas toujours une panne temporaire. Lorsque l'opération sélectionnée n'est pas disponible dans ce niveau, retryable est false et retry_after est omis. Ne répétez pas la même requête sans modification. Au lieu de cela :

1. Lisez code et retryable, pas le message lisible par l'humain.
2. Enregistrez l'ID de requête depuis les en-têtes de réponse.
3. Vérifiez la disponibilité de livraison du modèle avec GET /v1/models avant de choisir un autre modèle ou niveau.

Le guide avertit que des noms de modèles similaires ne prouvent pas la disponibilité. Un client doit effectuer une branchement sur code, et ne réessayer une erreur 5xx que lorsque retryable est true, en respectant retry_after et en plafonnant les tentatives.

Vérifier les options d'un modèle

Le point de terminaison du modèle rapporte la delivery availability by option. Ces valeurs proviennent de l'API de modèle en direct, observée le 03/10/2026 :

ID du modèle	Verified	Official	Page du modèle
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

Par exemple, verrouiller verified sur deepseek-v4-flash est le type de requête qui atteindrait delivery_tier_unavailable, car l'API ne rapporte aucune offre Verified aujourd'hui. Official et Auto restent valides ici.

Vérifiez n'importe quel modèle vous-même :

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

La disponibilité est vérifiée à chaque exécution de requête, et le guide de facturation indique que les étiquettes de livraison décrivent les options prises en charge. Considérez l'API de modèle comme un instantané et relisez-la avant de coder en dur un niveau verrouillé.

Comment le choix affecte ce que vous payez

Le guide de facturation (observé le 03/10/2026) indique que chaque requête terminée est facturée une fois, pour l'option qui a produit le résultat :

• TokenLab Verified utilise les prix publics de TokenLab.
• Official utilise la couche de prix Official basée sur le prix public du créateur du modèle.
• Auto facture l'option qui finalise la requête.

Pour la génération payante, la console affiche une estimation maximale avant confirmation, et l'utilisation (Usage) affiche la charge finale. Tout montant réservé inutilisé est libéré. Sur la page des modèles, un tiret dans la colonne de prix TokenLab signifie qu'aucune offre Verified n'est actuellement disponible. Cela ne signifie pas que c'est gratuit.

Le guide ne documente aucun écart de prix fixe entre Verified et Official, nous n'en revendiquerons donc aucun. Pour le prix TokenLab en direct sur claude-sonnet-5, l'API de modèle liste l'entrée à 0,9 USD et la sortie à 4,5 USD par million de tokens (tarification mise à jour le 02/10/2026). À titre d'estimation, 100 000 tokens d'entrée plus 10 000 tokens de sortie représentent 0,09 + 0,045 = 0,135 USD. Ce chiffre utilise uniquement le prix TokenLab listé. Lisez le prix Official sur la page du modèle avant de comparer.

Un court guide de décision

• Par défaut sur Auto lorsque vous voulez que la requête aboutisse et que vous pouvez accepter l'une ou l'autre couche de prix.
• Verrouillez Verified lorsque vous avez besoin des prix TokenLab et que le modèle rapporte verified: true.
• Verrouillez Official lorsque vous avez besoin de la base de prix public du créateur du modèle, ou lorsque le modèle n'a aucune offre Verified.
• Définissez la valeur par défaut de la clé pour les travailleurs qui ont toujours besoin du même niveau, et utilisez l'en-tête pour les exceptions ponctuelles.

Avant de verrouiller, lisez GET /v1/models/{model}. Effectuez un petit test et confirmez la charge dans l'utilisation (Usage).

Étape suivante : créer une clé avec une politique de livraison

Créez une clé API dans la Console, ou appelez POST /v1/management/api-keys avec un jeton de gestion et définissez deliveryPolicy dans le corps, comme décrit dans la page Create API Key. Envoyez ensuite une petite requête avec l'en-tête ci-dessus et vérifiez la charge dans l'utilisation (Usage).

FAQ

Quel paramètre l'emporte si l'en-tête, la clé API et l'espace de travail sont en désaccord ?

L'en-tête de la requête l'emporte. Le paramètre de la clé API remplace la valeur par défaut de l'espace de travail. Les sessions en temps réel ignorent l'en-tête et utilisent le paramètre de la clé ou de l'espace de travail.

Pourquoi ai-je reçu 503 delivery_tier_unavailable, et dois-je réessayer ?

Le niveau que vous avez demandé n'a aucune offre pour cette opération. Lisez retryable : lorsqu'il est false, ne renvoyez pas la même requête. Vérifiez la disponibilité avec GET /v1/models et changez le niveau ou le modèle.

Official coûte-t-il plus cher que TokenLab Verified ?

Les documents n'indiquent pas de différence fixe. Verified utilise les prix publics de TokenLab, et Official utilise la base de prix public du créateur du modèle. Comparez les deux sur la page du modèle et confirmez la charge finale dans l'utilisation (Usage).

Comment voir quelles options de livraison un modèle prend en charge ?

Appelez GET /v1/models/{model}, qui ne nécessite aucune clé. Aujourd'hui, claude-sonnet-5 et gpt-5.6-terra rapportent Verified et Official, tandis que deepseek-v4-flash rapporte uniquement Official.

Puis-je définir une option de livraison pour les sessions en temps réel ?

Oui, via le paramètre de la clé API ou de l'espace de travail. Les sessions en temps réel n'acceptent pas de remplacement via une chaîne de requête.

Créez votre clé API TokenLab dans la Console