Claude · Die Messages API: Ihre ersten echten Calls

Im Chatfenster haben Sie Claude kennengelernt. Mit der Messages APIAPIApplication Programming Interface: eine standardisierte Schnittstelle, über die Anwendungen kommunizieren und Daten austauschen, ohne die interne Funktionsweise der jeweils anderen zu kennen.Vollständige Definition ansehen → setzen Sie es produktiv ein: dasselbe Modell, ohne UI. Sie senden einen strukturierten Request und erhalten strukturierten Output zurück, und zwar aus Ihrem eigenen Code, nach Ihrem eigenen Zeitplan, in Ihrem eigenen Produkt.

Einen generischen „ersten API-Call“ haben Sie schon einmal gemacht. Diese Lektion spart sich deshalb das Drumherum und behandelt, was spezifisch für Claude ist: wie der Request aufgebaut ist, warum der system-Prompt dort sitzt, wo ererDas Verhältnis von Interaktionen (Likes, Kommentare, Shares) zur Reichweite eines Inhalts. Zeigt, wie stark die Zielgruppe reagiert, gemessen an der Zahl der Personen, die den Inhalt gesehen haben.Vollständige Definition ansehen → sitzt, wie Sie verlässliche Formate bekommen und wie Sie lange Antworten streamen, damit Ihre Nutzer nicht auf einen leeren Bildschirm starren.

Der Aufbau eines Claude-Requests

Jeder Call an die Messages API besteht aus wenigen Teilen:

• model: welches Claude Sie wollen (eine Sonnet-, Opus- oder Haiku-Variante). Sonnet ist das Arbeitspferd für den Alltag, Opus das leistungsfähigste Modell für schwieriges Reasoning, Haiku das schnelle, günstige.
• max_tokens: die Obergrenze, wie viele TokensTokensEin Token ist die grundlegende Texteinheit, die Sprachmodelle verarbeiten, oft ein Wortfragment, ein ganzes Wort oder ein Satzzeichen und nicht ein einzelnes Zeichen.Vollständige Definition ansehen → Claude in seiner Antwort erzeugen darf. Das ist ein Höchstwert, kein Zielwert. Die Antwort wird dadurch nicht aufgefüllt, nur begrenzt.
• messages: die Konversation als Liste von Turns. Jeder Turn hat eine role (user oder assistant) und content.
• system (optional, aber wichtig): ein Parameter auf oberster Ebene, getrennt von der messages-Liste. Rolle, Tonalität und Regeln gehören hierhin.

Der letzte Punkt bringt Umsteiger von anderen APIs oft ins Stolpern. In der Messages API ist der System-Prompt keine Message mit role: "system". Er ist ein eigenes Feld im Request. Anthropic-Modelle sind auf diese Struktur trainiert, und wenn Sie dauerhafte Anweisungen in system halten, statt sie in einen User-Turn zu packen, befolgt Claude sie zuverlässiger.

Zur Erinnerung: Ein Token ist das Textstück, in dem das Modell liest und schreibt (etwa ein paar Zeichen). Sie zahlen pro Input-Token und pro Output-Token, max_tokens ist also auch ein Kostenregler.

Ihr erster echter Call

Hier ein vollständiger, lauffähiger Call. Installieren Sie zuerst das SDK mit pip install anthropic und setzen Sie Ihren Key als Umgebungsvariable ANTHROPIC_API_KEY.

import anthropic

client = anthropic.Anthropic()  # liest ANTHROPIC_API_KEY aus der Umgebung

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a precise release-notes editor. Reply in tight bullet points.",
    messages=[
        {
            "role": "user",
            "content": "Summarize: we shipped SSO, fixed a billing bug, and removed the legacy export.",
        }
    ],
)

print(response.content[0].text)

Sehen Sie sich jetzt an, was zurückkommt. Die Response ist ein Objekt, kein roher String. Ihr content ist eine Liste von Content-Blöcken, weil eine einzelne Antwort mehr als eine Art von Block enthalten kann (Text und später Tool-Use-Anfragen). Bei einer reinen Textantwort lesen Sie response.content[0].text. Außerdem erhalten Sie response.usage mit den Input- und Output-Tokenzahlen sowie response.stop_reason, das Ihnen sagt, *warum* Claude aufgehört hat. end_turn heißt, die Antwort ist natürlich zu Ende. max_tokens heißt, Ihre Obergrenze wurde erreicht und die Antwort abgeschnitten. Prüfen Sie stop_reason in Produktion immer, denn eine abgeschnittene Antwort, die Sie als vollständig behandeln, ist ein stiller Bug.

