

Introduction à l'utilisation de l'API pour Claude

Ce guide est conçu pour donner à Claude les bases de l'utilisation de l'API Claude. Il fournit des explications et des exemples sur les identifiants de modèles et l'API Messages de base, l'utilisation d'outils, le streaming, la réflexion étendue, et rien d'autre.



Modèles

Smartest model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 4.6: claude-sonnet-4-6
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001



Appeler l'API



Requête et réponse de base

import anthropic
import os

message = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
).messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}



Tours de conversation multiples

L'API Messages est sans état, ce qui signifie que vous envoyez toujours l'historique complet de la conversation à l'API. Vous pouvez utiliser ce modèle pour construire une conversation au fil du temps. Les tours de conversation antérieurs n'ont pas nécessairement besoin de provenir réellement de Claude. Vous pouvez utiliser des messages assistant synthétiques.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)



Mettre des mots dans la bouche de Claude

Vous pouvez pré-remplir une partie de la réponse de Claude à la dernière position de la liste des messages d'entrée. Cela peut être utilisé pour façonner la réponse de Claude. L'exemple ci-dessous utilise "max_tokens": 1 pour obtenir une seule réponse à choix multiple de Claude.

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message.content[0].text)



Vision

Claude peut lire à la fois du texte et des images dans les requêtes. Les types de source base64 et url sont tous deux pris en charge pour les images, ainsi que les types de média image/jpeg, image/png, image/gif et image/webp.

import anthropic
import base64
import httpx

# Option 1 : Image encodée en base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message.content[0].text)

# Option 2 : Image référencée par URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url.content[0].text)



Réflexion étendue

La « extended thinking » (réflexion étendue) peut parfois aider Claude avec des tâches très difficiles. Sur les modèles antérieurs à Claude Opus 4.7, la température doit être définie à 1 lorsque la réflexion étendue est activée.

La réflexion étendue est prise en charge dans les modèles suivants :

• Claude Opus 4.8 (claude-opus-4-8, réflexion adaptative uniquement)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)



Fonctionnement de la réflexion étendue

Lorsque la réflexion étendue est activée, Claude crée des blocs de contenu thinking dans lesquels il produit son raisonnement interne. La réponse de l'API inclura des blocs de contenu thinking, suivis de blocs de contenu text.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# La réponse contiendra des blocs de réflexion résumés et des blocs de texte
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Lors de l'utilisation de la réflexion étendue manuelle (type: enabled), le paramètre budget_tokens détermine le nombre maximal de tokens que Claude est autorisé à utiliser pour son processus de raisonnement interne. Dans les modèles Claude 4 et ultérieurs, cette limite s'applique aux tokens de réflexion complets, et non à la sortie résumée. Des budgets plus importants peuvent améliorer la qualité des réponses en permettant une analyse plus approfondie pour les problèmes complexes. À moins que vous n'utilisiez la réflexion entrelacée, budget_tokens doit être inférieur à max_tokens afin que Claude dispose d'espace pour écrire sa réponse une fois la réflexion terminée.



Réflexion étendue avec utilisation d'outils

La réflexion étendue peut être utilisée conjointement avec l'utilisation d'outils, permettant à Claude de raisonner sur la sélection des outils et le traitement des résultats.

Limitations importantes :

1. Limitation du choix d'outil : Prend uniquement en charge tool_choice: {"type": "auto"} (par défaut) ou tool_choice: {"type": "none"}.
2. Préservation des blocs de réflexion : Pendant l'utilisation d'outils, vous devez renvoyer les blocs thinking à l'API pour le dernier message de l'assistant.



Préservation des blocs de réflexion

import anthropic

client = anthropic.Anthropic()

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city name."}},
        "required": ["location"],
    },
}

weather_data = {"temperature": 72}

# Première requête - Claude répond avec une réflexion et une demande d'outil
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Extraire le bloc de réflexion et le bloc d'utilisation d'outils
thinking_block = next(
    (block for block in response.content if block.type == "thinking"), None
)
tool_use_block = next(
    (block for block in response.content if block.type == "tool_use"), None
)

# Deuxième requête - Inclure le bloc de réflexion et le résultat de l'outil
continuation = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Notez que le thinking_block est transmis ainsi que le tool_use_block
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)

for block in continuation.content:
    if block.type == "text":
        print(block.text)



Réflexion entrelacée

La réflexion étendue avec utilisation d'outils dans les modèles Claude 4 prend en charge la « interleaved thinking » (réflexion entrelacée), qui permet à Claude de réfléchir entre les appels d'outils. Pour l'activer sur les modèles Claude 4, 4.5 et Sonnet 4.6, ajoutez l'en-tête bêta interleaved-thinking-2025-05-14 à votre requête API.

import anthropic

client = anthropic.Anthropic()

calculator_tool = {
    "name": "calculator",
    "description": "Perform arithmetic calculations.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The math expression to evaluate.",
            }
        },
        "required": ["expression"],
    },
}

database_tool = {
    "name": "database_query",
    "description": "Query the product database.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "The database query."}
        },
        "required": ["query"],
    },
}

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[calculator_tool, database_tool],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
        }
    ],
    betas=["interleaved-thinking-2025-05-14"],
)

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool call: {block.name}({block.input})")
    elif block.type == "text":
        print(f"Response: {block.text}")

Avec la réflexion entrelacée et UNIQUEMENT avec la réflexion entrelacée (pas avec la réflexion étendue standard), le budget_tokens peut dépasser le paramètre max_tokens, car budget_tokens représente dans ce cas le budget total pour tous les blocs de réflexion au sein d'un seul tour de l'assistant.



Utilisation d'outils



Spécification des outils client

Les outils client sont spécifiés dans le paramètre de niveau supérieur tools de la requête API. Chaque définition d'outil comprend :

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}



Bonnes pratiques pour les définitions d'outils

Fournissez des descriptions extrêmement détaillées. C'est de loin le facteur le plus important pour les performances des outils. Vos descriptions doivent expliquer chaque détail de l'outil, notamment :

• Ce que fait l'outil
• Quand il doit être utilisé (et quand il ne doit pas l'être)
• Ce que signifie chaque paramètre et comment il affecte le comportement de l'outil
• Toute mise en garde ou limitation importante

Envisagez d'utiliser input_examples pour les outils complexes. Pour les outils avec des objets imbriqués, des paramètres optionnels ou des entrées sensibles au format, vous pouvez fournir des exemples concrets à l'aide du champ input_examples (bêta). Cela aide Claude à comprendre les modèles d'entrée attendus. Consultez Fournir des exemples d'utilisation d'outils pour plus de détails.

Exemple d'une bonne description d'outil :

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}



Contrôler la sortie de Claude



Forcer l'utilisation d'outils

Vous pouvez forcer Claude à utiliser un outil spécifique en spécifiant l'outil dans le champ tool_choice :

tool_choice = {"type": "tool", "name": "get_weather"}

Lorsque vous travaillez avec le paramètre tool_choice, quatre options sont possibles :

• auto permet à Claude de décider s'il doit appeler ou non l'un des outils fournis (par défaut).
• any indique à Claude qu'il doit utiliser l'un des outils fournis.
• tool force Claude à toujours utiliser un outil particulier.
• none empêche Claude d'utiliser des outils.



Sortie JSON

Les outils n'ont pas nécessairement besoin d'être des fonctions client. Vous pouvez utiliser des outils chaque fois que vous souhaitez que le modèle renvoie une sortie JSON qui suit un schéma fourni.



Chaîne de raisonnement

Lors de l'utilisation d'outils, Claude affichera souvent sa « chain of thought » (chaîne de raisonnement), c'est-à-dire le raisonnement étape par étape qu'il utilise pour décomposer le problème et décider quels outils utiliser.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}



Utilisation d'outils en parallèle

Par défaut, Claude peut utiliser plusieurs outils pour répondre à une requête utilisateur. Vous pouvez désactiver ce comportement en définissant disable_parallel_tool_use=true.



Gestion des blocs de contenu tool use et tool result



Gestion des résultats des outils client

La réponse aura un stop_reason de tool_use et un ou plusieurs blocs de contenu tool_use qui incluent :

• id : Un identifiant unique pour ce bloc d'utilisation d'outil particulier.
• name : Le nom de l'outil utilisé.
• input : Un objet contenant l'entrée transmise à l'outil.

Lorsque vous recevez une réponse d'utilisation d'outil, vous devez :

1. Extraire le name, l'id et l'input du bloc tool_use.
2. Exécuter l'outil réel dans votre base de code correspondant à ce nom d'outil.
3. Poursuivre la conversation en envoyant un nouveau message avec un tool_result :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}



Gestion du stop reason max_tokens

Si la réponse de Claude est tronquée parce qu'elle a atteint la limite max_tokens pendant l'utilisation d'outils, réessayez la requête avec une valeur max_tokens plus élevée.



Gestion du stop reason pause_turn

Lors de l'utilisation d'outils serveur comme la recherche web, l'API peut renvoyer un stop reason pause_turn. Poursuivez la conversation en renvoyant la réponse mise en pause telle quelle dans une requête ultérieure.



Dépannage des erreurs



Erreur d'exécution d'outil

Si l'outil lui-même génère une erreur pendant l'exécution, renvoyez le message d'erreur avec "is_error": true :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}



Nom d'outil invalide

Si la tentative d'utilisation d'un outil par Claude est invalide (par exemple, des paramètres requis manquants), réessayez la requête avec des valeurs description plus détaillées dans vos définitions d'outils.



Messages en streaming

Lors de la création d'un Message, vous pouvez définir "stream": true pour diffuser progressivement la réponse en utilisant des « server-sent events » (événements envoyés par le serveur), ou SSE.



Streaming avec les SDK

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-4-8",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)



Types d'événements

Chaque événement envoyé par le serveur comprend un type d'événement nommé et des données JSON associées. Chaque flux utilise le déroulement d'événements suivant :

1. message_start : contient un objet Message avec un content vide.
2. Une série de blocs de contenu, chacun avec un content_block_start, un ou plusieurs événements content_block_delta, et un content_block_stop.
3. Un ou plusieurs événements message_delta, indiquant des modifications de niveau supérieur à l'objet Message final.
4. Un événement final message_stop.

Avertissement : Les décomptes de tokens affichés dans le champ usage de l'événement message_delta sont cumulatifs.



Types de delta de bloc de contenu



Delta de texte

{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Hello frien" }
}



Delta JSON d'entrée

Pour les blocs de contenu tool_use, les deltas sont des chaînes JSON partielles :

{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}



Delta de réflexion

Lors de l'utilisation de la réflexion étendue avec le streaming :

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}



Exemple de requête de streaming de base

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}