Claude API einrichten: Console, API Key und Messages-Aufrufe (2026)

Die Hürde bei der Claude API liegt nicht darin, ob man eine HTTP-Anfrage senden kann, sondern in ein paar leicht zu übersehenden Details: in welchen Request-Header der Key gehört, ob anthropic-version Pflicht ist, warum max_tokens nicht weggelassen werden darf und warum content ein Array und kein String ist. Wer diese Punkte richtig macht, hat den minimalen Aufruf in zehn Minuten laufen.

Dieser Artikel folgt der Reihenfolge Konto und Key, Request-Header, curl, Python, Streaming und Parameter, Fehlersuche, Key-Sicherheit und erklärt am Ende, wie ein kompatibles Gateway als alternativer Zugang dient. Modell-IDs, Kontextfenster und Abrechnung richten sich nach der offiziellen Anthropic-Dokumentation und unseren Modellpreisen.

Hinweis: Anthropic und Claude sind Marken ihrer jeweiligen Inhaber, OpenAI ist eine Marke ihres Inhabers. Dieser Artikel dient ausschließlich der technischen Einführung. Modelle, Preise und Kontingente können sich ändern; prüfen Sie vor der Integration die offizielle Dokumentation.

1. Vorbereitung: Konto, Workspace und Key

Die Claude API verwaltet Konto, Workspace, API Keys und Rechnungen über die Anthropic Console. Klären Sie vor dem Start drei Dinge:

Vorbereitung	Worauf achten	Erläuterung
Konto	E-Mail verifizierbar, Login in der Console möglich	Für Teams empfiehlt sich eine Firmenadresse
Workspace	Zu welchem Workspace gehört der Key	Der Workspace bestimmt Mitglieder, Keys und Zuordnung der Nutzung
Abrechnung	Zahlungsmethode, Rechnungsdaten, verfügbares Guthaben	Maßgeblich ist die Anzeige in der Console

Wenn im Team noch nicht feststeht, wer die Rechnungen verwaltet, sollten Sie noch keinen Produktions-Key anlegen. Sobald ein Key herausgegeben ist, hängen Nutzung und Berechtigungen am jeweiligen Workspace; eine spätere Aufteilung wird aufwendiger.

2. API Key anlegen: sechs Schritte

Öffnen Sie die Anthropic Console (console.anthropic.com), registrieren Sie sich oder melden Sie sich an und schließen Sie die E-Mail-Verifizierung ab.
Legen Sie einen Workspace an oder wählen Sie einen aus. Trennen Sie nach Möglichkeit Produktion, Tests und persönliche Experimente, damit nicht ein Key überall verwendet wird.
Wechseln Sie zur Seite API Keys und erstellen Sie einen neuen Key. Der Name sollte den Zweck erkennen lassen, etwa prod-backend-2026-10.
Kopieren Sie den Key und speichern Sie ihn sofort in einem Secret-Manager oder als Umgebungsvariable. In den meisten Konsolen wird der vollständige Wert nur einmal bei der Erstellung angezeigt.
Prüfen Sie in der Console unter Abrechnung Zahlungsmethode, Rechnungsdaten und Kontingente. Ob Vorauszahlung, Rechnungen und Obergrenzen möglich sind, ergibt sich aus den tatsächlichen Optionen der Console.
Setzen Sie lokal eine Umgebungsvariable und senden Sie eine minimale Anfrage, um den Key zu testen.

export ANTHROPIC_API_KEY="sk-ant-IHR_KEY"

Schreiben Sie den Key nicht in Code, Git-Repositories, Frontend-Seiten oder Chatverläufe. Auch in der Testphase empfiehlt sich ein eigener Key, der sich jederzeit widerrufen lässt.

3. Request-Header und minimaler curl-Aufruf

Der Endpunkt der Messages API ist POST https://api.anthropic.com/v1/messages. Drei Header sind entscheidend:

Header	Wert	Funktion
`x-api-key`	Ihr API Key	Authentifizierung des Anthropic API Key
`anthropic-version`	`2023-06-01`	Legt die API-Version fest; fehlt sie, kann die Anfrage fehlschlagen
`content-type`	`application/json`	Kennzeichnet den JSON-Request-Body

Wichtig: Der API Key läuft über x-api-key, nicht über Authorization: Bearer. Die Vermischung dieser beiden Authentifizierungsarten ist eine häufige Ursache für 401.

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "Du bist ein technischer Assistent. Antworte knapp.",
    "messages": [
      {"role": "user", "content": "Erkläre in drei Sätzen, was ein API-Gateway ist."}
    ]
  }'

