Le cycle d'une requête API — Construire avec l'API Claude

Comprendre le trajet d’une requête n’est pas un détour théorique : c’est ce qui vous permettra de savoir, quand quelque chose ne va pas, où chercher. Une réponse tronquée, une latence anormale et une facture inattendue ont chacune leur origine à une étape précise de ce parcours, et les confondre fait perdre des heures.

Les 5 étapes d’une requête

D'après la leçon « Accessing the API » (Claude Academy, Building with the Claude API).

Le client (navigateur, application mobile, script) envoie une demande à votre serveur
Votre serveur reçoit la demande et construit la requête API avec votre clé
L’API Anthropic valide la requête et la transmet au modèle
Le modèle traite le prompt et génère une réponse
La réponse remonte : modèle → API → votre serveur → client

Pourquoi un serveur intermédiaire ?

C’est la règle la plus importante de cette leçon, et elle n’a pas d’exception. Si votre clé se retrouve dans le code JavaScript d’une page web, n’importe qui peut l’ouvrir dans les outils de développement et l’utiliser à vos frais — le code envoyé au navigateur est, par construction, lisible par tout le monde. Aucune obfuscation ni variable d’environnement côté front n’y change quoi que ce soit. Votre serveur backend sert de rempart : c’est lui qui détient la clé et communique avec l’API. Pour lui parler, vous utilisez un SDK officiel (le cours officiel cite Python, TypeScript, JavaScript, Go et Ruby ; il en existe aussi pour Java, C# et PHP) ou de simples requêtes HTTP.

Les champs essentiels d’une requête

Chaque requête à l’API nécessite au minimum une clé d’API, qui identifie votre compte, et trois paramètres :

import anthropic

client = anthropic.Anthropic()  # Utilise ANTHROPIC_API_KEY depuis l'environnement

message = client.messages.create(
    model="claude-sonnet-5-5",   # le modèle à utiliser
    max_tokens=4096,                     # plafond de sortie, réflexion comprise
    messages=[                           # La conversation
        {"role": "user", "content": "Bonjour Claude !"}
    ]
)

Les trois paramètres obligatoires :

model : quel modèle utiliser
max_tokens : plafond de tokens pour la réponse, une sécurité et non une cible ; sur les modèles actuels, la réflexion y compte
messages : la liste des messages de la conversation

Ce que fait Claude en interne

Ces quatre étapes internes expliquent deux comportements que l’on constate sans toujours les relier. D’abord, la facturation se fait en tokens et non en mots ou en caractères — c’est la tokenisation qui décide, et un texte français coûte généralement plus de tokens qu’un texte anglais de même longueur. Ensuite, la réponse arrive progressivement parce qu’elle est produite progressivement, un token après l’autre : c’est ce qui rend le streaming possible, et ce qui explique qu’une réponse longue prenne plus de temps qu’une réponse courte.

Tokenisation : le texte est découpé en tokens (morceaux de mots). “Bonjour” peut devenir un ou plusieurs tokens
Embedding : chaque token est converti en un vecteur numérique
Contextualisation : le modèle analyse les relations entre tous les tokens via le mécanisme d’attention
Génération : une couche de sortie calcule la probabilité de chaque token suivant ; le modèle n’en prend pas toujours le plus probable, il mêle probabilité et part d’aléatoire contrôlée pour des réponses naturelles et variées, puis recommence token après token

Le cours officiel l’illustre avec le mot « quantum » : unité physique, mécanique quantique, échelle subatomique ou informatique quantique, c’est la contextualisation qui choisit le sens d’après les mots voisins. Les modèles actuels ajoutent une étape avant la réponse : ils peuvent réfléchir, en produisant des tokens de réflexion facturés comme des tokens de sortie.

Quand Claude arrête-t-il de générer ?

Ce champ mérite d’être lu par votre code, pas seulement consulté en débogage : c’est lui qui distingue une réponse terminée d’une réponse coupée. Une réponse tronquée à cause de max_tokens ressemble en tout point à une réponse normale — texte cohérent, aucune erreur — sauf qu’il lui manque la fin. Sans vérification de stop_reason, vous l’enregistrerez comme complète.

Fin naturelle : le modèle estime avoir terminé (end_turn)
max_tokens atteint : la réponse est coupée à la limite fixée (max_tokens)
Séquence d’arrêt : le modèle a produit une des chaînes de stop_sequences (stop_sequence, leçon 12)
Demande d’outil : Claude veut appeler un outil (tool_use, section 4)
Tour mis en pause : un tour long, avec outils serveur, s’est interrompu et peut reprendre (pause_turn)
Refus : les classificateurs de sécurité sont intervenus (refusal)
Contexte dépassé : la fenêtre de contexte du modèle est pleine (model_context_window_exceeded)

Structure de la réponse

Message(
    id='msg_01XFDUDYJgAACzvnptvVoYEL',
    type='message',
    role='assistant',
    content=[
        ThinkingBlock(type='thinking', thinking='', signature='…'),   # si le modèle a réfléchi
        TextBlock(type='text', text='Bonjour ! Comment puis-je vous aider ?'),
    ],
    model='claude-sonnet-5-5',
    stop_reason='end_turn',
    usage=Usage(input_tokens=12, output_tokens=15, …),
)

Les champs importants :

content : la réponse générée, une liste de blocs ; sur les modèles actuels, un bloc de réflexion (thinking, au texte vide par défaut) peut précéder le bloc de texte, et une demande d’outil arrive dans un bloc tool_use
stop_reason : pourquoi le modèle s’est arrêté
usage : tokens consommés en entrée et en sortie, réflexion comprise ; c’est la base de votre facture

Pour extraire le texte, on parcourt les blocs et on garde ceux de type text. Le cours officiel lit message.content[0].text, ce qui suffit avec Claude Haiku 4.5 sans réflexion ; avec un modèle qui réfléchit, le premier bloc peut être la réflexion, et ce code plante.

texte = "".join(block.text for block in message.content if block.type == "text")

À vous de jouer

Repérer les étapes. Pour une application de chat de votre choix (site, appli mobile), dessinez les cinq étapes avec les vrais composants : qui est le client, où vit votre serveur, où est stockée la clé. Repérez l’étape où une fuite de clé serait possible si l’on sautait le serveur.

Lire un stop_reason. Écrivez une petite fonction verifier(message) qui lève une exception si stop_reason vaut max_tokens ou refusal, et renvoie le texte sinon. Elle vous servira dans tout le cours.

Sources officielles : Accessing the API (Claude Academy, Building with the Claude API) · Create a Message (référence de l’API : paramètres, blocs de réponse, valeurs de stop_reason)

Points clés à retenir

Cinq étapes : client, votre serveur, API Anthropic, traitement par le modèle, réponse ; la clé ne quitte jamais le serveur.
Trois paramètres obligatoires : model, max_tokens, messages, plus la clé d’API qui authentifie.
En interne : tokenisation, embeddings, contextualisation, génération token par token ; les modèles actuels peuvent réfléchir avant de répondre.
stop_reason dit pourquoi la génération s’est arrêtée ; votre code le vérifie avant d’utiliser une réponse.
content est une liste de blocs : on lit les blocs text, jamais content[0] à l’aveugle.