Utiliser l'API Messages

Anthropic propose deux façons de développer avec Claude, chacune adaptée à des cas d'usage différents :

Ce guide couvre les modèles courants d'utilisation de l'API Messages, notamment les requêtes de base, les conversations à plusieurs tours, les techniques de préremplissage et les capacités de vision. Pour les spécifications complètes de l'API, consultez la référence de l'API Messages. Pour le harnais d'agent géré, consultez plutôt la présentation de Claude Managed Agents.

Requête et réponse de base

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
  }
}

Les réponses de refus (stop_reason: "refusal") incluent également un objet stop_details identifiant la catégorie de politique qui a déclenché le refus, sur tous les modèles. Consultez Gérer les raisons d'arrêt pour la référence des champs et un exemple de code de gestion.

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.

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)

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

Rôle system dans les messages

Sur Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 4.8 et Claude Opus 5, vous pouvez inclure des messages avec "role": "system" après un tour utilisateur (sous réserve des règles de placement) afin d'ajouter une nouvelle instruction système en cours de conversation. Un message system ne peut pas être la première entrée de messages. Pour les instructions qui s'appliquent dès le début, utilisez le champ system de premier niveau.

Un message système en cours de conversation a la même autorité que le champ system de premier niveau, mais comme il est ajouté à la fin de l'historique des messages, il n'invalide aucun préfixe mis en cache qui le précède. Utilisez le champ system de premier niveau pour les instructions qui doivent s'appliquer dès le tout premier tour, et un message système en cours de conversation pour les instructions qui ne deviennent pertinentes que plus tard.

Consultez Messages système en cours de conversation pour le guide complet, y compris la manière de les combiner avec la mise en cache des prompts.

Préremplir la réponse 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. Utilisez cette technique pour façonner la réponse de Claude. L'exemple suivant utilise "max_tokens": 1 pour obtenir de Claude une seule réponse à choix multiple.

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)

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

Vision

Claude peut lire à la fois du texte et des images dans les requêtes. Vous pouvez fournir des images en utilisant les types de source base64, url ou file. Le type de source file référence une image téléversée via l'API Files. Les types de médias pris en charge sont image/jpeg, image/png, image/gif et image/webp. Consultez le guide de vision pour plus de détails.

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(message)

# 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(message_from_url)

{
  "id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

Étapes suivantes