Die Modell-ID im Beispiel ist nur eine aktuell verfügbare Variante. Maßgeblich für verfügbare Modelle, Kontextfenster und Preise sind die offizielle Models API und unsere Modellpreise. Die Antwort enthält content als Array von Inhaltsblöcken; der Text steht meist in content[0].text, robuster ist jedoch das Durchlaufen aller Blöcke mit der Prüfung auf type == "text".

4. Messages API mit Python aufrufen

Installieren Sie das offizielle SDK:

pip install anthropic

Der minimale Aufruf:

import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="Du bist ein technischer Assistent. Antworte knapp.",
    messages=[
        {"role": "user", "content": "Erkläre in drei Sätzen, was ein API-Gateway ist."}
    ],
)

for block in resp.content:
    if block.type == "text":
        print(block.text)

print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)

Einige wichtige Punkte:

system ist ein Parameter auf oberster Ebene und keine Nachricht mit {"role": "system"}. Die Rollen der Messages API sind vor allem user und assistant.
max_tokens ist Pflicht und begrenzt die maximale Ausgabelänge dieser Antwort. Ist der Wert zu klein, wird die Antwort abgeschnitten und stop_reason zeigt max_tokens; ist er zu groß, müssen Kosten und Timeouts mitgedacht werden.
resp.content ist ein Array von Blöcken, das Text-, Denk- oder Tool-Aufruf-Blöcke enthalten kann. Geschäftscode sollte nicht davon ausgehen, dass nur Text zurückkommt.
Protokollieren Sie usage und stop_reason; sie sind die Grundlage für Abrechnung und Fehlersuche.

5. system, max_tokens und Streaming

system enthält Rollenvorgaben, Ausgabeformat und Randbedingungen. Stabile Inhalte gehören nach vorn, wechselnde Nutzereingaben in messages; das verbessert die Cache-Trefferquote.

max_tokens ist nicht „je mehr, desto besser“. Der Wert begrenzt die Ausgabe einer Anfrage und verändert nicht die Eingabekosten. Lange Berichte und Code brauchen ausreichend Spielraum, Klassifikation und Extraktion kommen mit kleineren Werten aus. In der Produktion sollten Sie den Wert je Schnittstellentyp konfigurieren statt global einen einzigen Wert zu verwenden.

