Utilisation de 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 multi-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.



Requête et réponse de base

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

Sur Claude Opus 4.7 et les modèles ultérieurs, 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. Consultez Gestion des raisons d'arrêt pour la référence des champs et un exemple de code de gestion.



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.

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



Rôle système dans les messages

Sur Claude Opus 4.8, vous pouvez inclure des messages avec "role": "system" après un tour utilisateur (sous réserve des règles de placement) pour ajouter une nouvelle instruction système en cours de conversation. Un message system ne peut pas être la première entrée dans 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 comment le combiner avec la mise en cache des prompts.



Mettre des mots dans la bouche 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. 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.

{
  "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. Les images peuvent être fournies en utilisant les 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édias pris en charge sont image/jpeg, image/png, image/gif et image/webp. Consultez le guide de vision pour plus de détails.

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}



Utilisation d'outils et utilisation de l'ordinateur

Consultez le guide d'utilisation d'outils pour des exemples d'utilisation des outils avec l'API Messages. Consultez le guide d'utilisation de l'ordinateur pour des exemples de contrôle d'environnements d'ordinateur de bureau avec l'API Messages. Pour une sortie JSON garantie, consultez Sorties structurées. Pour un budget de tokens indicatif sur l'ensemble d'une boucle agentique, définissez output_config.task_budget ; consultez Budgets de tâche.