Der Einstieg in die Claude-API

TL;DR

Der erste Aufruf ist in fünf Zeilen erledigt. Die drei Voreinstellungen, die später Ärger machen, sind: max_tokens zu niedrig gewählt, kein Streaming bei langen Antworten, und die Annahme, content[0] enthalte immer Text.

Installation und Anmeldung

pip install anthropic

import anthropic

# Löst Zugangsdaten aus der Umgebung auf — bevorzugt gegenüber festen Schlüsseln
client = anthropic.Anthropic()

Der leere Konstruktor sucht in dieser Reihenfolge: ANTHROPIC_API_KEY, dann ANTHROPIC_AUTH_TOKEN, dann ein per Kommandozeile angemeldetes Profil.

Der letzte Punkt wird oft übersehen: Eine nicht gesetzte ANTHROPIC_API_KEY bedeutet nicht, dass keine Zugangsdaten vorliegen. Nach einer Anmeldung über die Kommandozeile funktioniert der leere Konstruktor ohne jede Umgebungsvariable. Details dazu im Beitrag zur CLI und den Profilen.

Der erste Aufruf

antwort = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Was ist die Hauptstadt von Bayern?"}],
)

# content ist eine Liste von Blöcken — Typ prüfen, nicht blind indizieren
for block in antwort.content:
    if block.type == "text":
        print(block.text)

Die Falle in Zeile 8: antwort.content[0] ist nicht zwangsläufig ein Textblock. Bei aktivem Denkmodus steht dort ein Denkblock, bei Werkzeugnutzung ein Werkzeugaufruf, bei einer Ablehnung ist die Liste leer. Prüfen Sie block.type.

Die Systemanweisung

antwort = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    system="Du bist ein technischer Assistent für Maschinenbau. "
           "Antworte knapp und ohne Vorrede.",
    messages=[{"role": "user", "content": "Was ist Werkzeugverschleiß?"}],
)

Die Systemanweisung ist ein eigener Parameter, keine Nachricht mit der Rolle system am Anfang. Sie steht im gerenderten Prompt vor den Nachrichten und nach den Werkzeugen — was für das Caching entscheidend ist.

Mehrere Züge

Die API ist zustandslos: Sie schicken bei jedem Aufruf den gesamten Verlauf mit.

verlauf = []

def frage(text: str) -> str:
    verlauf.append({"role": "user", "content": text})
    antwort = client.messages.create(
        model="claude-opus-5", max_tokens=16000, messages=verlauf,
    )
    ausgabe = next((b.text for b in antwort.content if b.type == "text"), "")
    verlauf.append({"role": "assistant", "content": ausgabe})
    return ausgabe

frage("Mein Name ist Anna.")
frage("Wie heiße ich?")          # das Modell erinnert sich, weil der Verlauf mitgeht

Zwei Regeln: Die erste Nachricht muss die Rolle user haben. Aufeinanderfolgende Nachrichten derselben Rolle sind zulässig — die API fasst sie zusammen.

Bei Werkzeugnutzung ändert sich das: Dann hängen Sie antwort.content als Ganzes an, nicht nur den Text. Die Systematik steht im Beitrag zur Werkzeugnutzung.

Die drei Voreinstellungen, die man kennen sollte

max_tokens nicht zu niedrig wählen. Wer den Wert knapp bemisst, bekommt abgeschnittene Antworten mit stop_reason: "max_tokens" und muss wiederholen. Als Ausgangswert: rund 16.000 für nicht-gestromte Aufrufe, rund 64.000 bei Streaming.

Und ein Punkt, der bei neueren Modellen überrascht: max_tokens begrenzt Denken und Antworttext gemeinsam. Bei Claude Opus 5 und Sonnet 5 ist der Denkmodus standardmäßig aktiv — ein Wert, der auf einem älteren Modell reichte, kann jetzt mitten im Satz abschneiden.

Bei langen Antworten strömen. Nicht-gestromte Anfragen mit hohem max_tokens laufen in HTTP-Zeitüberschreitungen. Das SDK weist Anfragen, die es als zu lang einschätzt, sogar aktiv ab.

with client.messages.stream(
    model="claude-opus-5", max_tokens=64000,
    messages=[{"role": "user", "content": "Schreibe eine Analyse."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    komplett = stream.get_final_message()

get_final_message() liefert die gesamte Nachricht auch beim Strömen — Sie brauchen die Einzelereignisse nicht zu behandeln, wenn Sie sie nicht wollen.

stop_reason prüfen, bevor Sie weiterverarbeiten. Die Werte, die im Betrieb vorkommen:

Was Sie danach einrichten sollten

Vier Dinge, in dieser Reihenfolge, bevor etwas produktiv geht:

1. Prompt-Caching — halbiert die Rechnung bei wiederkehrenden Prompts. Siehe Prompt-Caching bei Claude.
2. Fehlerkette — mindestens Unterscheidung zwischen 429, ab 500 und 4xx. Siehe Fehlerbehandlung.
3. Ablehnungsbehandlung — stop_reason == "refusal" abfangen, Ausweichroute einbauen. Siehe Ablehnungen behandeln.
4. Ein Gateway davor — sobald eine zweite Anwendung dazukommt. Siehe Modellwechsel über das Gateway.

Häufig gestellte Fragen

Wie fange ich mit der Claude-API an?

Paket installieren, den leeren Konstruktor nutzen und messages.create mit Modell, max_tokens und einer Nutzernachricht aufrufen. Der Zugang wird aus der Umgebung aufgelöst — entweder über ANTHROPIC_API_KEY oder über ein per Kommandozeile angemeldetes Profil.

Warum ist content[0] nicht immer der Text?

Weil content eine Liste von Blöcken unterschiedlichen Typs ist. Bei aktivem Denkmodus steht dort ein Denkblock, bei Werkzeugnutzung ein Werkzeugaufruf, und bei einer Ablehnung ist die Liste leer. Prüfen Sie block.type und suchen Sie gezielt den Textblock heraus.

Welchen Wert soll ich für max_tokens wählen?

Als Ausgangswert rund 16.000 für nicht-gestromte Anfragen und rund 64.000 beim Strömen. Beachten Sie, dass max_tokens bei aktivem Denkmodus Denken und Antworttext gemeinsam begrenzt — und dass der Denkmodus bei Claude Opus 5 und Sonnet 5 standardmäßig aktiv ist.

Muss ich den Gesprächsverlauf selbst verwalten?

Ja, die API ist zustandslos. Sie schicken bei jedem Aufruf den gesamten Verlauf mit. Die erste Nachricht muss die Rolle user haben; aufeinanderfolgende Nachrichten derselben Rolle sind zulässig und werden zusammengefasst.

Wann muss ich strömen?

Sobald max_tokens deutlich über etwa 16.000 liegt. Nicht-gestromte Anfragen laufen dann in HTTP-Zeitüberschreitungen, und das SDK weist solche Anfragen teilweise aktiv ab. Mit stream.get_final_message() bekommen Sie trotzdem die gesamte Nachricht, ohne einzelne Ereignisse behandeln zu müssen.

Der nächste Schritt

Bringen Sie das Prompt-Caching in Ordnung, bevor Sie irgendetwas anderes optimieren. Es ist die einzige Maßnahme, die gleichzeitig Kosten senkt, Kontingent freimacht und die Antwortzeit verkürzt. Beim Aufbau helfen wir gern.