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/l'API Messages de base, l'utilisation d'outils, le streaming, la réflexion, et rien d'autre.

Modèles

Recommended default for most work, including complex agentic coding: Claude Opus 5.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2.5x Claude Opus 5.5 pricing: Claude Fable 5.1: claude-fable-5-1
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5.5: claude-sonnet-5-5
Previous Sonnet model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 5.5: claude-haiku-5-5
Previous Haiku model: Claude Haiku 4.5: claude-haiku-4-5-20251001

Appeler l'API

Requête et réponse de base

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    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-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Plusieurs tours de conversation

L'API Messages est « stateless » (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 précédents ne doivent pas nécessairement provenir réellement de Claude. Vous pouvez utiliser des messages assistant synthétiques.

import anthropic

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

Préremplir la réponse de Claude

Vous pouvez préremplir une partie de la réponse de Claude dans la dernière position de la liste des messages d'entrée. Utilisez cette technique pour orienter la réponse de Claude. L'exemple suivant utilise "max_tokens": 1 pour obtenir une seule réponse à choix multiple de la part de Claude.

import anthropic

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édias image/jpeg, image/png, image/gif et image/webp.

import anthropic
import base64
import httpx2

# Option 1 : image encodée en Base64
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    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(next(block.text for block in message.content if block.type == "text"))

# Option 2 : image référencée par URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))

Réflexion

La réflexion peut parfois aider Claude à accomplir des tâches très difficiles. Le mécanisme actuel est l'« adaptive thinking » (réflexion adaptative) (thinking: {"type": "adaptive"}) : Claude détermine quand et combien réfléchir, et vous orientez la profondeur de la réflexion avec le paramètre effort plutôt qu'avec un budget de tokens. La réflexion adaptative est prise en charge sur les modèles Claude 4.6 et ultérieurs ainsi que sur Claude Mythos Preview. Sur les modèles Claude 5 et Claude Mythos Preview, la réflexion est activée par défaut lorsque le paramètre thinking est omis.

La température doit être définie à 1 (ou laissée non définie) chaque fois que la réflexion est activée, sur tous les modèles. Sur les modèles Claude 4.7 et ultérieurs ainsi que sur Claude Mythos Preview, temperature est déprécié et seule sa valeur par défaut est acceptée, même lorsque la réflexion est désactivée.

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

• Claude Opus 5.5 (claude-opus-5-5, réflexion adaptative uniquement, toujours activée)
• Claude Sonnet 5.5 (claude-sonnet-5-5, réflexion adaptative uniquement, activée par défaut)
• Claude Haiku 5.5 (claude-haiku-5-5, réflexion adaptative uniquement, activée par défaut)
• Claude Opus 5 (claude-opus-5, réflexion adaptative uniquement, activée par défaut)
• Claude Sonnet 5 (claude-sonnet-5, réflexion adaptative uniquement, activée par défaut)
• Claude Opus 4.8 (claude-opus-4-8, réflexion adaptative uniquement)
• Claude Opus 4.7 (claude-opus-4-7, réflexion adaptative uniquement)
• Claude Opus 4.6 (claude-opus-4-6, réflexion adaptative ou réflexion manuelle héritée)
• Claude Sonnet 4.6 (claude-sonnet-4-6, réflexion adaptative ou réflexion manuelle héritée)
• Claude Opus 4.5 (claude-opus-4-5-20251101, réflexion manuelle héritée uniquement)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929, déprécié, réflexion manuelle héritée uniquement)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001, réflexion manuelle héritée uniquement)

Fonctionnement de la réflexion

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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 contient des blocs de réflexion résumés et des blocs de texte.
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

La réflexion étendue manuelle, ou « manual extended thinking » (thinking: {"type": "enabled", "budget_tokens": N}), est le mécanisme hérité. Elle fonctionne uniquement sur les modèles Claude 4 à 4.6 qui prennent en charge la réflexion ; les modèles Claude 4.7 et ultérieurs rejettent type: enabled avec une erreur 400 et utilisent à la place la réflexion adaptative. Avec la réflexion étendue manuelle, budget_tokens définit le nombre maximal de tokens que Claude est autorisé à utiliser pour son processus de raisonnement interne ; la limite s'applique aux tokens de réflexion complets, et non à la sortie résumée. À 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 rédiger sa réponse une fois la réflexion terminée.

Réflexion avec utilisation d'outils

La réflexion peut être utilisée conjointement avec l'utilisation d'outils (« tool use »), ce qui permet à 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 assistant.

Préserver les 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-5-5",
    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-5-5",
    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 en plus du 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

L'« interleaved thinking » (réflexion entrelacée) permet à Claude de réfléchir entre les appels d'outils, en raisonnant sur les résultats des outils avant de déterminer l'étape suivante.

Sur les modèles plus anciens qui utilisent la réflexion étendue manuelle (modèles Claude 4, 4.5 et Sonnet 4.6), activez la réflexion entrelacée en ajoutant 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:
    match block.type:
        case "thinking":
            print(f"Thinking: {block.thinking}")
        case "tool_use":
            print(f"Tool call: {block.name}({block.input})")
        case "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 manuelle classique), budget_tokens peut dépasser le paramètre max_tokens, car budget_tokens représente dans ce cas le budget total de tous les blocs de réflexion au sein d'un même tour de l'assistant.

Utilisation d'outils

Spécifier les outils client

Les outils client sont spécifiés dans le paramètre de premier niveau 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 comportant 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 indiquant cet outil dans le champ tool_choice :

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

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

• auto permet à Claude de déterminer 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 le moindre outil.

Sur Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 et Claude Mythos 5.1, any et tool renvoient une erreur 400. Laissez tool_choice sur auto et définissez "strict": true dans la définition de l'outil pour garantir que tout appel effectué par Claude correspond au input_schema de l'outil. Consultez Utilisation stricte des outils.

Sortie JSON

Les outils ne doivent pas nécessairement être des fonctions client. Vous pouvez utiliser des outils chaque fois que vous souhaitez que le modèle renvoie une sortie JSON conforme à un schéma fourni.

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.

Gérer les blocs de contenu d'utilisation d'outils et de résultats d'outils

Gérer les résultats des outils client

La réponse a un stop_reason égal à tool_use et un ou plusieurs blocs de contenu tool_use qui comprennent :

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

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

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

1. Extraire name, id et input du bloc tool_use.
2. Exécuter l'outil réel de 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"
    }
  ]
}

Gérer le motif d'arrêt max_tokens

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

Gérer le motif d'arrêt pause_turn

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

Résolution des erreurs

Erreur d'exécution d'outil

Si l'outil lui-même génère une erreur pendant son 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), relancez la requête avec des valeurs description plus détaillées dans vos définitions d'outils.

Streaming des messages

Lors de la création d'un Message, vous pouvez définir "stream": true pour diffuser la réponse de manière incrémentale en streaming à l'aide de « 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-5-5",
) 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 content_block_start, un ou plusieurs événements content_block_delta, et content_block_stop.
3. Un ou plusieurs événements message_delta, indiquant des modifications de premier niveau de 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 de 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 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-5-5", "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"}