Verwendung der Messages API

Anthropic bietet zwei Möglichkeiten, mit Claude zu entwickeln, die jeweils für unterschiedliche Anwendungsfälle geeignet sind:

Dieser Leitfaden behandelt gängige Muster für die Arbeit mit der Messages API, einschließlich grundlegender Anfragen, mehrstufiger Konversationen, Prefill-Techniken und Vision-Funktionen. Die vollständigen API-Spezifikationen findest du in der Messages API-Referenz.

Grundlegende Anfrage und Antwort

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

Bei Claude Opus 4.7 und späteren Modellen enthalten Ablehnungsantworten (stop_reason: "refusal") auch ein stop_details-Objekt, das die Richtlinienkategorie identifiziert, die die Ablehnung ausgelöst hat. Siehe Umgang mit Stop-Gründen für die Feldreferenz und Beispielcode zur Behandlung.

Mehrere Konversationsrunden

Die Messages API ist zustandslos, was bedeutet, dass du immer den vollständigen Konversationsverlauf an die API sendest. Du kannst dieses Muster verwenden, um eine Konversation im Laufe der Zeit aufzubauen. Frühere Konversationsrunden müssen nicht unbedingt tatsächlich von Claude stammen. Du kannst synthetische assistant-Nachrichten verwenden.

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

System-Rolle in Nachrichten

Bei Claude Opus 4.8 kannst du Nachrichten mit "role": "system" nach einer User-Runde einfügen (vorbehaltlich der Platzierungsregeln), um mitten in einer Konversation eine neue Systemanweisung hinzuzufügen. Eine system-Nachricht darf nicht der erste Eintrag in messages sein; verwende das Top-Level-Feld system für Anweisungen, die von Anfang an gelten sollen.

Eine System-Nachricht mitten in der Konversation hat dieselbe Autorität wie das Top-Level-Feld system, aber da sie am Ende des Nachrichtenverlaufs angehängt wird, macht sie keinen gecachten Präfix ungültig, der davor kam. Verwende das Top-Level-Feld system für Anweisungen, die ab der allerersten Runde gelten sollen, und eine System-Nachricht mitten in der Konversation für Anweisungen, die erst später relevant werden.

Siehe System-Nachrichten mitten in der Konversation für den vollständigen Leitfaden, einschließlich der Kombination mit Prompt-Caching.

Claude Worte in den Mund legen

Du kannst einen Teil von Claudes Antwort an der letzten Position der Eingabenachrichtenliste vorausfüllen. Dies kann verwendet werden, um Claudes Antwort zu formen. Das folgende Beispiel verwendet "max_tokens": 1, um eine einzelne Multiple-Choice-Antwort von Claude zu erhalten.

{
  "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 kann sowohl Text als auch Bilder in Anfragen lesen. Bilder können mit den Quelltypen base64, url oder file bereitgestellt werden. Der Quelltyp file verweist auf ein Bild, das über die Files API hochgeladen wurde. Unterstützte Medientypen sind image/jpeg, image/png, image/gif und image/webp. Weitere Details findest du im Vision-Leitfaden.

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

Tool-Nutzung und Computer-Nutzung

Siehe den Leitfaden zur Tool-Nutzung für Beispiele, wie du Tools mit der Messages API verwendest. Siehe den Leitfaden zur Computer-Nutzung für Beispiele, wie du Desktop-Computerumgebungen mit der Messages API steuerst. Für garantierte JSON-Ausgabe siehe Strukturierte Ausgaben. Für ein empfohlenes Token-Budget über eine vollständige agentische Schleife hinweg setze output_config.task_budget; siehe Task-Budgets.