SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor

Claude API Tutorial: Python-Tool auf Ubuntu 24.04

Bauen Sie ein Python-Logtool mit Claude API auf Ubuntu 24.04: Schlüssel sicher speichern, Streaming nutzen, Fehler typisieren und Kosten über Limits kontrollieren.

Was Sie bauen

Ein Kommandozeilen-Tool auf einem frisch eingerichteten Ubuntu 24.04 VPS. Sie übergeben ihm eine Fehlermeldung oder einen Log-Ausschnitt per Pipe und erhalten eine Diagnose in einfachem Englisch: journalctl -u nginx -n 50 | explain. Das Tool umfasst etwa sechzig Zeilen Python. Dabei verwenden Sie alle Komponenten, die eine echte Claude API-Anwendung benötigt: einen sicher gespeicherten Schlüssel, eine virtualenv, die Antwortstrukturen des SDK, Streaming, die typisierte Ausnahmekette und eine systemd-Unit, damit das Tool ohne manuelles Eingreifen läuft.

Ich habe dieses Projekt bewusst gewählt. In den meisten Tutorials zur ersten API-Anwendung erstellen Sie einen Chatbot, den Sie später nie wieder öffnen. Ein Log-Erklärer ist auf einem Server vom ersten Tag an nützlich. Außerdem zwingt er Sie, die beiden Fehlerquellen zu verstehen, bei denen Anfänger tatsächlich häufig scheitern: das korrekte Lesen des Antwortobjekts und die Kontrolle der Ausgaben. Die API rechnet pro Token ab. Für die Tarife Start, Build und Scale gibt es monatliche Ausgabenlimits. Zusätzlich können Sie niedrigere eigene Limits festlegen. Die Kostenkontrolle ist daher bereits bei der Entwicklung ein wichtiger Bestandteil und kein nachträglicher Zusatz. Dieselbe Disziplin ist wichtig, wenn Sie später zu Claude Code auf diesem VPS in tmux ausführen wechseln.

Einen API-Key über die Console abrufen

Der API-Zugriff wird in der Anthropic Console unter platform.claude.com verwaltet. Registrieren Sie sich und erstellen Sie anschließend unter Settings → API Keys einen Key (die Dokumentation verlinkt direkt auf platform.claude.com/settings/keys). In der Console müssen Sie den Key benennen, ein Ablaufdatum auswählen und ihn sich selbst oder einem Service Account zuordnen. Anthropic empfiehlt für Produktionsdienste und alle gemeinsam genutzten Keys Service-Account-Keys. Der Key wird nur einmal angezeigt, beginnt mit sk-ant- und kann anschließend nicht erneut abgerufen werden. Kopieren Sie ihn daher sofort oder löschen Sie ihn und stellen Sie einen neuen aus.

Zu den Kosten: Seit Oktober 2026 gibt es für die API kein dauerhaft kostenloses Kontingent. Laut der Preisdokumentation von Anthropic erhalten neue Benutzer eine kleine Menge kostenloser Credits zum Testen. Sobald diese aufgebraucht sind, benötigen Sie gekaufte Credits, anrechenbare Credits aus einem monatlichen Tarif oder eine Vereinbarung zur Rechnungsstellung, um weiterhin Anfragen zu senden. Dies ist unabhängig von einem claude.ai-Abonnement. Ein API-Key gewährt keinen Zugriff auf die Chat-Anwendung. Ein Pro-Tarif enthält keine API-Credits, Max-, Ultra- und Team-Tarife dagegen schon: Am 31. Oktober 2026 waren dies monatlich $100 bei Max und $200 bei Ultra. Bei Team werden $20 pro Standard-Sitz und $100 pro Premium-Sitz bereitgestellt, maximal jedoch $500. Die Credits werden aktiviert, indem Sie nach sieben Tagen in einem berechtigten Tarif in den Abrechnungseinstellungen von claude.ai eine Console-Organisation verknüpfen. Nicht verwendete Credits verfallen am Ende jedes Abrechnungszeitraums. Sie gelten nicht für die interaktive Nutzung von Claude Code. Sie gelten jedoch für claude -p und das Claude Agent SDK, wenn Sie diese selbst mit einem API-Key der verknüpften Console-Organisation ausführen. Die Einzelheiten finden Sie unter Funktionsweise der monatlichen API-Credits für Max, Ultra und Team. Wenn Sie zwischen einem Abonnement und der API abwägen, ist dieser Vergleich ein eigenes Thema: welchen Claude-Tarif Sie tatsächlich benötigen.