Model-IDs ändern sich mit der Zeit. Prüfen Sie deshalb die aktuellen Namen und Parameter in der offiziellen Messages API reference, bevor Sie ausliefern.

Die Konversation tragen Sie selbst

Die API ist stateless. Claude erinnert sich nicht an Ihren letzten Call. *Sie* halten die Konversation, indem Sie jeden Turn an die messages-Liste anhängen und das Ganze erneut senden.

Ein Austausch über mehrere Turns ist einfach eine Liste:

messages = [
    {"role": "user", "content": "What's a good index for a time-series table?"},
    {"role": "assistant", "content": "Start with a composite index on (device_id, ts)."},
    {"role": "user", "content": "Why that order and not (ts, device_id)?"},
]

Lassen Sie User- und Assistant-Turns abwechseln. Senden Sie zwei User-Turns hintereinander, fasst die API sie zu einem zusammen. Das funktioniert, macht Ihren Verlauf aber schwerer nachvollziehbar. Behandeln Sie die Liste als das eigentliche Transkript und hängen Sie nach jedem Call Claudes Antwort an.

Verlässliche Formate bekommen

Ältere Anleitungen lehren Prefilling: Die messages-Liste endet mit einem angefangenen assistant-Turn (etwa {), sodass Claude von dort weiterschreibt. Bauen Sie nicht darauf. Die neuesten Claude-Modelle lehnen einen vorausgefüllten letzten Assistant-Turn mit einem Fehler ab, und die Technik war immer ein Workaround.

Sie haben heute bessere Optionen:

• Für garantiertes JSON nutzen Sie Structured Outputs: Sie übergeben mit dem Request ein JSON-SchemaSchemaEin Schema ist der formale Bauplan, der festlegt, wie Daten in einer Datenbank, einer Datei oder einer Nachricht strukturiert, benannt, typisiert und miteinander verknüpft sind.Vollständige Definition ansehen →, und die Antwort wird darauf beschränkt. Den genauen Parameter finden Sie im structured outputs guide.
• Für leichtere Formatkontrolle nennen Sie das Format in system („Antworte mit genau drei Bullets, ohne Einleitung“) und zeigen ein kurzes Beispiel.
• Tool Use mit einem definierten Input-Schema ist ein weiterer solider Weg, typisierte Felder zurückzubekommen. Das behandeln wir später in diesem Modul.

Streaming für lange Antworten

Wenn Claude eine lange Antwort schreibt, wollen Sie nicht warten, bis alles fertig ist, bevor irgendetwas angezeigt wird. Beim Streaming kommt die Antwort in Stücken zurück, während sie generiert wird, der Text erscheint also Wort für Wort, wie in der Claude-App.

Tauschen Sie eine Methode aus und iterieren Sie:

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system="You are a technical writer. Be concrete.",
    messages=[{"role": "user", "content": "Explain database connection pooling."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()
    print("\n\nTokens used:", final.usage.output_tokens)

Die Methode stream() liefert einen Context Manager (den with-Block), der die Verbindung sauber schließt, auch wenn mitten im Stream etwas schiefgeht. Der Helper text_stream gibt Ihnen nur die Text-Deltas, und das ist meist genau das, was Sie für eine UI brauchen. Wenn die Schleife endet, setzt get_final_message() die vollständige Response wieder zusammen, sodass Sie trotzdem usage und stop_reason bekommen.

Streamen Sie immer dann, wenn eine Antwort lang werden kkDie durchschnittliche Zahl neuer Nutzer, die jeder bestehende Nutzer über Empfehlungen generiert. Über 1,0 verstärkt sich das Wachstum selbst und wird exponentiell.Vollständige Definition ansehen →önnte oder ein Mensch zusieht, wie sie ankommt. Für kurze Hintergrundjobs, bei denen nichts auf den Output wartet, ist der einfache create()-Call simpler und insgesamt genauso schnell.

Was Claude hier ausmacht

Einige Verhaltensweisen sollten Sie kennen, bevor Sie darauf aufbauen.

System-Prompts haben echtes Gewicht. Dauerhafte Anweisungen in system werden konsistenter befolgt als derselbe Text, versteckt in einer User-Message. Packen Sie das Beständige (Rolle, Output-Format, harte Constraints) in system und die Aufgabe pro Request in den User-Turn.

Langer Kontext ist in der Praxis nutzbar. Claude-Modelle unterstützen große Kontextfenster, groß genug für ganze Dokumente, lange Transkripte oder einen ordentlichen Teil einer Codebasis. Oft können Sie Quellmaterial also direkt übergeben, statt dafür Retrieval aufzubauen. Preise und Fenstergrößen ändern sich, prüfen Sie die aktuellen Zahlen deshalb in der Doku, statt sie auswendig zu lernen.

Dieselbe API treibt Tools und Agents an. Tool Use, die Connectors der Claude-Apps, MCP-Server und das Claude Agent SDK setzen alle auf diesem messages.create-Call auf. Tool Use bedeutet zusätzliche Content-Block-Typen, die durch die Request- und Response-Struktur laufen, die Sie bereits kennen.

Fehler lesen und ein guter Client sein

Echte Calls schlagen manchmal fehl. Diese begegnen Ihnen zuerst:

• 401 (Authentifizierung): Ihr ANTHROPIC_API_KEY fehlt, ist falsch oder nicht in die Umgebung geladen. Prüfen Sie, ob die Variable gesetzt ist (ohne den Key selbst auszugeben).
• 429 (Rate Limit) und 529 (überlastet): Sie senden zu schnell, oder der Dienst ist kurzzeitig ausgelastet. Die Lösung ist in beiden Fällen dieselbe: Tempo drosseln und erneut versuchen.

Das SDK wiederholt bestimmte Fehlschläge bereits mit exponentiellem Backoff. Sie sollten Calls aber trotzdem kapseln und die Fälle behandeln, bei denen das SDK aufgibt:

import anthropic

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        messages=[{"role": "user", "content": "One sentence on idempotency."}],
    )
    print(response.content[0].text)
except anthropic.RateLimitError:
    print("Rate limited. Slow down and retry with backoff.")
except anthropic.APIStatusError as exc:
    print(f"API error {exc.status_code}: {exc.message}")

Fangen Sie RateLimitError gezielt ab, wenn Sie eigenes Backoff wollen, und greifen Sie für jeden anderen Fehlerstatus auf APIStatusError zurück. Das ist der Unterschied zwischen einem Skript, das beim ersten Schluckauf abstürzt, und einem Service, der einen vollen Nachmittag übersteht.

Wo Ihre Keys hingehören

Das erwischt viele schon am ersten Tag. Ihr API-Key ist ein Geheimnis, an dem Ihre Abrechnung hängt. Hardcoden Sie ihn nie im Quellcode, committen Sie ihn nie und liefern Sie ihn nie in einer Browser-App aus, in der Nutzer ihn lesen können. Halten Sie ihn in einer Umgebungsvariable oder einem Secrets Manager. Der Konstruktor anthropic.Anthropic() liest ANTHROPIC_API_KEY ohne Argument ein, deshalb bleibt der Key in allen Snippets oben implizit. Brauchen Sie Calls aus dem Browser, leiten Sie sie über ein kleines Backend, das den Key hält.

Keys erzeugen und rotieren Sie in der Claude Console, und den SDK-Quellcode finden Sie unter github.com/anthropics, falls Sie nachlesen wollen, wie Retries und Streaming implementiert sind.

Das Wichtigste in Kürze

• Legen Sie dauerhafte Anweisungen in den system-Parameter auf oberster Ebene, nicht in eine User-Message. User-Turns sind für die eigentliche Aufgabe da.
• Prüfen Sie immer stop_reason und usage. Eine bei max_tokens abgeschnittene Antwort sieht vollständig aus, ist es aber nicht, und die Tokenzahlen sind Ihr Kostensignal.
• Die API ist stateless. Sie tragen die Konversation also selbst und lassen die Turns abwechseln.
• Verzichten Sie bei aktuellen Modellen auf Prefilling. Nutzen Sie Structured Outputs, wenn Sie garantiertes JSON brauchen.
• Nutzen Sie messages.stream() mit text_stream, wenn ein Mensch wartet, und create() für stille Hintergrundjobs.
• Tool Use, Connectors, MCPMCPEin offener Standard, mit dem KI-Assistenten einheitlich und kontrolliert an die Werkzeuge und Daten des Unternehmens angebunden werden, statt jede Integration einzeln zu bauen.Vollständige Definition ansehen → und das Agent SDK laufen alle durch dieselbe Request- und Response-Struktur.