Über die API

Alles, was in diesem Kurs bisher stand, spielte in einem Fenster: Sie tippen, das Modell antwortet, Sie lesen. Darunter liegt eine zweite Tür, durch die dieselben Modelle erreichbar sind. Sie hat keine Oberfläche, dafür eine Adresse.

Die Oberfläche ist selbst ein Programm

Was Sie im Browser bedienen, redet nicht mit dem Modell. Es redet mit einer Schnittstelle, die

provides programmatic access to Claude models and Claude Managed Agents (externe Seite, platform.claude.com),

und macht damit genau das, was jedes andere Programm auch tun kann. Der Chat-Verlauf, die Knöpfe, der Kopieren-Schalter: alles davon gehört zur Anwendung. Das Modell dahinter sieht nur eine Anfrage über das Netz.

Für die Praxis heißt das zweierlei. Erstens ist jede Beobachtung aus dem Chat-Fenster immer eine Beobachtung über zwei Dinge, das Modell und die Anwendung darüber. Das reicht bis zu der Frage, wer überhaupt geantwortet hat: In ChatGPT lag diese Wahl zeitweise bei einer Automatik, die Geschichte steht in Kapitel 10. Über die Adresse nennen Sie das Modell selbst und bekommen genau dieses. Zweitens steht Ihnen dieselbe Tür offen, wenn Sie etwas bauen wollen, das ohne Mensch davor auskommt.

Der Schlüssel ist ein Ausweis

Um durch diese Tür zu kommen, braucht eine Anfrage einen Schlüssel. Der Begriff führt in die Irre, wenn man an ein Passwort denkt. Ein Passwort gehört einer Person und öffnet ihr Konto. Ein Schlüssel gehört einer Organisation, wird maschinell benutzt und bekommt beim Anlegen einen Typ und eine Lebensdauer:

You choose each key’s type (see Key types) and its expiration when you create it (externe Seite, platform.claude.com)

Zur Wahl stehen Vorgaben von drei Stunden bis dreißig Tagen, eine eigene Dauer oder „nie“. Bei „nie“ übernimmt man den Ablauf selbst, und die Wahl fällt einmal:

expiration is set at creation time and cannot be changed afterward (externe Seite, platform.claude.com)

Dazu lässt er sich eingrenzen. Wer Entwicklung und Betrieb auseinanderhält, gibt jedem einen eigenen Arbeitsbereich, und dann lässt sich je Bereich sehen und begrenzen, was verbraucht wird. Die Dokumentation empfiehlt genau das:

Use workspaces to separate environments and control spend by use case (externe Seite, platform.claude.com)

Beim Verlust zeigt sich dann doch eine Ähnlichkeit zum Passwort. Wer den Schlüssel hat, arbeitet auf Ihre Rechnung und erreicht dieselben Stellen wie Sie. Hinter derselben Adresse liegen die verwalteten Agenten aus dem Zitat oben, dazu hochgeladene Dateien und abgelegte Anleitungen. Die Rechnung ist der sichtbarste Teil des Schadens. Der Anbieter behandelt einen abhandengekommenen Schlüssel entsprechend und rät, ihn beim bloßen Verdacht aus dem Verkehr zu ziehen:

disable or delete any key you suspect has leaked (externe Seite, platform.claude.com)

Zwei Wege stehen dafür bereit, und sie unterscheiden sich in der Umkehrbarkeit: Abschalten lässt sich zurücknehmen, Löschen legt den Schlüssel endgültig ins Archiv.

Jede Anfrage steht für sich

Die zweite Eigenart ist die folgenreichere, und der Anbieter schreibt sie selbst hin:

The Messages API is stateless, which means that you always send the full conversational history to the API (externe Seite, platform.claude.com)

Die Schnittstelle kennt also einzelne Aufrufe, von denen jeder alles mitbringt, was das Modell wissen soll. Eine Unterhaltung entsteht erst dadurch, dass ein Programm den Verlauf aufhebt und bei der nächsten Runde erneut mitschickt.

seitlich verschiebbar

eigene Darstellung, Stand 05.08.2026

