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

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    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-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-Reasons 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.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    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-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 system-Feld auf oberster Ebene für Anweisungen, die von Anfang an gelten sollen.

Eine System-Nachricht mitten in der Konversation hat dieselbe Autorität wie das system-Feld auf oberster Ebene, aber da sie am Ende des Nachrichtenverlaufs angehängt wird, macht sie kein gecachtes Präfix ungültig, das davor kam. Verwende das system-Feld auf oberster Ebene 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.

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

import base64
import httpx

# Option 1: Base64-kodiertes Bild
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    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: Per URL referenziertes Bild
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

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



Nächste Schritte