✨ API Agent-First

Présentation

L’API Agent-First de TokenLab enrichit les réponses d’erreur avec des indices structurés que les agents d’IA peuvent analyser et appliquer immédiatement — pas de recherches web, pas de consultation de docs, pas de conjectures. Les erreurs gateway compatibles OpenAI de Chat Completions et Responses peuvent inclure des champs optionnels comme did_you_mean, suggestions, hint, retryable et retry_after dans l’objet error. Anthropic Messages et Gemini conservent leurs formes d’erreur natives et ne promettent pas ces extensions.

Champs d’indice d’erreur

Pour les erreurs gateway compatibles OpenAI, tous les champs d’indice sont des extensions optionnelles dans l’objet error :

Champ	Type	Description
`did_you_mean`	`string`	Nom de modèle le plus proche correspondant
`suggestions`	`array`	Modèles recommandés avec métadonnées
`alternatives`	`array`	Modèles alternatifs actuellement disponibles
`hint`	`string`	Guide lisible par un humain/agent pour l’étape suivante
`retryable`	`boolean`	Indique si retenter la même requête peut réussir
`retry_after`	`number`	Secondes à attendre avant de retenter
`balance_usd`	`number`	Solde actuel du compte en USD
`estimated_cost_usd`	`number`	Coût estimé de la requête échouée

Exemples de codes d’erreur

model_not_found (400)

Quand un nom de modèle ne correspond à aucun modèle actif :

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [
      {"id": "gpt-5.4"},
      {"id": "gpt-5-mini"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.tokenlab.sh/v1/models to list all available models."
  }
}

La résolution de did_you_mean utilise :

Mappage d’alias statique (à partir des données d’erreur en production)
Correspondance de chaînes normalisée (supprime les traits d’union, insensible à la casse)
Correspondance par distance d’édition (seuil ≤ 3)

Les routes publiques n’exposent pas de codes d’erreur séparés pour les modèles cachés, différés ou non publics. Traitez les modèles publics indisponibles de la même manière qu’une erreur de correspondance : inspectez did_you_mean, suggestions et hint, puis retentez avec un modèle public pris en charge.

insufficient_balance (402)

Lorsque le solde du compte est trop faible pour le coût estimé :

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5-mini"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

suggestions contient des modèles moins chers que le coût estimé vers lesquels l’agent peut basculer.

all_channels_failed (503)

Lorsque tous les canaux en amont pour un modèle sont indisponibles :

{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "All channels for 'claude-opus-4-6' are temporarily unavailable. Retry in 30s or try an alternative model."
  }
}

retryable est false lorsque la raison est no_channels (aucun canal configuré pour ce modèle). Il est true uniquement pour les pannes transitoires comme des déclenchements de circuit breaker ou l’épuisement de quotas.

rate_limit_exceeded (429)

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

La valeur retry_after est calculée à partir du temps réel de réinitialisation de la fenêtre de limitation de débit.

Les endpoints compatibles OpenAI utilisent les types d’erreur publics stables de TokenLab tels que rate_limit_exceeded, upstream_error et all_channels_failed. Les endpoints compatibles Anthropic et Gemini utilisent leurs propres formes de réponse natives.

context_length_exceeded (400)

Lorsque l’entrée dépasse la fenêtre de contexte du modèle (erreur en amont, enrichie d’indices) :

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

Découverte des endpoints natifs

Ne déduisez pas la disponibilité d’un protocole natif du nom du modèle ou du fournisseur, ni des en-têtes d’une réponse Chat. Avant de choisir un endpoint natif, consultez GET /v1/models/{model} et utilisez uniquement un format de requête annoncé dans les détails du modèle et desservi par une route du même protocole. Le champ à lire est tokenlab.accepted_request_formats.

Format de requête	Endpoint
Chat Completions	`/v1/chat/completions`
Responses	`/v1/responses`
Messages	`/v1/messages`
Gemini	`/v1beta/models/{model}:generateContent`

Le format annoncé détermine la disponibilité de l’endpoint ; la prise en charge de chaque champ et outil reste propre à l’upstream.

Améliorations de /v1/models

/v1/models contient désormais des métadonnées de recommandation non-chat que les agents peuvent utiliser avant d’appeler les endpoints d’image, vidéo, musique, 3D, TTS, STT, embedding, rerank ou traduction.

{
  "id": "gemini-2.5-flash-image",
  "tokenlab": {
    "category": "image",
    "pricing_unit": "per_request",
    "agent_preferences": {
      "image": {
        "preferred_rank": 1,
        "success_rate_24h": 0.98,
        "sample_count_24h": 423,
        "status": "ready",
        "updated_at": "2026-03-28T12:00:00.000Z",
        "basis": {
          "source": "recent_activity_24h"
        }
      }
    }
  }
}

Champ	Valeurs	Description
`category`	`chat`, `image`, `video`, `audio`, `tts`, `stt`, `3d`, `embedding`, `rerank`	Type de modèle
`pricing_unit`	`per_token`, `per_image`, `per_second`, `per_request`	Méthode de facturation du modèle
`cache_pricing`	object or `null`	Renvoyé uniquement quand le modèle a des prix de prompt cache upstream.
`agent_preferences.<scene>`	object	Instantané de recommandation non-chat renvoyé uniquement avec `GET /v1/models?recommended_for=<scene>`