Streaming eignet sich für lange Antworten und interaktive Oberflächen. So sieht es mit dem Python SDK aus:

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=4096,
    system="Du bist ein technischer Assistent.",
    messages=[{"role": "user", "content": "Schreibe eine Produktbeschreibung mit 200 Wörtern."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Auch Streaming-Anfragen liefern usage und stop_reason; diese sollten bei der Speicherung nicht fehlen. Bei nativem HTTP ergänzen Sie "stream": true im Request-Body. Die Antwort ist ein SSE-Ereignisstrom, der etwa über content_block_delta ausgewertet wird.

6. Modellbenennung und Versionsauswahl

Claude-Modelle sind in Serien wie Opus, Sonnet und Haiku gegliedert. Die Serien unterscheiden sich in Ausrichtung, Kontextfenster und Preis. Modell-IDs gibt es meist in zwei Formen: stabile Aliasse und datierte Snapshots. In der Produktion muss klar sein, welche Form verwendet wird; der Anzeigename aus der Console gehört nicht direkt in den Code.

Empfohlene Reihenfolge für die Auswahl:

Filtern Sie mit Ihrem eigenen Evaluationsset die Serie heraus, die die Qualitätsanforderungen erfüllt.
Vergleichen Sie Latenz, Kontextfenster und Kosten.
Prüfen Sie abschließend, ob das Modell in der Zielregion und über den gewählten Zugang verfügbar ist.

Modelle werden eingeführt und abgekündigt, ältere IDs können in den Legacy-Status wechseln. Bündeln Sie Modellnamen in einer Konfiguration oder Mapping-Tabelle, sodass bei einer Migration nur eine Stelle geändert werden muss. Maßgeblich sind die offizielle Models API, die Console und unsere Modellpreise.

7. Fehlersuche bei 401, 429 und 400

Statuscode	Häufige Ursachen	Reihenfolge der Prüfung
401	Key fehlt, falscher Header, Key widerrufen, Workspace passt nicht	`x-api-key`, Leerzeichen und Zeilenumbrüche, Key-Status, Base URL prüfen
429	Anfrage- oder Token-Rate überschritten, plötzliche Parallelität, Kontingentproblem	`retry-after` lesen, exponentielles Backoff mit Jitter, Keys aufteilen, Parallelität senken
400	Ungültiges JSON, `max_tokens` fehlt, falsche Modell-ID, Parameter außerhalb des Bereichs	Fehlerbody und Request-ID sichern, Request-Body Punkt für Punkt prüfen
404	Pfad oder Modellname existiert nicht	`/v1/messages` und Modell-ID bestätigen
5xx	Temporäre Störung beim Upstream	Begrenzt wiederholen, bei weiterem Fehler auf einen Ausweichzugang wechseln

Sichern Sie bei der Fehlersuche zuerst den Response-Header request-id. Bei 401 sollten Sie nicht zuerst das Guthaben verdächtigen, sondern Authentifizierungs-Header und Key prüfen. Ein 429 bedeutet nicht zwangsläufig „kein Geld mehr“, sondern kann eine Ratenbegrenzung sein. Bei 400 liegt das Problem meist im Request-Body; die Fehlermeldung nennt häufig das betroffene Feld.

8. Key-Sicherheit und kompatibles Gateway als Alternative

Für die Key-Sicherheit sollten mindestens vier Regeln gelten: Keys nur in Umgebungsvariablen oder einem Secret-Manager speichern; Keys nach Projekt trennen; Nutzungsalarme einrichten; Keys regelmäßig rotieren und die Keys ausgeschiedener Mitarbeiter widerrufen. Langlebige Keys dürfen weder im Frontend noch in mobilen Apps oder öffentlichen Repositories auftauchen.

Wenn Teams in China auf Netzwerk-, Zahlungs- oder Rechnungsprobleme stoßen, kann ein Gateway mit Anthropic-kompatiblem Endpunkt die offizielle Adresse ersetzen. Beim offiziellen SDK müssen in der Regel nur base_url und Key geändert werden:

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com",
)

resp = client.messages.create(
    model="siehe Modellliste im Gateway",
    max_tokens=256,
    messages=[{"role": "user", "content": "Antworte nur mit OK"}],
)
print(resp.content)

Bietet ein Gateway nur eine OpenAI-kompatible Schnittstelle, müssen Request-Struktur oder eine Adaptionsschicht angepasst werden; der Austausch der Base URL allein genügt nicht. Prüfen Sie bei der Auswahl eines Gateways drei Dinge: Unterstützung des nativen Anthropic-Protokolls, Zuordnung der Modellnamen sowie transparente Regeln zu Ratenbegrenzung und Logging.

9. Häufige Fragen

Sind Claude API und das Abo der Claude-Webversion dasselbe?

Nein. Die Webversion ist ein Produktabo für Endnutzer, die API wird nutzungsbasiert abgerechnet. Kontosystem, Kontingente und Verwaltung sind getrennt. Keys, Rechnungen und Nutzung der API werden in der Anthropic Console verwaltet.

Ist der vollständige Wert eines API Key nach der Erstellung noch sichtbar?

In den meisten Fällen wird er nur einmal bei der Erstellung angezeigt. Danach sind nur Präfix oder Name sichtbar. Speichern Sie den Key daher sofort in einem Secret-Manager; bei Verlust widerrufen Sie den alten Key und legen einen neuen an.

Warum muss max_tokens übergeben werden?

Die Messages API verlangt eine explizite Obergrenze für die Ausgabe einer Anfrage, um Länge und Ressourcen zu steuern. Fehlt der Parameter, wird die Anfrage mit 400 abgelehnt. Wählen Sie einen zur Aufgabe passenden Wert und setzen Sie ihn nicht blind auf das Maximum.

Ist 429 ein aufgebrauchtes Kontingent oder zu hohe Parallelität?

Beides ist möglich. Prüfen Sie zuerst Response-Body und retry-after: Kurzzeitig gehäufte Fehler deuten meist auf Rate oder Parallelität hin; treten sie dauerhaft auf und ist die Abrechnung auffällig, prüfen Sie Tarif und Nutzung. Gegenmaßnahmen sind Backoff, weniger Parallelität und aufgeteilte Keys.

Brauchen Teams in China zwingend ein Gateway?

Nicht unbedingt. Teams mit stabiler Direktverbindung, funktionierender Zahlung und abgeschlossener Compliance-Prüfung fahren direkt meist einfacher. Ein Gateway lohnt die Prüfung, wenn Abrechnung in RMB, Rechnungen, ein einheitlicher Multi-Modell-Zugang oder Netzbeschleunigung benötigt werden; klären Sie dabei Daten- und Störungsrichtlinien.

Nächster Schritt

Registrieren Sie sich beim ZSQH AI Gateway, testen Sie mit einem Test-Key die minimale Anfrage an /v1/messages und integrieren Sie danach die Produktion. Modelle, Kontextfenster und Abrechnung entnehmen Sie den Modellpreisen.

Weiterlesen: