L'API Claude pour ceux qui construisent
- 01La requête, une seule porte d'entrée6 min
L'API Claude n'a qu'une seule porte d'entrée, la requête POST de l'API Messages : chaque échange passe par ce point, avec un tableau messages et un modèle choisi. Le champ max_tokens est obligatoire, sans valeur par défaut, et la réponse suit toujours la même forme, avec un stop_reason qui indique pourquoi la génération s'est arrêtée.
- 02Des rôles qui tiennent, pas un pré remplissage qui casse7 min
Compléter soi-même le début de la réponse de Claude, le pré remplissage du tour assistant, ne fonctionne plus sur les modèles courants : le serveur renvoie une erreur, sauf un cas particulier de gestion des refus. Une instruction system stable produit le même résultat sans toucher au tableau messages, et le champ output_config.format contraint la forme de la sortie.
- 03Les outils, Claude propose, le code dispose7 min
Claude n'exécute jamais un outil lui-même : il renvoie une demande d'usage, le code du développeur l'exécute réellement, puis renvoie le résultat pour que la conversation continue. Ce cycle repose sur un seul contrat, le schéma déclaré par le champ input_schema. Un outil se déclare par name, description et input_schema.
- 04Recevoir la réponse au fil de l'eau6 min
Le mode flux garde la connexion HTTP ouverte et livre le texte par fragments, au fur et à mesure que le modèle le produit, sans attendre la fin de la génération. Le décompte de jetons vit dans le champ usage du dernier événement message_delta, jamais dans message_stop : un code qui l'y cherche ne le trouve pas.
- 05Deux leviers de coût, la mémoire en cache et le traitement par lot8 min
Un préfixe de requête marqué comme réutilisable coûte une fraction réduite du prix normal quand il est relu depuis le cache, et un ensemble de requêtes non urgentes traité en lot coûte moins cher qu'un traitement immédiat, deux réductions qui se cumulent entre elles et avec les autres modificateurs de prix.
- 06Compter avant d'envoyer, la fenêtre de contexte6 min
Un point de comptage dédié rend le nombre de jetons d'une requête avant de l'envoyer, et la fenêtre de contexte à comparer à ce chiffre n'est plus une valeur commune à toute une gamme de modèles, elle varie désormais fortement d'une famille à l'autre.
- 07Choisir un modèle, en changer, encaisser un refus9 min
Le choix d'un modèle est un compromis entre qualité, vitesse et coût qui se revoit à chaque nouvelle génération, et un refus renvoyé par un classificateur de sécurité se traite comme un cas normal du protocole, pas comme une panne.
- 08Passer à Opus 5.5 sans casser votre code8 min
Passer de Claude Opus 5 à Claude Opus 5.5 ne se résume pas à changer l'identifiant : quatre réglages anciens renvoient désormais une erreur 400, et les notes écrites entre deux appels d'outils arrivent vides tant que le code ne règle pas thinking.display.