Claude API: Erste Schritte für Entwickler

1. Was die Claude API ist und wann man sie braucht

Die Claude API ist die programmatische Schnittstelle zu den Claude-Modellen von Anthropic. Während die Weboberfläche unter claude.ai für interaktive Gespräche gedacht ist, richtet sich die API an Entwickler, die Claude in eine eigene Anwendung, ein Backend-Skript oder eine Automatisierung einbetten wollen: Ein PHP-Backend, das Produktbeschreibungen generiert, ein Node-Service, der Support-Tickets vorklassifiziert, oder ein CLI-Tool, das Log-Dateien zusammenfasst, sprechen alle mit demselben REST-Endpunkt. Es gibt keine grafische Oberfläche zwischen Anwendung und Modell, nur HTTP-Requests mit JSON-Payloads.

Der zentrale Endpunkt ist POST https://api.anthropic.com/v1/messages. Alles, was mit Claude programmatisch passiert, läuft über diesen einen Endpunkt: einfache Chat-Anfragen, Tool-Aufrufe, Bildanalyse und strukturierte Ausgaben. Es gibt keine separaten Endpunkte für unterschiedliche Aufgaben. Für den Einstieg reicht ein Verständnis von drei Dingen: wie man sich authentifiziert, wie die Anfrage aufgebaut ist und wie die Antwort verarbeitet wird. Genau diese drei Punkte deckt dieser Artikel praktisch ab, inklusive lauffähiger Beispiele in PHP und JavaScript.

2. API-Key erstellen und Zugangsdaten sichern

Ein API-Key wird in der Anthropic Console (console.anthropic.com) erstellt, innerhalb eines Workspace der eigenen Organisation. Jeder Key ist an eine Organisation und optional an einen Workspace gebunden, was getrennte Budgets und Berechtigungen für unterschiedliche Projekte oder Teams ermöglicht. Der Key beginnt typischerweise mit sk-ant- und wird nur einmal im Klartext angezeigt. Wer ihn verliert, muss einen neuen erstellen und den alten widerrufen, ein nachträgliches Anzeigen ist aus Sicherheitsgründen nicht möglich.

Der Key gehört niemals direkt in den Quellcode. Die gängige Praxis ist eine Umgebungsvariable, ANTHROPIC_API_KEY, die von den offiziellen SDKs automatisch erkannt wird. In lokalen Projekten landet der Wert in einer .env-Datei, die über .gitignore vom Versionierungssystem ausgeschlossen ist. In Produktionsumgebungen übernehmen Secret-Manager oder die Umgebungsvariablen des Hosting-Anbieters diese Aufgabe. Ein im Repository committeter Key ist kein theoretisches Risiko, automatisierte Scanner durchsuchen öffentliche Repositories gezielt nach genau diesem Muster.

Abrechnung erfolgt nutzungsbasiert pro Token, getrennt nach Input- und Output-Token und abhängig vom gewählten Modell. Claude Haiku 4.5 ist das günstigste und schnellste Modell für einfache Aufgaben, Claude Sonnet 5 bietet die beste Balance aus Geschwindigkeit und Fähigkeiten für die meisten Anwendungsfälle, und Claude Opus 4.8 ist das leistungsfähigste Modell für komplexe Aufgaben. Für erste Experimente genügt ein kleines Guthaben, die Konsole zeigt den aktuellen Verbrauch in Echtzeit an.

3. Die Messages API: system, messages und model

Jede Anfrage an /v1/messages braucht mindestens drei Felder: model als Modell-Bezeichner, max_tokens als Obergrenze für die Antwortlänge, und messages als Array abwechselnder Nutzer- und Assistenten-Nachrichten. Das erste Element in messages muss von der Rolle user sein, danach wechseln sich user und assistant ab. Jede Nachricht besteht aus role und content, wobei content entweder ein einfacher String oder ein Array typisierter Content-Blöcke sein kann, etwa für Text, Bilder oder Dateien.

