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, darunter grundlegende Anfragen, mehrstufige Gespräche, Prefill-Techniken und Vision-Fähigkeiten. Die vollständigen API-Spezifikationen findest du in der Messages API-Referenz. Informationen zum verwalteten Agent-Harness findest du stattdessen in der Übersicht zu Claude Managed Agents.

Grundlegende Anfrage und Antwort

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

Ablehnungsantworten (stop_reason: "refusal") enthalten bei jedem Modell zusätzlich ein stop_details-Objekt, das die Richtlinienkategorie angibt, die die Ablehnung ausgelöst hat. Siehe Umgang mit Stop-Reasons für die Feldreferenz und Beispielcode zur Behandlung.

Mehrere Gesprächsrunden

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

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

System-Rolle in Nachrichten

Bei 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 und Claude Sonnet 5.5 kannst du nach einer Benutzerrunde Nachrichten mit "role": "system" einfügen (unter Beachtung der Platzierungsregeln), um mitten im Gespräch eine neue Systemanweisung hinzuzufügen. Eine system-Nachricht kann nicht der erste Eintrag in messages sein. Verwende das system-Feld auf oberster Ebene für Anweisungen, die von Anfang an gelten.

Eine Systemnachricht mitten im Gespräch hat dieselbe Autorität wie das Top-Level-Feld system, aber da sie an das Ende des Nachrichtenverlaufs angehängt wird, macht sie keinen zwischengespeicherten Präfix ungültig, der vor ihr kam. Verwende das Top-Level-Feld system für Anweisungen, die ab dem allerersten Turn gelten sollen, und eine Systemnachricht mitten im Gespräch für Anweisungen, die erst später relevant werden.

Siehe Systemnachrichten mitten im Gespräch für den vollständigen Leitfaden, einschließlich der Kombination mit „prompt caching“ (Prompt-Caching).

Vorausfüllen von Claudes Antwort

Du kannst einen Teil von Claudes Antwort an der letzten Position der Liste der Eingabenachrichten vorausfüllen. Verwende diese Technik, 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 in Anfragen sowohl Text als auch Bilder lesen. Du kannst Bilder über die Quelltypen base64, url oder file bereitstellen. 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 httpx2

# Option 1: Base64-kodiertes Bild
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: Per URL referenziertes Bild
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
  }
}

Nächste Schritte