Die Messages API: Ihre ersten echten Calls

# Die Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →: Ihre ersten echten Calls

Im Chatfenster haben Sie Claude kennengelernt; mit der Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → setzen Sie ihn ein. Gleiches Modell, keine UI. Sie senden einen strukturierten Request, Sie bekommen strukturierten Output zurück, und das aus Ihrem eigenen Code, zu Ihrem eigenen Zeitpunkt, in Ihrem eigenen Produkt.

Einen generischen „ersten APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → Call“ haben Sie schon gemacht. Sparen wir uns also die Zeremonie und gehen direkt zu dem, was bei Claude spezifisch ist: wie der Request aufgebaut ist, warum der system Prompt dort sitzt, wo ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → sitzt, und wie Sie lange Antworten streamen, ohne dass Ihre Nutzer auf einen leeren Bildschirm starren.

Der Aufbau eines Claude Requests

Jeder Call an die Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → besteht aus einigen Pflichtteilen:

• `model`: welchen Claude Sie wollen (eine Sonnet, Opus oder Haiku Variante). Sonnet ist das Arbeitstier für den Alltag, Opus ist am leistungsfähigsten bei schwierigem Reasoning, Haiku ist das schnelle und günstige Modell.
• `max_tokens`: die Obergrenze dafür, wie viele TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → Claude in seiner Antwort generieren darf. Das ist eine Obergrenze, kein Zielwert. Die Antwort wird nicht aufgefüllt, sie wird nur begrenzt.
• `messages`: die Konversation als Liste von Turns. Jeder Turn hat eine role (user oder assistant) und content.
• `system` (optional, aber wichtig): ein Top-Level-Parameter, getrennt von der messages Liste. Hier stehen Rolle, Tonalität und Regeln.

Der letzte Punkt ist das Erste, über das Leute stolpern, die von anderen APIs kommen. In der Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → ist der System Prompt keine Message mit role: "system". ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → ist ein eigenes Feld im Request. Anthropic Modelle sind auf diese Struktur hin trainiert, und wenn Sie dauerhafte Anweisungen in system halten statt sie in einen user Turn zu packen, verbessert das messbar, wie zuverlässig Claude ihnen folgt.

Ein TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → ist, zur Erinnerung, der Textbaustein, in dem das Modell liest und schreibt (etwa ein paar Zeichen). Sie zahlen pro TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → rein und pro TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → raus, max_tokens ist also auch eine Kostenkontrolle.

Ihr erster echter Call

Hier ist ein vollständiger, ausführbarer 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-5",
    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 wir uns an, was zurückkommt. Die Response ist ein Objekt, kein roher String. Ihr content ist eine Liste von Content Blocks, denn eine einzelne Antwort kann mehr als eine Art von Block enthalten (Text und später Tool-Use-Requests). Für eine reine Textantwort lesen Sie response.content[0].text. Sie bekommen außerdem response.usage mit den Input- und Output-TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →-Zahlen und response.stop_reason, das Ihnen sagt, *warum* Claude gestoppt hat: end_turn heißt, ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → ist natürlich fertig geworden, max_tokens heißt, ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → hat Ihre Obergrenze erreicht und wurde abgeschnitten. Prüfen Sie stop_reason in der Produktion immer. Eine abgeschnittene Antwort, die Sie als vollständig behandelt haben, ist ein stiller Bug.

Prüfen Sie die aktuellen Modellnamen und Parameter in der offiziellen Messages API Reference, bevor Sie ausliefern, denn Modell-IDs entwickeln sich über die Zeit weiter.

Die Konversation tragen Sie

Die APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → ist zustandslos. 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 zurücksenden.

Ein Austausch über mehrere Turns ist einfach eine alternierende 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)?"},
]