Das Chat-Fenster täuscht darüber hinweg, weil es die Arbeit für Sie erledigt: Es hebt den Verlauf auf und schickt ihn bei jeder Runde erneut mit. Ein eigener Aufbau muss das selbst tun. Hier liegt auch die Antwort darauf, warum ein langes Gespräch teurer wird als ein kurzes. Dieselbe Mechanik erklärt auch, warum ein Tool Call zwei Durchläufe kostet, nachzulesen in Kapitel 09.

Gemeint ist damit der Verlauf, den das Modell bei der nächsten Anfrage vor sich hat. Was ein Anbieter für seine eigenen Zwecke speichert, ist eine getrennte Frage mit einer eigenen Antwort je Funktion und je Vertrag; sie steht in Beurteilen und Einordnen, Kapitel 01.

Warum das auch angeht, wer nie programmiert

Man kann diesen Bereich für eine Sache der Entwickler halten. Drei Fälle sagen etwas anderes.

Sie kaufen ein Werkzeug ein. Jede Anwendung mit eingebauter KI spricht im Hintergrund eine solche Schnittstelle an, meistens die eines der großen Anbieter. Was dort an Bedingungen gilt, gilt damit auch für Ihre Daten. Welche Kontoart dabei zum Tragen kommt und was daraus folgt, steht in Beurteilen und Einordnen, Kapitel 01.

Sie verhandeln über Mengen. Was ein Zugang leistet, steht in Grenzen je Minute, und die hängen an einer Stufe, in die eine Organisation eingeordnet wird. Dazu kommt ein monatlicher Deckel, der

set a maximum monthly cost an organization can incur for API usage (externe Seite, platform.claude.com).

Sie beurteilen ein Angebot. Ein Anbieter, der einen festen Monatspreis nennt, zahlt dahinter meist selbst nach Verbrauch. Mit den Einheiten im Kopf lässt sich fragen, was passiert, wenn die Nutzung steigt.

Eine Anfrage an ein Sprachmodell ist ein gewöhnlicher HTTP-Aufruf. Das ist die gute Nachricht für jeden, der schon einmal eine Schnittstelle angesprochen hat, und es bedeutet, dass hier dieselben Werkzeuge greifen wie überall sonst.

Drei Header und ein Rumpf

Der Aufruf geht als POST an eine feste Adresse. Was ihn von einem beliebigen anderen unterscheidet, sind die Header:

Requests to the Claude API include these headers (externe Seite, platform.claude.com)

Header	Wozu
Authorization	Bearer und der Schlüssel oder ein kurzlebiges Token; das ältere x-api-key mit dem Schlüssel geht weiter
anthropic-version	die Fassung der Schnittstelle, etwa 2023-06-01
content-type	application/json

Ein Schlüssel, der für mehrere Arbeitsbereiche gilt, braucht dazu anthropic-workspace-id, damit die Anfrage weiß, wohin sie gehört.

Die Versionsangabe ist die interessanteste der drei, und sie verspricht weniger, als der Name nahelegt. Erhalten bleiben die vorhandenen Ein- und Ausgabefelder, damit ein laufendes Programm weiterläuft:

Generally, if you are using the API as documented in this reference, Anthropic will not break your usage (externe Seite, platform.claude.com)

Die Antwortform kann sich innerhalb derselben Version trotzdem ändern. Dieselbe Seite führt auf, was sich der Anbieter vorbehält: zusätzliche Ausgabewerte, geänderte Bedingungen einzelner Fehlertypen und

Add new variants to enum-like output values (externe Seite, platform.claude.com)

Wer sein Programm dagegen hart macht, verträgt also unbekannte Felder, statt sich auf die Zahl zu verlassen. Umgekehrt kostet die Zahl auch weniger, als viele annehmen: Die Versionsliste (externe Seite, platform.claude.com) hat seit Juni 2023 keinen Eintrag mehr bekommen, und alles, was seither dazugekommen ist, kam unter derselben Angabe.

Im Rumpf steht das Modell, eine Obergrenze für die Ausgabe und die Nachrichten, jede mit einer Rolle. Mehr braucht es für einen ersten Aufruf nicht. Die Bibliotheken der Anbieter setzen die Header selbst und wiederholen vorübergehende Fehler von sich aus, allerdings in engen Grenzen:

The official SDKs automatically retry transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the retry-after header when present (externe Seite, platform.claude.com)

Der Schlüssel gehört in den Serverraum

Eine Anfrage lässt sich technisch auch aus dem Browser abschicken. Genau das ist der häufigste Fehler beim ersten eigenen Aufbau, denn wer den Schlüssel an den Browser ausliefert, hat ihn veröffentlicht. Jeder Besucher kann ihn aus dem Quelltext lesen und auf Ihre Rechnung arbeiten.

Der übliche Aufbau schiebt deshalb einen eigenen kleinen Dienst dazwischen. Der Browser spricht mit Ihrem Dienst, Ihr Dienst spricht mit dem Anbieter, und der Schlüssel verlässt nie den Serverraum. Das kostet einen Baustein mehr und bringt zwei Dinge mit, die Sie ohnehin brauchen werden: eine Stelle, an der sich mitzählen lässt, wer wie viel verbraucht, und eine Stelle, an der sich Missbrauch abfangen lässt.

Für den Fall, in dem dieser Baustein fehlt, gibt es einen eigenen Weg. Eine ausgelieferte App kann sich beim Anbieter als echte Installation ausweisen und bekommt dafür ein kurzlebiges Zugangsmerkmal, gedacht für

iOS and macOS apps distributed to end users, where the app calls the Claude API directly with no back end or proxy (externe Seite, platform.claude.com)

Ausgeliefert wird dabei ein Merkmal mit kurzer Haltbarkeit, der dauerhafte Schlüssel bleibt, wo er ist.

Drei Grenzen laufen nebeneinander

Was ein Zugang leistet, ist begrenzt, und die Begrenzung hat mehrere Dimensionen. Wofür sie gilt, sagt die Dokumentation gleich im ersten Satz:

To mitigate misuse and manage capacity on the API, limits are in place on how much an organization can use the Claude API (externe Seite, platform.claude.com)

Gemessen wird also der Zugang über die Schnittstelle, und zwar je Organisation. Was in einer Chat-Anwendung gilt, steht dort nicht. Ein Abo bringt eigene Nutzungsgrenzen mit, die anders gemessen und anders gemeldet werden. Wer in ChatGPT oder Claude an eine Grenze stößt, bekommt einen Hinweis im Gespräch. Ein Fehlercode entsteht an der Schnittstelle.

Der Anbieter beschreibt die Begrenzung des Zugangs als das, was

set the maximum number of API requests an organization can make over a defined period of time (externe Seite, platform.claude.com),

und misst dabei drei Größen getrennt: Anfragen je Minute, Eingabe-Token je Minute, Ausgabe-Token je Minute.

seitlich verschiebbar

eigene Darstellung, Stand 05.08.2026

Die praktische Folge ist, dass verschiedene Anwendungen an verschiedenen Grenzen anstoßen. Ein Dienst mit vielen kurzen Anfragen läuft in die Anfragengrenze. Ein Dienst, der lange Dokumente auswertet, läuft in die Eingabegrenze, während er bei den Anfragen weit unter dem Erlaubten bleibt. Wer nur eine Zahl im Kopf hat, sucht den Fehler an der falschen Stelle.

Die Grenzen gelten je Modell und je Organisation. Zwei Modelle nebeneinander zu benutzen, zieht deshalb meistens aus zwei getrennten Töpfen. Die Ausnahme steht als Fußnote unter derselben Tabelle und trifft ausgerechnet den häufigsten Fall, mehrere Fassungen derselben Familie:

Opus rate limit is a total limit that applies to combined traffic across Claude Opus 4.8, Opus 4.7, Opus 4.6, and Opus 4.5 (externe Seite, platform.claude.com)

Wer während eines Wechsels beide Fassungen fährt, teilt sich also ein Kontingent. Welche Kennungen zusammengefasst sind, steht in der Tabelle und ändert sich mit jeder neuen Modellreihe.

Was bei einer Abweisung zu tun ist

Wird eine Grenze erreicht, kommt die Antwort mit dem Code 429 zurück, in der Fehlerliste geführt als

Your organization has hit a rate limit (externe Seite, platform.claude.com).

