Le cycle d'une requete API

Comprendre le trajet d’une requete est essentiel pour bien utiliser l’API Claude. Voyons chaque etape.

Les 5 etapes d’une requete

Client (navigateur/app)
        ↓
Votre serveur backend
        ↓
API Anthropic
        ↓
Traitement par le modele
        ↓
Reponse renvoyee

1. Le client (navigateur, application mobile, script) envoie une demande a votre serveur
2. Votre serveur recoit la demande et construit la requete API avec votre cle
3. L’API Anthropic valide la requete et la transmet au modele
4. Le modele traite le prompt et genere une reponse
5. La reponse remonte : modele → API → votre serveur → client

Pourquoi un serveur intermediaire ?

Ne jamais exposer votre cle API cote client. Si votre cle se retrouve dans le code JavaScript d’une page web, n’importe qui peut la recuperer et l’utiliser a vos frais. Votre serveur backend sert de rempart : c’est lui qui detient la cle et communique avec l’API.

Les champs essentiels d’une requete

Chaque requete a l’API necessite au minimum :

import anthropic

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

message = client.messages.create(
    model="claude-sonnet-4-20250514",   # Le modele a utiliser
    max_tokens=1024,                     # Nombre max de tokens en sortie
    messages=[                           # La conversation
        {"role": "user", "content": "Bonjour Claude !"}
    ]
)

Les trois parametres obligatoires :

• model : quel modele utiliser
• max_tokens : limite de tokens pour la reponse (securite anti-explosion de couts)
• messages : la liste des messages de la conversation

Ce que fait Claude en interne

Quand le modele recoit votre prompt, il passe par plusieurs etapes :

1. Tokenisation : le texte est decoupe en tokens (morceaux de mots). “Bonjour” peut devenir un ou plusieurs tokens
2. Embedding : chaque token est converti en un vecteur numerique
3. Contextualisation : le modele analyse les relations entre tous les tokens via le mecanisme d’attention
4. Generation : le modele predit le prochain token, puis le suivant, et ainsi de suite jusqu’a avoir termine

Quand Claude arrete-t-il de generer ?

Trois cas possibles :

• max_tokens atteint : la reponse est coupee a la limite que vous avez definie (stop_reason: max_tokens)
• Fin naturelle : le modele estime avoir termine sa reponse (stop_reason: end_turn)
• Sequence d’arret : vous avez defini une sequence de stop personnalisee et le modele l’a generee (stop_reason: stop_sequence)

Structure de la reponse

Message(
    id='msg_01XFDUDYJgAACzvnptvVoYEL',
    type='message',
    role='assistant',
    content=[
        TextBlock(type='text', text='Bonjour ! Comment puis-je vous aider ?')
    ],
    model='claude-sonnet-4-20250514',
    stop_reason='end_turn',
    usage=Usage(
        input_tokens=12,
        output_tokens=15
    )
)

Les champs importants :

• content : la reponse generee (liste de blocs, generalement un seul TextBlock)
• stop_reason : pourquoi le modele s’est arrete
• usage : nombre de tokens consommes (entree + sortie) — utile pour suivre vos couts

Pour extraire le texte de la reponse :

reponse = message.content[0].text

Dans la prochaine lecon, nous obtiendrons une cle API pour passer a la pratique.