Der system Prompt ist bewusst kein Teil des messages-Arrays, sondern ein eigenes Top-Level-Feld. Er definiert Rolle, Ton und Randbedingungen für das gesamte Gespräch, zum Beispiel „Du bist ein Assistent, der ausschließlich mit gültigem JSON antwortet.“ Diese Trennung ist kein Implementierungsdetail, sondern strukturell wichtig: Ein system Prompt als erste Nachricht im messages-Array zu simulieren funktioniert zwar technisch, verschenkt aber die klare Trennung zwischen Verhaltensvorgabe und Konversationsverlauf und erschwert späteres Prompt-Caching. Jede Anfrage braucht außerdem die Header x-api-key, anthropic-version und content-type: application/json.

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "system": "You are a concise assistant for a German e-commerce team. Answer in German unless asked otherwise.",
  "messages": [
    { "role": "user", "content": "Write one sentence describing a red running shoe." }
  ]
}

// Response shape (abbreviated)
{
  "id": "msg_01abc...",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Ein leichter roter Laufschuh für schnelle Tempoläufe." }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 28, "output_tokens": 14 }
}

4. Die erste Anfrage: cURL-Minimalbeispiel

Der schnellste Weg, die Claude API ohne jede Abhängigkeit zu testen, ist ein einzelner cURL-Aufruf im Terminal. Damit lässt sich prüfen, ob der API-Key korrekt gesetzt ist und ob die Anfrage grundsätzlich funktioniert, bevor überhaupt Code geschrieben wird. Das ist auch beim Debugging späterer Integrationen der erste sinnvolle Schritt: Wenn ein PHP- oder Node-Skript einen Fehler wirft, klärt derselbe cURL-Befehl mit denselben Parametern innerhalb von Sekunden, ob das Problem im eigenen Code oder in der Anfrage selbst liegt.

Die Antwort ist ein JSON-Objekt mit einem content-Array. Jeder Block darin hat einen type, im einfachsten Fall text mit dem eigentlichen Antworttext. Das Feld stop_reason zeigt, warum die Generierung endete, üblicherweise end_turn bei einer natürlich abgeschlossenen Antwort oder max_tokens, wenn die Obergrenze erreicht wurde, bevor Claude fertig war. Das usage-Objekt liefert die tatsächlich verbrauchten Input- und Output-Token, wichtig für Kostenkontrolle und für das spätere Tuning von max_tokens.

# Set the key once per shell session, never hardcode it in scripts
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

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-4-8",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "What is the capital of Germany?"}
    ]
  }'