Quand recommended_for est présent, agent_preferences est dérivé d’un instantané de taux de succès sur 24 heures mis en cache :

Fenêtre : 24 heures
Cache d’instantané : stale-while-revalidate
status = "ready" signifie que le modèle dispose d’un nombre suffisant d’échantillons récents pour participer au classement
status = "insufficient_samples" signifie que le modèle reste visible mais n’est pas classé devant les modèles notés

Filtrage par catégorie

GET https://api.tokenlab.sh/v1/models?category=chat          # Modèles de chat uniquement
GET https://api.tokenlab.sh/v1/models?category=image         # Modèles de génération d'images
GET https://api.tokenlab.sh/v1/models?tag=coding&category=chat  # Modèles de chat optimisés pour le codage

Découverte de recommandations

Pour les workflows non-chat, les agents doivent d’abord récupérer la liste recommandée actuelle :

GET https://api.tokenlab.sh/v1/models?recommended_for=image
GET https://api.tokenlab.sh/v1/models?recommended_for=translation
GET https://api.tokenlab.sh/v1/models?category=tts&recommended_for=tts

Les valeurs valides pour recommended_for sont :

image
video
music
3d
tts
stt
embedding
rerank
translation

Si category et recommended_for sont présents, ils doivent correspondre exactement. Flux recommandé pour l’agent :

GET /v1/models?recommended_for=<scene>
Choisir le premier modèle dont agent_preferences.<scene>.status == "ready"
Appeler explicitement l’endpoint avec model=<selected>
En cas d’erreurs transitoires uniquement, retenter avec le modèle ready suivant

llms.txt

Un aperçu API lisible par machine est disponible à :

GET https://api.tokenlab.sh/llms.txt

Il inclut :

Modèle de première requête avec un exemple fonctionnel
Noms de modèles courants (générés dynamiquement à partir des données d’utilisation)
Les 12 endpoints API
Paramètres de filtrage pour la découverte de modèles
Conseils de gestion des erreurs

Les agents d’IA qui lisent llms.txt avant leur premier appel API peuvent généralement réussir dès la première tentative.

Utilisation dans le code agent

Python (OpenAI SDK)

from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokenlab.sh/v1"
)

def smart_chat(messages, model="gpt-4o"):
    try:
        return client.chat.completions.create(
            model=model, messages=messages
        )
    except BadRequestError as e:
        error = e.body.get("error", {}) if isinstance(e.body, dict) else {}
        # Use did_you_mean for auto-correction
        if error.get("code") == "model_not_found" and error.get("did_you_mean"):
            return client.chat.completions.create(
                model=error["did_you_mean"], messages=messages
            )
        raise

JavaScript (OpenAI SDK)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

async function smartChat(messages, model = 'gpt-4o') {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    const err = error?.error;
    if (err?.code === 'model_not_found' && err?.did_you_mean) {
      return client.chat.completions.create({
        model: err.did_you_mean, messages
      });
    }
    throw error;
  }
}

Principes de conception

Échouer vite, fournir des informations utiles

Les erreurs retournent immédiatement toutes les données dont un agent a besoin pour s’auto-corriger.

Pas de routage automatique

L’API ne remplace jamais silencieusement un modèle différent. L’agent décide.

Suggestions basées sur les données

Toutes les recommandations proviennent de données de production, pas de listes codées en dur.

Rétrocompatible

Tous les champs d’indice sont optionnels. Les clients existants ne voient aucune différence.

Démarrage

Guides essentiels

Guides médias

✨ API Agent-First

Présentation

Champs d’indice d’erreur

Exemples de codes d’erreur

model_not_found (400)

insufficient_balance (402)

all_channels_failed (503)

rate_limit_exceeded (429)

context_length_exceeded (400)

Découverte des endpoints natifs

Améliorations de /v1/models

Filtrage par catégorie

Découverte de recommandations

llms.txt

Utilisation dans le code agent

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Principes de conception

Échouer vite, fournir des informations utiles

Pas de routage automatique

Suggestions basées sur les données

Rétrocompatible

​Présentation

​Champs d’indice d’erreur

​Exemples de codes d’erreur

​model_not_found (400)

​insufficient_balance (402)

​all_channels_failed (503)

​rate_limit_exceeded (429)

​context_length_exceeded (400)

​Découverte des endpoints natifs

​Améliorations de /v1/models

​Filtrage par catégorie

​Découverte de recommandations

​llms.txt

​Utilisation dans le code agent

​Python (OpenAI SDK)

​JavaScript (OpenAI SDK)

​Principes de conception

Échouer vite, fournir des informations utiles

Pas de routage automatique

Suggestions basées sur les données

Rétrocompatible

Présentation

Champs d’indice d’erreur

Exemples de codes d’erreur

model_not_found (400)

insufficient_balance (402)

all_channels_failed (503)

rate_limit_exceeded (429)

context_length_exceeded (400)

Découverte des endpoints natifs

Améliorations de /v1/models

Filtrage par catégorie

Découverte de recommandations

llms.txt

Utilisation dans le code agent

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Principes de conception