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 pour travailler avec l’API Messages, notamment les requêtes de base, les conversations à plusieurs tours, les techniques de « prefill » (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 MessagesAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir.. Pour utiliser plutôt le harnais d’agent géré, consultez 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 ayant déclenché le refus, sur tous les modèles. Consultez Gérer les raisons d’arrêt pour la référence du champ et un exemple de code de gestion.

Plusieurs tours de conversation

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 précédents ne doivent pas nécessairement provenir réellement de Claude. Vous pouvez utiliser des messages assistant synthétiques.

Avec les fils de messages, en bêta, l’API peut conserver la conversation, de sorte que chaque requête ultérieure n’envoie que les nouveaux messages. Un fil expire 5 minutes après sa dernière requête et est supprimé au plus tard 1 heure après sa dernière utilisation.

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 système dans les messages

Vous pouvez inclure des messages avec "role": "system" après un tour utilisateur pour ajouter une nouvelle instruction système en cours de conversation, sous réserve des règles de placement. Cela fonctionne sur Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5 et Claude Haiku 5.5. Un message system porteur de contenu ne peut pas être la première entrée de messages. Utilisez le champ system de niveau supérieur pour les instructions qui s’appliquent dès le début.

Un message système en cours de conversation a la même autorité que le champ system de niveau supérieur, 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 niveau supérieur 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 en 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 de Claude une seule réponse à choix multiples.

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 à l’aide des types de source base64, url ou file. Le type de source file fait référence à une image téléversée via l’API Files. Les types de média pris en charge sont image/jpeg, image/png, image/gif et image/webp. Consultez le guide 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

Disponibilité