Erstellen Sie den Key mit dem Geltungsbereich auf den Workspace eines einzelnen Projekts oder Servers. Wenn ein Key offengelegt wird, und bei ausreichend langer Nutzungsdauer wird das irgendwann passieren, sollten Sie ihn widerrufen können, ohne alle anderen Ressourcen zu beeinträchtigen, die Sie verwalten.

Der Schlüssel gehört nicht in .bashrc

Der reflexartige Ansatz ist export ANTHROPIC_API_KEY=sk-ant-... in ~/.bashrc. Tun Sie das nicht. Dabei entstehen drei getrennte Probleme:

  • Jeder Prozess übernimmt ihn. Eine Umgebungsvariable, die in Ihrer Login-Shell exportiert wurde, wird an alles weitergegeben, was Sie starten: an die Webanwendung, an den Crash-Reporter, der die Umgebung hilfreicherweise in einen Fehlerbericht schreibt, und an die phpinfo()-Seite, die jemand aktiviert gelassen hat. Die Angriffsfläche des Schlüssels umfasst damit „alles, was dieser Benutzer jemals ausführt“.
  • Beim Eingeben landet er in ~/.bash_history. Führen Sie den Export einmal von Hand aus, liegt Ihr Schlüssel dauerhaft in einer Klartextdatei und wird in jede Sicherung Ihres Home-Verzeichnisses übernommen.
  • Wenn systemd ihn benötigt, ist er dort nicht vorhanden. Dienste lesen Ihre .bashrc nicht. Beim hier verwendeten Python SDK führt ein fehlender Schlüssel ohne alternative Anmeldedaten daher zu einem lokalen TypeError mit Could not resolve authentication method., bevor eine HTTP-Anfrage gesendet wird.

Eine eigene Umgebungsdatei mit 600-Berechtigungen hält den Schlüssel aus der exportierten Umgebung Ihrer Login-Shell heraus und lädt ihn nur für den Prozess, der ihn benötigt:

sudo mkdir -p /opt/explain
sudo install -m 600 -o root -g root /dev/null /etc/claude-explain.env
IFS= read -r -s -p 'Claude API key: ' explain_api_key
printf '\n'
printf 'ANTHROPIC_API_KEY=%s\n' "$explain_api_key" | sudo tee /etc/claude-explain.env >/dev/null
unset explain_api_key

Verwenden Sie tee aus einem printf statt eines Editors, wenn der Schlüssel nicht in Editor-Auslagerungsdateien gelangen soll. Prüfen Sie in jedem Fall mit ls -l /etc/claude-explain.env, dass die Datei -rw------- enthält und root gehört. Interaktive Shells erhalten den Schlüssel pro Aufruf über einen Wrapper (siehe unten). systemd erhält ihn über EnvironmentFile=; root liest die Datei, bevor die Berechtigungen reduziert werden, sodass der Dienstbenutzer keinen Lesezugriff darauf benötigt. Die obige Eingabeaufforderung hält den Schlüssel aus Shell-Verlauf, Code, git und Befehlszeilenargumenten heraus. Der laufende Prozess erhält ihn weiterhin in seiner Umgebung.

Installieren Sie das SDK in einer venv

Ubuntu 24.04 liefert Python 3.12 mit der Durchsetzung von PEP 668 aus. Daher schlägt ein direktes pip install anthropic mit dem Systeminterpreter mit error: externally-managed-environment fehl. Das Betriebssystem arbeitet dabei wie vorgesehen. Verwenden Sie eine virtuelle Umgebung:

sudo apt update && sudo apt install -y python3-venv
sudo python3 -m venv /opt/explain/venv
sudo /opt/explain/venv/bin/pip install anthropic

Auf einem Server ist keine Aktivierung erforderlich. Der direkte Aufruf von /opt/explain/venv/bin/python verwendet immer die Pakete der venv.

Erster Aufruf und korrektes Lesen der Antwort

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Explain what a systemd unit file is in three sentences."}],
)

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

Zwei Dinge in diesen zwölf Zeilen vermitteln den größten Teil des mentalen API-Modells. Erstens liest anthropic.Anthropic() ohne Argumente den Schlüssel aus der Umgebung. Übergeben Sie ihn niemals als Zeichenfolgenliteral. Zweitens ist response.content eine Liste von Inhaltsblöcken und keine Zeichenfolge. Wenn Sie die Liste direkt ausgeben, erhalten Sie die typische Ausgabe von Einsteigern:

[TextBlock(citations=None, text='A systemd unit file is...', type='text')]

Das ist kein Fehler, sondern die Repräsentation des Objekts. Antworten können mehrere Blocktypen enthalten, etwa Text, Tool-Aufrufe und Denkprozesse. Deshalb durchlaufen Sie die Liste und prüfen block.type == "text", bevor Sie auf .text zugreifen. Bei Opus 5.5 ist das bereits beim ersten Aufruf relevant: Das Denken ist immer aktiviert. Wenn das Modell das Denken bei einer einfachen Anfrage nicht überspringt, beginnt die Liste daher mit einem thinking-Block, dessen Feld thinking standardmäßig leer ist. response.content[0].text ist nicht Ihre Antwort. Bauen Sie diese Schleife vom ersten Tag an ein. Dadurch vermeiden Sie eine ganze Klasse von Verwirrung nach dem Muster „Es wird unverständlicher Inhalt ausgegeben“.

Verwenden Sie exakt die Modell-ID claude-opus-5-5. Ab der Generation 4.6 sind Modell-IDs datumsfrei. Die datumsfreie ID bezeichnet den festgelegten Snapshot. Verlassen Sie sich daher nicht auf die Gewohnheit oder einen alten Blogbeitrag, an eine aktuelle Modell-ID ein Datum anzuhängen. Das führt zu einem 404-Fehler, der weiter unten behandelt wird. Bei älteren Modellen gilt das umgekehrte Prinzip: Die kanonische ID von Haiku 4.5 lautet claude-haiku-4-5-20251001.

Das eigentliche Tool: Erklärung

Hier ist das vollständige Programm. Es liest von stdin und gibt die Diagnose als Stream aus. Fehler werden behandelt:

#!/usr/bin/env python3
"""explain: pipe an error or log excerpt in, get a diagnosis out."""
import sys
import anthropic

MODEL = "claude-opus-5-5"

def main() -> int:
    text = sys.stdin.read().strip()
    if not text:
        print("usage: journalctl -u nginx -n 50 | explain", file=sys.stderr)
        return 1

    client = anthropic.Anthropic()
    try:
        with client.messages.stream(
            model=MODEL,
            max_tokens=4096,
            system=(
                "You are a senior Linux sysadmin. The user pipes you server "
                "logs or error output. Name the most likely cause outright, "
                "then give the commands to confirm and fix it. Be terse."
            ),
            messages=[{"role": "user", "content": text}],
        ) as stream:
            for chunk in stream.text_stream:
                print(chunk, end="", flush=True)
        print()
    except anthropic.RateLimitError as e:
        retry_after = e.response.headers.get("retry-after")
        if retry_after is not None:
            print(f"rate limited; retry in {retry_after}s", file=sys.stderr)
        else:
            print(f"API limit reached: {e.message}", file=sys.stderr)
        return 2
    except anthropic.APIStatusError as e:
        print(f"API error {e.status_code}: {e.message}", file=sys.stderr)
        return 2
    except anthropic.APIConnectionError:
        print("network error reaching the API", file=sys.stderr)
        return 2
    return 0

if __name__ == "__main__":
    sys.exit(main())

Speichern Sie es als /opt/explain/explain.py. Fügen Sie anschließend einen Wrapper hinzu, der den Schlüssel für die interaktive Nutzung lädt:

sudo tee /usr/local/bin/explain >/dev/null <<'EOF'
#!/bin/sh
set -a; . /etc/claude-explain.env; set +a
exec /opt/explain/venv/bin/python /opt/explain/explain.py "$@"
EOF
sudo chmod 755 /usr/local/bin/explain

(Der Wrapper muss über sudo ausgeführt werden. Alternativ benötigt die Env-Datei eine Gruppe, der Ihr Administratorkonto angehört. Entscheiden Sie sich bewusst für eine dieser Optionen, anstatt die Dateiberechtigungen auf 644 zu lockern.)

