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

Avant de connecter une API d’IA, identifiez le contrat attendu par votre client : compatible avec OpenAI ou avec Anthropic. Utilisez ensuite la Base URL documentée par le fournisseur, conservez la clé API hors du code source, envoyez une requête courte et vérifiez à la fois la réponse et son enregistrement d’utilisation. Le simple fait qu’un écran de configuration s’enregistre sans erreur ne prouve pas que la requête a atteint l’endpoint prévu.

Si vous avez besoin d’une passerelle API plutôt que de l’abonnement web propre à un fournisseur, commencez par la présentation des API d’IA BetterToken. BetterToken propose des interfaces distinctes compatibles avec OpenAI et Anthropic. Vous utilisez toujours votre propre compte BetterToken et votre propre clé API ; cette clé ne provient ni d’OpenAI Console ni d’Anthropic Console.

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

Ce sont des produits différents :

Mode d’accès	Ce que vous recevez	Ce que cela n’implique pas
Accès API	Des requêtes HTTP authentifiées avec votre propre clé	L’accès à l’abonnement de chat grand public d’un fournisseur
Abonnement web	Une interface produit précise et les limites incluses	Un solde API transférable ou une clé API tierce
Compte partagé	La session de connexion d’une autre personne	Une intégration de production sûre ou adaptée

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.

Chez un fournisseur compatible OpenAI, la Base URL et le chemin Chat Completions peuvent prendre cette forme :

Base URL: https://api.example.com/v1
Chemin complet : https://api.example.com/v1/chat/completions

Chez un fournisseur compatible Anthropic, la forme peut être Base URL https://api.example.com et chemin Messages complet https://api.example.com/v1/messages. Ce sont des formes, et non des valeurs à copier : prenez les valeurs réelles dans la documentation du fournisseur choisi.

Besoin de vérifier le protocole et les champs de la première requête ? Ouvrir la référence de configuration de l’API

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://api.example.com/v1/chat/completions
Anthropic Messages raw path: https://api.example.com/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 API_KEY="your_api_key_here"
export MODEL_ID="your_current_model_id"
export OPENAI_BASE_URL="https://api.example.com/v1"
export ANTHROPIC_BASE_URL="https://api.example.com"

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 "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$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 "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$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.

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.
• L’enregistrement d’utilisation ou de facturation du fournisseur contient la requête avec le statut et le montant attendus.

La disponibilité des modèles, les Model IDs et les prix changent. Consultez le catalogue et la page de prix actuels du fournisseur choisi avant de calculer un budget.

7. Diagnostiquer les erreurs par couche de réponse

• 401 : vérifiez la clé, les espaces superflus et la méthode d’authentification. Bearer et x-api-key ne sont pas interchangeables.
• 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.
• 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.

L’ordre pratique est le suivant : déterminer le contrat du client, stocker la clé comme secret, définir la bonne Base URL, envoyer une requête courte et vérifier la réponse avec le relevé d’utilisation. Ajoutez streaming, outils, contexte long ou workflow d’agent seulement ensuite.

É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.

Les formes https://api.example.com, https://api.example.com/v1, https://api.example.com/v1/messages et https://api.example.com/v1/chat/completions sont des exemples : utilisez les valeurs documentées par le fournisseur choisi.