Zwei Regeln, die Sie sich einprägen sollten. Erstens müssen Turns zwischen user und assistant alternieren; Sie kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen nicht zwei user Turns hintereinander senden. Zweitens kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen Sie die Antwort des Assistant vorgeben, indem Sie Ihre messages Liste mit einem assistant Turn mit Teilinhalt beenden. Claude macht genau dort weiter, wo Sie aufgehört haben. Dieser Trick, Prefilling genannt, ist wirklich nützlich: Prefill mit {, um JSON-Output zu erzwingen, oder mit Here is the answer in three bullets:, um das Format festzulegen. Es ist ein Claude-spezifischer Hebel, den die Chat-UI Ihnen nie bietet.

Streaming für lange Antworten

Wenn Claude eine lange Antwort schreibt, wollen Sie nicht warten, bis alles fertig ist, bevor Sie etwas zeigen. Streaming schickt die Response stückweise zurück, während sie generiert wird, sodass Text Wort für Wort erscheint, so wie in der Claude App.

Ein Argument umstellen und iterieren:

with client.messages.stream(
    model="claude-sonnet-4-5",
    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() gibt einen Context Manager zurück (den with Block), der garantiert, dass die Verbindung sauber geschlossen wird, selbst wenn mitten im Stream etwas schiefgeht. Der Helper text_stream gibt Ihnen nur die Text-Deltas, was Sie für eine UI normalerweise wollen. Wenn die Schleife endet, setzt get_final_message() die vollständige Response wieder zusammen, sodass Sie usage und stop_reason trotzdem bekommen.

Streamen Sie immer dann, wenn eine Antwort lang werden kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnte oder wenn ein Mensch zusieht, wie sie eintrifft. Für kurze Background-Jobs, bei denen nichts auf den Output wartet, ist der einfache create() Call schlichter und insgesamt genauso schnell.

Was das zu Claude macht und nicht nur zu einer APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →

Einige Verhaltensweisen sollten Sie kennen, bevor Sie darauf aufbauen.

System Prompts haben echtes Gewicht. Wegen der Position von system im Request wird dauerhaften Anweisungen dort konsistenter gefolgt als demselben Text, vergraben in einer user Message. Packen Sie das Beständige (Rolle, Output-Format, harte Einschränkungen) in system und die Aufgabe pro Request in den user Turn.

Langer Kontext ist ein Feature, nicht nur eine Zahl. Claude Modelle unterstützen große Context Windows, groß genug, um ganze Dokumente, lange Transkripte oder einen beträchtlichen Teil einer Codebase hineinzugeben. Praktisch heißt das, dass Sie Quellmaterial oft direkt übergeben kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, statt dafür Retrieval zu bauen. Preise und exakte Fenstergrößen verschieben sich, prüfen Sie die aktuellen Zahlen also in der Doku, statt sie sich zu merken.

Dieselbe API treibt Tools und Agents an. Alles, was Sie später bauen werden (Tool Use, die Connectors, die die Claude Apps bereitstellen, MCP Server und das Claude Agent SDK) sitzt auf genau diesem messages.create Call. Tool Use sind einfach zusätzliche Content-Block-Typen, die durch dieselbe Request- und Response-Struktur fließen, die Sie schon verstehen. Lernen Sie diese Oberfläche gut, und der restliche Claude Pfad wird inkrementell.

Fehler lesen und ein guter Client sein

Echte Calls scheitern manchmal. Die zwei, denen Sie zuerst begegnen:

• `401` (Authentifizierung): Ihr ANTHROPIC_API_KEY fehlt, ist falsch oder ist nicht in die Umgebung geladen. Geben Sie die Variable aus (nicht den Key selbst), um zu bestätigen, dass Ihr Prozess sie sehen kann.
• `429` (Rate Limit) und `529` (overloaded): Sie senden zu schnell, oder der Service ist kurz überlastet. Die Lösung ist dieselbe: zurückfahren und erneut versuchen.

Das SDK wiederholt bestimmte Fehlversuche schon mit Exponential Backoff, aber Sie sollten Calls dennoch umschließen und die Fälle behandeln, bei denen das SDK aufgibt:

import anthropic

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-sonnet-4-5",
        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 alles andere mit einem Nicht-Erfolgs-Status auf APIStatusError zurück. Das ist der Unterschied zwischen einem Skript, das beim ersten Schluckauf stirbt, und einem Service, der einen vollen Nachmittag übersteht.

Wo Sie Ihre Keys aufbewahren

Eine operative Anmerkung, weil das Leute am ersten Tag erwischt. Ihr APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → Key ist ein Secret, an dem eine Abrechnung hängt. Schreiben Sie ihn nie fest in den Quellcode, committen Sie ihn nie, liefern Sie ihn nie in einer Browser-App aus, in der Nutzer ihn lesen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen. Halten Sie ihn in einer Umgebungsvariable oder einem Secrets Manager und lassen Sie das SDK ihn automatisch lesen. Der Konstruktor anthropic.Anthropic() nimmt ANTHROPIC_API_KEY ohne Argument auf, genau deshalb lässt jedes Snippet oben ihn implizit. Wenn Sie Calls auf Browser-Seite brauchen, leiten Sie sie über ein kleines Backend, das den Key hält, niemals über den Client.

Keys erzeugen und rotieren kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen Sie in der Anthropic Console, und der SDK-Quellcode liegt unter github.com/anthropics, wenn Sie nachlesen wollen, wie die Retries und das Streaming implementiert sind.

Key Takeaways

• Packen Sie dauerhafte Anweisungen in den Top-Level-Parameter `system`, nicht in eine user Message. Claude ist auf diese Struktur hin trainiert und folgt ihr zuverlässiger; reservieren Sie user Turns für die eigentliche Aufgabe.
• Prüfen Sie immer `stop_reason` und `usage`. Eine bei max_tokens abgeschnittene Antwort sieht vollständig aus, ist es aber nicht, und TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →-Zahlen sind Ihr Kosten- und Budgetsignal.
• Tragen Sie die Konversation selbst. Die APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → ist zustandslos: Hängen Sie jeden user und assistant Turn an die messages Liste an, halten Sie sie strikt alternierend und nutzen Sie Prefilling, um das Output-Format festzulegen, wenn Sie es brauchen.
• Streamen Sie immer, wenn ein Mensch wartet. Nutzen Sie messages.stream() und den Helper text_stream für lange oder nutzerseitige Antworten und create() für stille Background-Jobs.
• Dieser Call ist die Grundlage für alles Weitere. Tool Use, Connectors, MCP und das Agent SDK laufen alle über dieselbe messages.create Request- und Response-Struktur, die Sie gerade gelernt haben.