# Extract just the answer text with jq
response=$(curl -s 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-4-8","max_tokens":256,"messages":[{"role":"user","content":"Hello"}]}')

echo "$response" | jq -r '.content[0].text'

5. PHP-Beispiel: die Claude API in einem Skript nutzen

Für PHP stellt Anthropic ein offizielles SDK bereit, installierbar über composer require anthropic-ai/sdk. Das SDK übernimmt Authentifizierung, Header-Aufbau und Fehlerklassifizierung, sodass ein eigenes HTTP-Client-Setup mit Guzzle oder cURL nicht nötig ist. Der Client liest den API-Key standardmäßig aus der Umgebungsvariable ANTHROPIC_API_KEY, ein expliziter Parameter im Konstruktor ist nur nötig, wenn mehrere Keys parallel verwendet werden, etwa für unterschiedliche Mandanten in einer Multi-Tenant-Anwendung.

Die Antwort des SDK ist ein typisiertes Objekt, dessen content-Eigenschaft ein Array polymorpher Blöcke ist. Vor dem Zugriff auf ->text muss der Block-Typ geprüft werden, weil ein Block auch ein anderer Typ sein kann, etwa ein Denk-Block bei aktiviertem Thinking. Dieses Muster mit Typ-Prüfung ist kein PHP-spezifisches Detail, sondern zieht sich durch alle offiziellen SDKs und verhindert, dass ein Skript bei einer unerwarteten Antwortstruktur mit einem Fatal Error abbricht.

<?php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Anthropic\Client;

// The client reads ANTHROPIC_API_KEY from the environment automatically
$client = new Client();

$message = $client->messages->create(
    model: 'claude-opus-4-8',
    maxTokens: 512,
    system: 'You write short, factual product summaries in German.',
    messages: [
        ['role' => 'user', 'content' => 'Summarize a waterproof hiking backpack in two sentences.'],
    ],
);

// content is polymorphic - always check the block type before reading ->text
foreach ($message->content as $block) {
    if ($block->type === 'text') {
        echo $block->text . PHP_EOL;
    }
}

echo 'Tokens used: ' . $message->usage->outputTokens . PHP_EOL;

6. JavaScript-Beispiel: Anfrage vom Server aus

Im Node.js-Umfeld übernimmt @anthropic-ai/sdk, installierbar über npm install @anthropic-ai/sdk, dieselbe Rolle wie das PHP-SDK. Wichtig: Die Claude API wird ausschließlich serverseitig aufgerufen, niemals direkt aus Browser-JavaScript, weil der API-Key sonst im Client-Bundle sichtbar wäre und von jedem Besucher ausgelesen werden könnte. Ein typisches Setup ist ein kleiner Express- oder Fastify-Endpunkt, der die Anfrage entgegennimmt, an Claude weiterleitet und nur das Ergebnis an das Frontend zurückgibt.

Die JavaScript-Antwortstruktur entspricht exakt der von PHP und cURL, weil alle SDKs dieselbe JSON-Struktur der REST-API abbilden, lediglich mit sprachtypischer Benennung. Ein Skript, das lokal mit node script.js läuft, eignet sich hervorragend zum schnellen Testen von Prompts, bevor sie in eine größere Anwendung integriert werden, etwa in eine bestehende Node-Middleware oder einen Lambda-Handler.

import Anthropic from "@anthropic-ai/sdk";

// Reads ANTHROPIC_API_KEY from the environment automatically
const client = new Anthropic();

async function main() {
  const message = await client.messages.create({
    model: "claude-opus-4-8",
    max_tokens: 512,
    system: "You write short, factual product summaries in German.",
    messages: [
      { role: "user", content: "Summarize a waterproof hiking backpack in two sentences." },
    ],
  });

  // content is a discriminated union - narrow by .type before reading .text
  for (const block of message.content) {
    if (block.type === "text") {
      console.log(block.text);
    }
  }

  console.log(`Tokens used: ${message.usage.output_tokens}`);
}

main().catch((error) => {
  console.error("Request failed:", error.message);
  process.exit(1);
});

7. Streaming vs. Non-Streaming Responses

In der Standardeinstellung wartet eine Anfrage, bis die komplette Antwort fertig generiert ist, und liefert erst dann ein einziges JSON-Objekt zurück. Das ist einfach zu verarbeiten, aber bei langen Antworten spürbar langsam für den Nutzer, der bis zur letzten generierten Silbe nichts sieht. Mit "stream": true in der Anfrage liefert die API stattdessen einen Strom von Server-Sent Events, sodass Text erscheint, während er generiert wird, genau wie in der Chat-Oberfläche von claude.ai.

Der Event-Strom besteht aus mehreren Event-Typen: message_start zu Beginn, content_block_start und content_block_delta für jedes neue Textstück, content_block_stop beim Abschluss eines Blocks, message_delta mit Metadaten wie stop_reason, und message_stop am Ende. Für eine Chat-Oberfläche mit Live-Anzeige ist Streaming fast immer die richtige Wahl. Eine zweite, oft übersehene Regel: Bei einer hohen max_tokens-Grenze, etwa oberhalb von 16.000 Token, sollte grundsätzlich gestreamt werden, weil eine nicht-gestreamte Anfrage bei langer Generierungszeit ein HTTP-Timeout riskiert, unabhängig davon, ob die Antwort live angezeigt wird oder nicht.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function streamAnswer() {
  const stream = client.messages.stream({
    model: "claude-opus-4-8",
    max_tokens: 1024,
    messages: [
      { role: "user", content: "Explain streaming responses in three short paragraphs." },
    ],
  });

  // Print text deltas as they arrive
  stream.on("text", (delta) => {
    process.stdout.write(delta);
  });

  // finalMessage() resolves once the stream completes, giving the full response
  const finalMessage = await stream.finalMessage();
  console.log(`\n\nTotal output tokens: ${finalMessage.usage.output_tokens}`);
}

streamAnswer();

8. Fehlerbehandlung, Rate Limits und Retries

Die Claude API meldet Fehler über HTTP-Statuscodes und ein strukturiertes JSON-Fehlerobjekt. 400 bedeutet eine fehlerhafte Anfrage, etwa ein fehlendes Pflichtfeld, 401 einen ungültigen API-Key, 429 ein überschrittenes Rate Limit, und Codes ab 500 einen Fehler auf Anthropic-Seite. Wichtig für den Programmierstil: Fehler niemals über String-Matching der Fehlermeldung abfangen, sondern über typisierte Exception-Klassen, die alle offiziellen SDKs bereitstellen, etwa RateLimitError oder AuthenticationError in PHP und JavaScript.

Rate Limits sind pro Organisation nach Requests pro Minute und Token pro Minute begrenzt und hängen vom Nutzungstarif ab. Bei einem 429-Fehler liefert der Header retry-after die empfohlene Wartezeit in Sekunden. Die offiziellen SDKs wiederholen 429- und 5xx-Fehler bereits automatisch mit exponentiellem Backoff, standardmäßig zwei Wiederholungen, konfigurierbar über den Client. Für eigene Retry-Logik außerhalb der SDKs, etwa bei rohen HTTP-Aufrufen, gilt dasselbe Muster: exponentiell steigende Wartezeit zwischen den Versuchen, eine Obergrenze für die Anzahl der Wiederholungen, und ein sofortiger Abbruch bei 4xx-Fehlern, die kein Rate Limit sind, weil ein wiederholter Versuch dort nichts ändert.

9. Anfängerfehler im direkten Vergleich

Die meisten Fehler beim Einstieg in die Claude API sind strukturell dieselben, egal ob in PHP, JavaScript oder direkt per cURL entwickelt wird. Die folgende Übersicht zeigt die häufigsten Anfängerfehler neben dem empfohlenen Muster.

Kein einzelner dieser Fehler ist schwer zu beheben, aber in Kombination summieren sie sich zu einer Integration, die im Test funktioniert und in Produktion unter Last oder bei Netzwerkproblemen ausfällt. Wer die Muster aus der Tabelle von Anfang an anwendet, spart sich später größere Refactorings.

10. Zusammenfassung

Der Einstieg in die Claude API läuft immer über dieselben Grundbausteine: ein API-Key aus der Anthropic Console, sicher als Umgebungsvariable gespeichert, eine Anfrage an /v1/messages mit den Feldern model, max_tokens und messages, sowie ein optionales, aber empfehlenswertes system-Feld für Verhaltensvorgaben. Die offiziellen SDKs für PHP und JavaScript übernehmen Authentifizierung, Fehlerklassifizierung und Retry-Logik, sodass sich eigener Code auf die eigentliche Aufgabe konzentrieren kann statt auf HTTP-Details.

Streaming ist die richtige Wahl für interaktive Oberflächen und für Anfragen mit hoher max_tokens-Grenze, während einfache Batch-Verarbeitung oft ohne Streaming auskommt. Wer von Anfang an typisierte Fehlerbehandlung, respektierte Rate Limits und eine saubere Trennung von system Prompt und Nachrichtenverlauf einbaut, vermeidet die häufigsten Stolperfallen und hat eine Basis, die sich ohne größere Umbauten zu komplexeren Anwendungsfällen wie Tool-Use oder strukturierten Ausgaben erweitern lässt.

11. FAQ: Claude API für Entwickler