Warum Streaming. client.messages.stream gibt Tokens aus, sobald sie eintreffen, statt während der gesamten Generierung stumm zu bleiben. Außerdem werden dadurch HTTP-Timeouts bei langen Ausgaben vermieden. Das SDK lehnt aus genau diesem Grund bei nicht gestreamten Aufrufen sehr große max_tokens-Werte ab. text_stream liefert nur den Antworttext. Bei aktivierter standardmäßiger Anzeige des Denkprozesses in Opus 5.5 wird überhaupt kein Denktext gestreamt, sodass die Ausgabe sauber bleibt. Wenn Sie das zusammengesetzte Objekt anschließend benötigen, rufen Sie stream.get_final_message() innerhalb des with-Blocks auf.

Warum diese Reihenfolge der Ausnahmen. Das SDK löst typisierte Ausnahmen aus, zuerst die spezifischsten: RateLimitError steht für 429. Wenn die Ausnahme einen retry-after-Header enthält, gibt dieser an, wie lange gewartet werden soll. Ein 429 aufgrund eines Ausgabenlimits der Stufe enthält keinen solchen Header. APIStatusError deckt andere Antworten außerhalb des Bereichs 2xx ab. Prüfen Sie e.status_code >= 500 auf serverseitige Probleme. APIConnectionError bedeutet, dass überhaupt keine Antwort eingegangen ist. Bevor Sie eine Wiederholungsschleife implementieren: Das SDK wiederholt 429- und 5xx-Fehler bereits selbst, standardmäßig zweimal mit exponentiellem Backoff (max_retries auf dem Client). Wenn except ausgeführt wird, sind die Wiederholungsversuche bereits ausgeschöpft. In einem CLI ist es daher richtig, den Fehler zu melden und das Programm zu beenden, statt zu warten und weitere Anfragen zu senden.

Kostenkontrolle

Dieser Aspekt verdient einen eigenen Abschnitt, weil die Tarife Start, Build und Scale integrierte monatliche Ausgabenlimits haben. Diese Limits ersetzen jedoch kein eigenes Budget für dieses Tool. Außerdem summiert sich jeder Fehler hier unbemerkt.

max_tokens ist Ihr Limit für Ausgabe-Tokens pro Aufruf. Eingaben werden separat abgerechnet. Die Gesamtkosten einer Anfrage hängen daher ebenfalls von der Eingabegröße ab. Ausgabe-Tokens sind die teurere Richtung: Bei Opus 5.5 kosten sie das Fünffache des Eingabepreises. max_tokens begrenzt die Anzahl der Tokens, die das Modell höchstens erzeugen darf. Ein zu lang laufender Prompt kann nicht mehr Ausgabe erzeugen, als Sie erlaubt haben. Bei den 5.5-Modellen umfasst dieses Limit auch das Denken: Denk-Tokens zählen zu max_tokens und werden als Ausgabe abgerechnet, obwohl der Denktext nicht an Sie zurückgegeben wird. Wählen Sie das Limit passend zur Aufgabe. Mit 4,096 Tokens hat eine knappe Logdiagnose noch ausreichend Platz für die vorgelagerte Analyse. Eine Klassifizierungsaufgabe benötigt deutlich weniger. Wenn Antworten mit stop_reason: "max_tokens" vorzeitig enden, war das Limit zu knapp. Erhöhen Sie es bewusst oder senken Sie die Einstellung für den Aufwand, damit das Modell weniger analysiert, statt standardmäßig ein sehr hohes Limit zu verwenden.

Zählen Sie vor dem Senden. Auch Eingaben kosten Geld, und Logs sind umfangreich. Die API stellt dafür einen kostenlos nutzbaren Zähl-Endpunkt bereit. Er hat eigene Rate-Limits, die von der Nachrichtenerstellung getrennt sind:

count = client.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": big_log_text}],
)
print(count.input_tokens)

Damit verhindern Sie, dass versehentlich ein 2 GB großes Log durch das Tool geleitet wird. Übergeben Sie dabei das Modell, das Sie tatsächlich aufrufen werden: Claude 4.7 und spätere Modelle verwenden einen neueren Tokenizer, der für denselben Text ungefähr 30% mehr Tokens erzeugt als frühere Claude-Modelle. Verwenden Sie dafür nicht tiktoken. Das ist der Tokenizer von OpenAI, nicht der von Claude. Seine Zählung stimmt daher nicht mit der Abrechnung überein.

