API d’IA : protocole, clé API et première requête

Accès API, abonnements web et comptes partagés

Ce sont des produits différents :

Pour un développement normal, utilisez un compte et une clé que vous contrôlez. Ne construisez pas une intégration autour d’un identifiant acheté ou partagé.

1. Choisir le protocole à partir du client

Lisez la documentation du client ou du SDK avant de choisir un modèle. Utilisez l’interface compatible avec OpenAI si l’outil attend un SDK OpenAI, Chat Completions, Responses API ou un champ tel que OPENAI_BASE_URL. Utilisez l’interface compatible avec Anthropic s’il crée des requêtes Messages et attend ANTHROPIC_BASE_URL ou x-api-key.

Le nom du modèle ne détermine pas le protocole. Le client doit produire le même contrat de requête que celui accepté par l’endpoint.

Pour BetterToken, les Base URLs sont :

OpenAI-compatible Base URL:  https://www.bettertoken.ai/v1
Anthropic-compatible Base URL: https://bettertoken.ai/

La valeur compatible avec OpenAI contient déjà /v1. La valeur compatible avec Anthropic ne le contient pas ; une requête Messages directe utilise le chemin complet /v1/messages.

2. Distinguer la Base URL du chemin de requête

Un SDK ou un outil demande généralement une Base URL et ajoute lui-même le chemin de la ressource. Un appel HTTP direct nécessite le chemin complet.

OpenAI-compatible raw path:  https://www.bettertoken.ai/v1/chat/completions
Anthropic Messages raw path: https://www.bettertoken.ai/v1/messages

Ne collez pas un chemin de requête complet dans un champ qui attend uniquement une Base URL. Le client pourrait sinon ajouter deux fois la ressource et renvoyer une erreur 404.

3. Conserver la clé API hors du code

Utilisez des variables d’environnement locales pour le premier test, puis placez les identifiants de production dans le gestionnaire de secrets fourni par votre plateforme.

export BETTERTOKEN_API_KEY="your_api_key_here"
export BETTERTOKEN_MODEL_ID="your_current_model_id"

Ne placez jamais une vraie clé dans le code source, .env.example, un prompt, une issue, une capture d’écran ou un message au support. Copiez le Model ID actuel exact depuis la documentation ou le catalogue du fournisseur au lieu de le deviner à partir d’un nom marketing.

4. Envoyer une requête minimale compatible avec OpenAI

Commencez par une courte requête textuelle avant d’activer le streaming ou les outils :

curl https://www.bettertoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_MODEL_ID"'",
    "messages": [{"role": "user", "content": "Reply with API_OK"}],
    "max_tokens": 16
  }'

Évitez curl -v dans des journaux partagés avec d’autres personnes : la sortie détaillée peut révéler des en-têtes sensibles.

5. Envoyer une requête minimale compatible avec Anthropic

La requête Messages utilise un autre en-tête d’authentification et une autre structure de corps :

curl https://www.bettertoken.ai/v1/messages \
  -H "x-api-key: $BETTERTOKEN_API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_MODEL_ID"'",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Reply with API_OK"}]
  }'

CURRENT_SUPPORTED_VERSION est un espace réservé. Avant le test, vérifiez l’en-tête actuellement pris en charge dans la référence de l’API. Si votre besoin concerne spécifiquement un accès compatible avec Claude, consultez les limites d’accès et la configuration de l’API Claude avant de revenir à la requête minimale.

6. Vérifier la réponse et l’enregistrement d’utilisation

Le premier test n’est terminé que lorsque ces signaux concordent :

• Le statut HTTP indique une réussite.
• La réponse contient le Model ID attendu ou sa valeur d’affichage documentée.
• Le contrat choisi renvoie le contenu et les champs usage attendus.
• BetterToken Workspace affiche au même moment un enregistrement comprenant le modèle, le statut, les tokens d’entrée, de sortie et de cache applicables, ainsi que le montant facturé.

Workspace est un relevé d’utilisation et de facturation. Ne supposez pas qu’il conserve l’intégralité du prompt ou du corps de la réponse. Consultez le catalogue actuel des modèles pour la disponibilité et les tarifs au lieu de copier une liste dynamique dans vos notes d’intégration.

7. Diagnostiquer les erreurs par couche de réponse

• 401 ou 403 : vérifiez la clé, le groupe de clés, les espaces, la Base URL et l’en-tête d’authentification exigé par le protocole choisi.
• 404 : comparez la Base URL au chemin complet. Recherchez un doublon de /v1, /chat/completions ou /messages.
• model not found : copiez le Model ID actuel exact et confirmez qu’il est disponible pour le groupe de clés et le protocole sélectionnés.
• 429 : lisez le corps de la réponse, respectez tout délai de nouvelle tentative et vérifiez les limites actuelles de concurrence ou de débit avant d’envoyer une seule nouvelle requête.
• Timeout ou erreur TLS : distinguez les conditions locales de proxy, pare-feu, DNS et certificats d’une réponse API. Ne désactivez pas durablement la vérification TLS.
• Aucun enregistrement dans Workspace : vérifiez qu’une ancienne variable d’environnement n’a pas dirigé la requête vers un autre fournisseur.

Après chaque modification de configuration, renvoyez une seule requête courte et faites-la correspondre à Workspace. Une fois ce test réussi, ajoutez progressivement le streaming, les outils, un contexte plus long ou une boucle d’agent afin de limiter la surface de diagnostic de chaque nouvelle erreur.

Étape suivante : API compatible OpenAI

Pour un parcours de configuration pratique avec votre propre clé et une route compatible OpenAI, consultez la page API OpenAI. Elle décrit une API BetterToken compatible, et non une clé OpenAI officielle.