Zwei Dinge stehen dann in der Antwort, und beide sind nützlich. Ein Header retry-after nennt die Zahl der Sekunden bis zum nächsten Versuch. Und die Fehlermeldung sagt, welche der drei Grenzen erreicht wurde.

Der falsche Reflex ist, sofort erneut zu fragen. Der richtige Umgang steht in derselben Doku, dort für den Fall eines Serverfehlers, und gilt hier genauso:

Retry the request with exponential backoff (externe Seite, platform.claude.com)

Also warten, dann noch einmal doppelt so lange warten, und dabei die genannte Wartezeit beachten. Wer stattdessen in einer engen Schleife nachfragt, bekommt dieselbe Abweisung ein zweites Mal und erzeugt zusätzliche Last, die nichts einbringt. Dass auch ein sprunghafter Anstieg für sich genommen zur Abweisung führt, steht in Ebene 3.

Der Deckel über allem

Neben den Mengen je Minute steht eine zweite Art Grenze, die im Alltag seltener auffällt und dann umso härter trifft. Sie

set a maximum monthly cost an organization can incur for API usage (externe Seite, platform.claude.com),

und wenn dieser Betrag erreicht ist, ruht der Zugang bis zum nächsten Monat. Die Beträge hängen an der Nutzungsstufe: bei der Einstiegsstufe dreistellig, auf der zweiten vierstellig, ganz oben sechsstellig. Für einen Versuchsaufbau ist das viel, für einen Dienst mit echten Nutzern kann es der Betrag einer Woche sein.

Auch diese Abweisung kommt als 429, derselbe Code wie oben bei den Minutengrenzen. Der Umgang damit unterscheidet sich trotzdem: Ein Header mit der Wartezeit fehlt, und wer es dennoch mit Zurückhalten und erneutem Versuch probiert, bekommt dieselbe Abweisung, bis der Monat wechselt oder jemand den Deckel anhebt. Der Rat aus dem vorigen Abschnitt gilt also nur für die eine, nicht für die andere Art von Grenze.

Ein eigener, niedrigerer Deckel lässt sich zusätzlich setzen, und für die einzelnen Arbeitsbereiche ebenfalls. Das ist die Stelle, an der ein Fehler im eigenen Code aufhört, teuer zu werden. Was die einzelne Anfrage kostet und warum die Ausgabe die teure Spalte ist, steht in Kapitel 10.

Die Zahlen aus Ebene 2 beschreiben, was erlaubt ist. Interessant wird es an der Frage, wie sie gemessen werden, denn davon hängt ab, ob ein Aufbau mit denselben Grenzen das Doppelte schafft oder die Hälfte.

Das Kontingent füllt sich fortlaufend

Die naheliegende Vorstellung ist ein Zähler, der zur vollen Minute auf null springt. So arbeitet die Messung nicht:

your capacity is continuously replenished up to your maximum limit, rather than being reset at fixed intervals (externe Seite, platform.claude.com)

Das Verfahren heißt Token-Bucket und ist im Netzbetrieb seit Jahrzehnten üblich. Man stelle sich einen Eimer vor, der stetig nachläuft und eine Höchstmarke hat. Jede Anfrage schöpft daraus, und wer schneller schöpft als nachläuft, steht irgendwann vor einem leeren Eimer.

Daraus folgt ein Verhalten, das viele zunächst für einen Fehler halten. Die Doku benennt es selbst: Eine Grenze von 60 Anfragen je Minute kann als eine Anfrage je Sekunde durchgesetzt werden. Sechzig Aufrufe gleichzeitig abzuschicken, führt deshalb zu Abweisungen, obwohl die Minutenzahl eingehalten ist. Gleichmäßig verteilt reicht dasselbe Kontingent weiter.

Dieselbe Mechanik erklärt einen zweiten Fall. Auch ein zu schneller Anstieg wird gebremst, unabhängig von den Minutengrenzen:

You might also encounter 429 errors because of acceleration limits on the API if your organization has a sharp increase in usage (externe Seite, platform.claude.com)

Der Fehlercode ist derselbe wie bei einer erreichten Minutengrenze, der Anlass ein anderer, und der Rat lautet, den Verkehr allmählich hochzufahren. Nach einem 429 lohnt deshalb zuerst der Blick auf den Verlauf der letzten Minuten, erst danach auf die einzelne Zahl.