Wählen Sie das Modell nach der Aufgabe, nicht aus Loyalität. Im Oktober 2026 kostet Opus 5.5 (claude-opus-5-5) $4 pro 1 Million Eingabe-Tokens und $20 pro 1 Million Ausgabe-Tokens. Haiku 5.5 (claude-haiku-5-5) kostet $0.10/$0.50 für Prompts bis 100,000 Tokens und $0.50/$2.50 oberhalb dieses Umfangs, bei einem Kontext von 1M. Sonnet 5.5 (claude-sonnet-5-5) liegt mit $2/$10 dazwischen. Konkret kostet ein Logauszug mit 2,000 Tokens und einer Antwort mit 500 Tokens auf Opus ungefähr $0.018 und auf Haiku $0.00045, zuzüglich der Analyse des Modells, die als Ausgabe abgerechnet wird. Beginnen Sie mit Opus, solange Sie die Ausgabequalität bewerten. Testen Sie anschließend dieselben Prompts mit Haiku. Bei einfachen Transformationen mit hohem Volumen ist die Qualität häufig nicht zu unterscheiden, während der Preis pro Token nur ein Vierzigstel beträgt. Prüfen Sie die aktuellen Werte auf der Preisseite, bevor Sie diese Zahlen fest in ein Budget übernehmen.

Batches für alles, was warten kann. Die Batches API verarbeitet Anfragen asynchron zu 50% der Standardpreise. Die meisten Batches sind innerhalb einer Stunde abgeschlossen. Nächtliche Zusammenfassungen, Backfills, Massenklassifizierungen und alle Aufgaben, bei denen niemand auf eine Antwort wartet, gehören dorthin.

Prompt-Caching für wiederholten Kontext. Wenn jeder Aufruf denselben großen System-Prompt oder dasselbe Runbook erneut sendet, markieren Sie ihn als cachefähig:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    system=[{
        "type": "text",
        "text": RUNBOOK_TEXT,  # the same 30K tokens on every call
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": question}],
)
print(response.usage.cache_read_input_tokens)  # non-zero from the second call on

Das Schreiben eines Caches kostet bei einer TTL von 5 Minuten das 1.25-Fache des Eingabepreises. Das Lesen des Caches kostet bei Opus 5.5 und Sonnet 5.5 das 0.05-Fache und bei den meisten anderen Modellen das 0.1-Fache. Der zweite Aufruf innerhalb dieses Zeitfensters amortisiert daher bereits den ersten. Dabei gibt es zwei Einschränkungen. Der gecachte Präfix muss das modellspezifische Mindestvolumen erreichen, bei Opus 5.5 sind das 512 Tokens. Ein sehr kurzer System-Prompt wird daher stillschweigend überhaupt nicht gecacht. Wenn cache_read_input_tokens bei identischen Aufrufen weiterhin null bleibt, prüfen Sie, ob die Aufrufe innerhalb der Cache-Lebensdauer liegen und ob Präfix und Cache-Konfiguration identisch bleiben. Ein Zeitstempel ist die häufigste Ursache.

Denken Sie daran, was als Eingabe zählt. System-Prompts, Tooldefinitionen und bei mehrteiligen Unterhaltungen der gesamte Verlauf, den Sie bei jedem Turn erneut senden, werden als Eingabe-Tokens abgerechnet. Eine Chat-Schleife, die den Verlauf nie kürzt, lässt die Kosten quadratisch wachsen. Die vollständige Abrechnung sollten Sie verstehen, bevor Sie etwas Konversationelles entwickeln: wie sich die Token-Nutzung und Abrechnung von Claude tatsächlich zusammensetzen.

Unter systemd ausführen

Der Nutzen der Disziplin bei Umgebungsdateien: ein Timer, der jeden Morgen die Fehler des Vortags zusammenfasst.

# /etc/systemd/system/log-digest.service
[Unit]
Description=Daily error-log digest via the Claude API

[Service]
Type=oneshot
User=explain
Group=systemd-journal
EnvironmentFile=/etc/claude-explain.env
ExecStart=/bin/sh -c 'journalctl -p err --since yesterday --until today | /opt/explain/venv/bin/python /opt/explain/explain.py >> /var/log/log-digest.txt'
# /etc/systemd/system/log-digest.timer
[Unit]
Description=Run the log digest every morning

[Timer]
OnCalendar=06:15
Persistent=true

[Install]
WantedBy=timers.target
sudo useradd -r -s /usr/sbin/nologin explain
sudo touch /var/log/log-digest.txt && sudo chown explain /var/log/log-digest.txt
sudo systemctl daemon-reload
sudo systemctl enable --now log-digest.timer
sudo systemctl start log-digest.service   # test it once, right now

Beachten Sie, was EnvironmentFile= ermöglicht: systemd liest die Datei im Besitz von root mit den Rechten 600, bevor es zum nicht privilegierten Benutzer explain wechselt. Dadurch erhält der Prozess die Variable, während der Benutzer die Schlüsseldatei nicht lesen kann. Die Gruppe systemd-journal gewährt Zugriff auf die Logs. Testen Sie den Dienst mit einem manuellen systemctl start und lesen Sie journalctl -u log-digest.service. Warten Sie nicht bis 06:15, um einen Tippfehler zu finden. Wenn dieses Muster über eine Shell-Pipeline hinauswächst, lässt sich derselbe Ansatz mit dem Schlüssel in der Umgebungsdatei direkt auf Claude-gestützte n8n-Workflows auf demselben Server übertragen.

Fehlerfälle und die dabei angezeigten Meldungen

401 trotz gültigem Schlüssel. Die Ausnahme lautet:

anthropic.AuthenticationError: Error code: 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}, 'request_id': 'req_011CSHoEeqs5C35K2UUqR7Fy'}

Wenn der Schlüssel in Ihrer Shell funktioniert, der Dienst jedoch einen 401-Fehler zurückgibt, prüfen Sie, welche Zugangsdaten der Dienst tatsächlich erhalten hat. Ein fehlender Schlüssel ohne alternative Zugangsdaten erzeugt ein lokales TypeError mit Could not resolve authentication method.. Prüfen Sie daher, ob EnvironmentFile= auf den richtigen Pfad verweist. Weitere Ursachen sind versehentlich im Schlüsselwert enthaltene Anführungszeichen. Normale ANTHROPIC_API_KEY="sk-ant-..."-Anführungszeichen werden von systemd und der Shell entfernt. Möglich sind außerdem zusätzliche Zeichen, ein in der Console letzte Woche widerrufener Schlüssel oder ein Schlüssel, dessen Ablaufzeit erreicht wurde.

404 durch einen Tippfehler in der Modell-ID. Eine Variante besteht darin, eine Modell-ID mit einem Datums-Suffix zu versehen, für die keine datierte Form existiert:

anthropic.NotFoundError: Error code: 404 - {'type': 'error', 'error': {'type': 'not_found_error', 'message': 'model: claude-opus-5-5-20260922'}, 'request_id': 'req_011CSJqymAvNw4bT3qmDdMbA'}

IDs der aktuellen Generation müssen exakt wie angegeben verwendet werden: claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, claude-fable-5-2. Eine Ausnahme bilden Modelle vor der Generation 4.6: claude-haiku-4-5 ist ein Alias für die datierte ID claude-haiku-4-5-20251001, und beide Formen funktionieren. Kopieren Sie IDs aus der Modelldokumentation und niemals aus dem Gedächtnis oder einem alten Tutorial.

429 rate_limit_error. Die Fehlerzeichenfolge lautet rate_limit_error. Wenn die Antwort einen retry-after-Header enthält, gibt dieser die Wartezeit in Sekunden an. Das SDK hat vor dem Auftreten der Ausnahme bereits zweimal mit Backoff erneut versucht. Anhaltende 429-Fehler wegen eines Rate-Limits bedeuten daher, dass Sie die Arbeit in Batches aufteilen oder zeitlich verteilen müssen. Verkürzen Sie nicht die Retry-Schleife. Ein 429-Fehler wegen des monatlichen Ausgabenlimits einer Tier-Stufe enthält keinen retry-after-Header und enthält error.details.error_code: "enforced_spend_limit_reached". Die Nutzung wird bis 00:00 UTC am ersten Tag des nächsten Monats pausiert, sofern das Limit nicht vorher erhöht wird.

Das Objekt wird ausgegeben, nicht der Text. Die Ausgabe sieht wie [TextBlock(citations=None, text='...', type='text')] aus. Sie haben response.content ausgegeben, anstatt die Blöcke zu durchlaufen und .text aus den Blöcken zu lesen, bei denen block.type == "text". Jedes SDK-Beispiel oben macht dies korrekt. Kopieren Sie die Schleife.