Was zwischengespeichert ist, zählt nicht mit

Hier liegt der größte Hebel, und er wird regelmäßig übersehen, weil er unter einem Kostenthema abgelegt ist:

For most Claude models, only uncached input tokens count toward your ITPM rate limits (externe Seite, platform.claude.com)

seitlich verschiebbar

eigene Darstellung, Stand 05.08.2026

Die Doku rechnet ein Beispiel vor: Bei zwei Millionen erlaubten Eingabe-Token je Minute und einer Trefferquote von 80 Prozent im Cache lassen sich zehn Millionen verarbeiten. Der Faktor fünf entsteht ohne jede Verhandlung über höhere Grenzen.

Das „most“ im Zitat hat dabei einen konkreten Adressaten. In derselben Tabelle steht an einem älteren Modell eine Fußnote, und für dieses eine zählen auch die wiederverwendeten Token gegen die Minutengrenze. Vor dem Einplanen des Hebels gehört die Zeile des eigenen Modells also nachgeschlagen.

Der Unterschied zum Preisthema ist wichtig. In Kapitel 10 geht es darum, dass zwischengespeicherte Eingabe billiger abgerechnet wird. Hier geht es darum, dass sie beim Durchsatz gar nicht mitgezählt wird. Beides zusammen macht aus einer Systemanweisung, die bei jeder Anfrage identisch mitreist, den lohnendsten Kandidaten für eine feste Marke im Cache.

Die Kehrseite: Eine Marke, die bei jeder Anfrage anders gesetzt wird, verliert beides gleichzeitig. Und eine geänderte Konfiguration kann den Cache ebenfalls entwerten, etwa eine Tool-Liste, die zwischen zwei Anfragen wächst. Die Grafik oben führt sie als einen der Teile, die sonst über alle Aufrufe gleich bleiben.

Auf der Ausgabeseite gilt eine andere Rechnung, und sie räumt einen verbreiteten Verdacht aus. Gezählt wird dort, was tatsächlich erzeugt wurde:

The max_tokens parameter does not factor into OTPM rate limit calculations, so there is no rate limit downside to setting a higher max_tokens value (externe Seite, platform.claude.com)

Eine großzügig gesetzte Obergrenze kostet also nichts, solange die Antwort kurz ausfällt.

Eine Grenze ist eine Obergrenze

Der Satz, der die Erwartung an diese Zahlen zurechtrückt, steht in der Doku selbst:

All limits described here represent maximum allowed usage, not guaranteed minimums (externe Seite, platform.claude.com)

Das ist mehr als eine juristische Absicherung. Es heißt, dass eine erreichte Grenze und eine ausbleibende Antwort zwei verschiedene Ereignisse sind, die sich nur bei genauem Hinsehen unterscheiden lassen. Ein 429 sagt, dass Sie zu viel wollten. Ein 529 meldet den Zustand

The API is temporarily overloaded (externe Seite, platform.claude.com),

und die Fehlerseite nennt den Fall dazu: hoher Verkehr über alle Nutzer hinweg. Beide führen dazu, dass keine Antwort kommt, und beide erfordern verschiedene Reaktionen: Im ersten Fall hilft es, den eigenen Takt zu senken, im zweiten hilft nur Warten.

Für einen Aufbau, der etwas zusagen muss, folgt daraus eine unbequeme Konsequenz. Eine Verfügbarkeitszusage gegenüber dem eigenen Nutzer kann sich nicht auf die Grenzen des Anbieters stützen, weil dort ausdrücklich keine Untergrenze zugesagt ist. Eine solche Zusage braucht deshalb einen zweiten Weg.

Zurückhalten, und zwar mit Kennung

Die Bibliotheken der Anbieter wiederholen vorübergehende Fehler von sich aus, zweimal, mit wachsendem Abstand und unter Beachtung der genannten Wartezeit. Das deckt den Normalfall ab und hört danach auf. Wer selbst baut, hält sich an dieselbe Regel und setzt eine Streuung dazu: Laufen zehn Kopien desselben Dienstes, warten sie nach einer Abweisung sonst alle gleich lang und stoßen gemeinsam wieder an.