error: externally-managed-environment. Sie haben pip install mit Ubuntus System-Python 24.04 ausgeführt. Verwenden Sie die venv. Führen Sie auf einem wichtigen Server niemals --break-system-packages aus.

Antworten werden abgeschnitten. response.stop_reason == "max_tokens" bedeutet, dass das Modell mitten im Gedankengang das Ausgabelimit erreicht hat. Das Verhalten ist erwartungsgemäß. Erhöhen Sie das Limit gezielt. Beachten Sie außerdem, dass bei den 5.5-Modellen das Nachdenken dasselbe Limit verbraucht.

Sobald Ihre erste Anwendung funktioniert, macht einen KI-Agenten mit Claude erstellen aus denselben API-Aufrufen einen Agenten, der Tools verwendet.

FAQ

Wie viel kostet es, die Claude API auszuprobieren?

Für ein Tool dieser Art erstaunlich wenig. Im Oktober 2026 kostet Opus 5.5 4 $ pro 1 Million Eingabe-Token und 20 $ pro 1 Million Ausgabe-Token. Eine typische Log-Diagnose mit einigen tausend Eingabe-Token und einigen hundert Ausgabe-Token kostet daher vor Thinking-Token, die als Ausgabe abgerechnet werden, etwa 2 Cent. Mit Haiku 5.5 (0,10 $/0,50 $) liegt der Preis deutlich unter einem Zehntelcent. Ein Monat mit täglichen Zusammenfassungen kostet weniger als ein Kaffee. Das Risiko liegt nicht im Preis pro Aufruf, sondern in unbeschränkten Schleifen und zu großen Ausgabelimits. Deshalb stellt dieses Tool genau eine Anfrage und setzt max_tokens explizit.

Gibt es ein kostenloses Kontingent für die Claude API?

Im Oktober 2026 gibt es kein dauerhaft kostenloses Kontingent. Laut der Preisdokumentation von Anthropic erhalten neue Benutzer eine kleine Menge kostenloser Credits, um die API zu testen. Das ist ein einmaliges Testkontingent. Danach benötigen Sie gekaufte Credits, anrechenbare Credits aus einem monatlichen Tarif oder eine Vereinbarung zur Rechnungsstellung. Max-, Ultra- und Team-Abonnenten bilden eine Ausnahme: Ihre Tarife enthalten monatliche API-Credits, wie oben beschrieben. Wenn Ihr Ziel keine Grenzkosten pro Anfrage statt maximaler Modellqualität sind, können Sie stattdessen ein Open-Weight-Modell mit Ollama selbst hosten und den Speicherbedarf in RAM statt in Token bezahlen.

Wie schütze ich meinen API-Schlüssel auf einem Server?

Niemals im Code, niemals in git, niemals aus .bashrc exportiert und niemals in einer Shell eingegeben, deren Verlauf den Schlüssel speichert. Legen Sie ihn in einer Datei ab, die root gehört und über 600-Berechtigungen verfügt. Laden Sie ihn pro Prozess. Verwenden Sie für die interaktive Nutzung ein Wrapper-Skript und für systemd EnvironmentFile=. Verwenden Sie pro Server oder Projekt jeweils einen eigenen Schlüssel. So lässt sich ein offengelegter Schlüssel gezielt widerrufen, statt den gesamten Zugriff abschalten zu müssen. Sobald der Schlüssel eine Paste-Site oder einen git-Commit erreicht, widerrufen Sie ihn sofort in der Console. Das Löschen des Commits macht den Schlüssel nicht wieder geheim.

Mit welchem Claude-Modell sollte ich beginnen?

Beginnen Sie mit claude-opus-5-5, solange Sie prüfen, ob die Ausgaben als Grundlage ausreichen, und solange Sie die Idee zunächst mit der höchsten Qualität bewerten möchten. Bei einem Hobby-Volumen beträgt der Kostenunterschied nur wenige Cent. Sobald der Prompt feststeht, führen Sie Ihre echten Eingaben erneut mit claude-haiku-5-5 aus. Für Zusammenfassungen, Klassifizierung und Log-Triage ist dieses Modell häufig gut genug und kostet pro Token nur ein Vierzigstel. Wechseln Sie anhand von Messungen zu Haiku oder Sonnet, nicht standardmäßig.

War dieser Artikel hilfreich?