Zwei Feinheiten fallen dabei leicht unter den Tisch. Erstens ist eine Wiederholung bei einem 400 sinnlos, dort ist die Anfrage selbst fehlerhaft, und eine Schleife darüber erzeugt nur Last. Zweitens hat jede Antwort eine Kennung:

Every API response includes a unique request-id header (externe Seite, platform.claude.com)

Mit ihr im Protokoll lässt sich später über einen einzelnen Vorfall sprechen. Ohne sie bleibt bei einer Rückfrage an den Anbieter nur die ungefähre Uhrzeit.

Dieselbe Sprache auf dem eigenen Rechner

Der Aufbau lässt sich vom Anbieter lösen, und im günstigen Fall merkt die Anwendung davon wenig. Programme, die Modelle lokal ausführen, sprechen dieselbe Form:

Connect OpenAI clients to Ollama. Ollama supports a subset of the OpenAI API. (externe Seite, docs.ollama.com)

Das Wort subset ist dabei die eigentliche Auskunft. Im einfachsten Fall genügt eine geänderte Adresse, und im Beispiel der Doku steht dann noch ein Schlüssel, versehen mit dem Vermerk

required but ignored (externe Seite, docs.ollama.com).

Wo niemand abrechnet, bleibt von ihm eine Formalie übrig. Dass er hier keine Rechte prüft, ist eine Eigenschaft dieses lokalen Zugangs. Über das, was ein Schlüssel beim Anbieter aufschließt, sagt es nichts.

Zwei Handgriffe kommen trotzdem hinzu, beide auf derselben Seite. Das Modell muss vorher geholt werden, und eine Anwendung, die auf feste Modellnamen des Anbieters eingestellt ist, braucht einen passenden Namen auf der anderen Seite:

For tooling that relies on default OpenAI model names such as gpt-3.5-turbo, use ollama cp to copy an existing model name to a temporary name (externe Seite, docs.ollama.com)

Was darüber hinaus zu tun ist, hängt daran, welche Felder eine Anwendung benutzt. Die Seite zählt sie einzeln auf, Endpunkt für Endpunkt, und diese Liste ist die belastbare Antwort auf die Frage, wie teuer ein Wechsel wird.

Damit bekommt die Betriebsfrage aus Beurteilen und Einordnen, Kapitel 01 eine technische Untergrenze: Der Wechsel zwischen einem Anbieter und dem eigenen Rechner fängt bei einer Zeile an. Was danach kommt, steht dort, von der Modellgüte über die Stromrechnung bis zu der Frage, um die es dort eigentlich geht: wer die Eingaben rechtlich verarbeiten darf. Die Geschwindigkeit hat einen eigenen Ort, weil sie am Gerät gemessen werden muss: eine Messung über sieben Beschleunigungsverfahren.

Was die Anwendung dazutut

Zum Schluss die Gegenrichtung, weil sie erklärt, warum ein selbst gebauter Zugang zunächst schlechter wirkt als das gewohnte Fenster. Zwischen dem Modell und dem, was Sie im Browser sehen, liegt eine ganze Schicht, beschrieben in Kapitel 01: Verlaufsverwaltung, Tools, Cache, Sicherheitsfilter, gestreamte Ausgabe.

Wer selbst baut, bekommt das Modell und muss diese Schicht selbst stellen. Das ist der eigentliche Aufwand, und er erklärt, warum die erste eigene Anwendung in zehn Minuten steht und die zweite Fassung Wochen braucht.

Ein Stück davon ist inzwischen beim Anbieter zu haben, und dann fällt genau die Eigenschaft weg, an der das ganze Kapitel hängt:

Claude Managed Agents is a stateful resource; session transcripts persist until you delete them (externe Seite, platform.claude.com)

Wer diesen Weg nimmt, tauscht die Verlaufsverwaltung im eigenen Code gegen ein Protokoll, das beim Anbieter liegt, bis jemand es löscht. Aus einer Bauentscheidung wird damit eine Frage an den Vertrag: wie lange es dort liegt und wer es sehen darf. Das ist dieselbe Frage, die Beurteilen und Einordnen, Kapitel 01 für die Eingaben stellt, nur an einer Stelle, an der man sie zuletzt vermutet.