Claude Platform Docs
Documentation

API-Einführung für Claude

Dieser Leitfaden soll Claude die Grundlagen der Nutzung der Claude API vermitteln. Er bietet Erklärungen und Beispiele zu Modell-IDs/der grundlegenden Messages API, Tool-Nutzung, Streaming, Nachdenken und sonst nichts.

API-Einführung für Claude

Dieser Leitfaden soll Claude die Grundlagen der Nutzung der Claude API vermitteln. Er bietet Erklärungen und Beispiele zu Modell-IDs/der grundlegenden Messages API, „tool use“ (Tool-Nutzung), „streaming“ (Streaming), „thinking“ (Nachdenken) und sonst nichts.

Modelle

Recommended default for most work, including complex agentic coding: Claude Opus 5.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2x Claude Opus 5.5 pricing: Claude Fable 5.2: claude-fable-5-2
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5.5: claude-sonnet-5-5
Previous Sonnet model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 5.5: claude-haiku-5-5
Previous Haiku model: Claude Haiku 4.5: claude-haiku-4-5-20251001

Die API aufrufen

Grundlegende Anfrage und Antwort

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Mehrere Gesprächsrunden

Die Messages API ist zustandslos, was bedeutet, dass du immer den vollständigen Gesprächsverlauf an die API sendest. Du kannst dieses Muster verwenden, um ein Gespräch im Laufe der Zeit aufzubauen. Frühere Gesprächsrunden müssen nicht unbedingt tatsächlich von Claude stammen. Du kannst synthetische assistant-Nachrichten verwenden.

Mit Nachrichten-Threads, in der Beta, kann die API die Konversation aufbewahren, sodass jede spätere Anfrage nur die neuen Nachrichten sendet. Ein Thread läuft 5 Minuten nach seiner letzten Anfrage ab und wird spätestens 1 Stunde nach seiner letzten Verwendung gelöscht.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Claudes Antwort vorausfüllen

Du kannst einen Teil von Claudes Antwort an der letzten Position der Liste der Eingabenachrichten vorausfüllen. Verwende diese Technik, um Claudes Antwort zu gestalten. Das folgende Beispiel verwendet "max_tokens": 1, um eine einzelne Multiple-Choice-Antwort von Claude zu erhalten.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message.content[0].text)

Vision

Claude kann sowohl Text als auch Bilder in Anfragen lesen. Für Bilder werden sowohl die Quelltypen base64 als auch url unterstützt, zusammen mit den Medientypen image/jpeg, image/png, image/gif und image/webp.

import anthropic
import base64
import httpx2

# Option 1: Base64-kodiertes Bild
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message.content if block.type == "text"))

# Option 2: Per URL referenziertes Bild
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))

Nachdenken

Nachdenken kann Claude manchmal bei sehr schwierigen Aufgaben helfen. Der aktuelle Mechanismus ist „adaptive thinking“ (adaptives Nachdenken) (thinking: {"type": "adaptive"}): Claude bestimmt, wann und wie viel nachgedacht wird, und du steuerst die Tiefe des Nachdenkens mit dem Parameter effort statt mit einem Token-Budget. Adaptives Nachdenken wird auf Claude 4.6 und neueren Modellen sowie Claude Mythos Preview unterstützt. Auf Claude 5 und neueren Modellen sowie Claude Mythos Preview ist Nachdenken standardmäßig aktiviert, wenn der Parameter thinking weggelassen wird.

Nachdenken wird in den folgenden Modellen unterstützt:

  • Claude Fable 5.2 (claude-fable-5-2, nur adaptives Nachdenken, immer aktiviert)
  • Claude Mythos 5.2 (claude-mythos-5-2, nur adaptives Nachdenken, immer aktiviert)
  • Claude Opus 5.5 (claude-opus-5-5, nur adaptives Nachdenken, immer aktiviert)
  • Claude Sonnet 5.5 (claude-sonnet-5-5, nur adaptives Nachdenken, standardmäßig aktiviert; thinking: {"type": "disabled"} gibt einen 400-Fehler zurück, sende daher thinking: {"type": "between_tools"}, um das vorgelagerte Nachdenken zu deaktivieren)
  • Claude Haiku 5.5 (claude-haiku-5-5, nur adaptives Nachdenken, standardmäßig aktiviert)
  • Claude Fable 5.1 (claude-fable-5-1, nur adaptives Nachdenken, immer aktiviert)
  • Claude Mythos 5.1 (claude-mythos-5-1, nur adaptives Nachdenken, immer aktiviert)
  • Claude Fable 5 (claude-fable-5, nur adaptives Nachdenken, immer aktiviert)
  • Claude Mythos 5 (claude-mythos-5, nur adaptives Nachdenken, immer aktiviert)
  • Claude Opus 5 (claude-opus-5⁠, nur adaptives Nachdenken, standardmäßig aktiviert)
  • Claude Sonnet 5 (claude-sonnet-5, nur adaptives Nachdenken, standardmäßig aktiviert)
  • Claude Opus 4.8 (claude-opus-4-8⁠, nur adaptives Nachdenken)
  • Claude Opus 4.7 (claude-opus-4-7, nur adaptives Nachdenken)
  • Claude Opus 4.6 (claude-opus-4-6, adaptives oder veraltetes manuelles Nachdenken)
  • Claude Sonnet 4.6 (claude-sonnet-4-6, adaptives oder veraltetes manuelles Nachdenken)
  • Claude Opus 4.5 (claude-opus-4-5-20251101, nur veraltetes manuelles Nachdenken)
  • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929, abgekündigt, nur veraltetes manuelles Nachdenken)
  • Claude Haiku 4.5 (claude-haiku-4-5-20251001, nur veraltetes manuelles Nachdenken)

Wie Nachdenken funktioniert

Wenn Nachdenken aktiviert ist, erstellt Claude thinking-Inhaltsblöcke, in denen es sein internes Denken ausgibt. Die API-Antwort enthält thinking-Inhaltsblöcke, gefolgt von text-Inhaltsblöcken.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# Die Antwort enthält zusammengefasste Thinking-Blöcke und Text-Blöcke
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

Manuelles erweitertes Nachdenken (thinking: {"type": "enabled", "budget_tokens": N}) ist der veraltete Mechanismus. Es funktioniert nur auf Claude-Modellen von 4 bis 4.6, die Nachdenken unterstützen; Claude 4.7 und neuere Modelle lehnen type: enabled mit einem 400-Fehler ab und verwenden stattdessen adaptives Nachdenken. Beim manuellen erweiterten Nachdenken legt budget_tokens die maximale Anzahl an Token fest, die Claude für seinen internen Denkprozess verwenden darf; das Limit gilt für die vollständigen Thinking-Token, nicht für die zusammengefasste Ausgabe. Sofern du nicht verschachteltes Nachdenken verwendest, muss budget_tokens kleiner als max_tokens sein, damit Claude nach Abschluss des Nachdenkens Platz hat, seine Antwort zu schreiben.

Nachdenken mit Tool-Nutzung

Nachdenken kann zusammen mit Tool-Nutzung verwendet werden, sodass Claude die Tool-Auswahl und die Verarbeitung der Ergebnisse durchdenken kann.

Wichtige Einschränkungen:

  1. Einschränkung bei der Tool-Auswahl: Beim manuellen erweiterten Nachdenken (thinking: {"type": "enabled"}) wird nur tool_choice: {"type": "auto"} (Standard) oder tool_choice: {"type": "none"} unterstützt. Adaptives Nachdenken akzeptiert erzwungene Tool-Nutzung, außer auf den Modellen, die unter Tool-Nutzung erzwingen aufgeführt sind. Wo sie akzeptiert wird, überspringt ein erzwungener Tool-Aufruf das Nachdenken: Die Antwort beginnt mit dem Tool-Aufruf und enthält keinen thinking-Block.
  2. Thinking-Blöcke beibehalten: Während der Tool-Nutzung musst du thinking-Blöcke für die letzte Assistant-Nachricht an die API zurückgeben.

Thinking-Blöcke beibehalten

Python
import anthropic

client = anthropic.Anthropic()

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city name."}},
        "required": ["location"],
    },
}

weather_data = {"temperature": 72}

# Erste Anfrage – Claude antwortet mit Nachdenken und Tool-Anfrage
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Thinking-Block und Tool-Use-Block extrahieren
thinking_block = next(
    (block for block in response.content if block.type == "thinking"), None
)
tool_use_block = next(
    (block for block in response.content if block.type == "tool_use"), None
)

# Zweite Anfrage – Thinking-Block und Tool-Ergebnis einschließen
continuation = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Beachte, dass sowohl der thinking_block als auch der tool_use_block übergeben werden
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)

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

Verschachteltes Nachdenken

„Interleaved thinking“ (verschachteltes Nachdenken) ermöglicht es Claude, zwischen Tool-Aufrufen nachzudenken und über Tool-Ergebnisse zu reflektieren, bevor es den nächsten Schritt bestimmt.

Auf älteren Modellen, die manuelles erweitertes Nachdenken verwenden (Claude 4-, 4.5- und Sonnet 4.6-Modelle), aktivierst du verschachteltes Nachdenken, indem du den Beta-Header interleaved-thinking-2025-05-14 zu deiner API-Anfrage hinzufügst:

import anthropic

client = anthropic.Anthropic()

calculator_tool = {
    "name": "calculator",
    "description": "Perform arithmetic calculations.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The math expression to evaluate.",
            }
        },
        "required": ["expression"],
    },
}

database_tool = {
    "name": "database_query",
    "description": "Query the product database.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "The database query."}
        },
        "required": ["query"],
    },
}

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[calculator_tool, database_tool],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
        }
    ],
    betas=["interleaved-thinking-2025-05-14"],
)

for block in response.content:
    match block.type:
        case "thinking":
            print(f"Thinking: {block.thinking}")
        case "tool_use":
            print(f"Tool call: {block.name}({block.input})")
        case "text":
            print(f"Response: {block.text}")

Mit verschachteltem Nachdenken und NUR mit verschachteltem Nachdenken (nicht mit regulärem manuellem erweitertem Nachdenken) kann budget_tokens den Parameter max_tokens überschreiten, da budget_tokens in diesem Fall das Gesamtbudget über alle Thinking-Blöcke innerhalb einer Assistant-Runde darstellt.

Tool-Nutzung

Client-Tools angeben

Client-Tools werden im Top-Level-Parameter tools der API-Anfrage angegeben. Jede Tool-Definition enthält:

ParameterBeschreibung
nameDer Name des Tools. Muss dem Regex ^[a-zA-Z0-9_-]{1,128}$ entsprechen.
descriptionEine detaillierte Klartextbeschreibung dessen, was das Tool tut, wann es verwendet werden sollte und wie es sich verhält.
input_schemaEin JSON Schema-Objekt, das die erwarteten Parameter für das Tool definiert.
{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Best Practices für Tool-Definitionen

Stelle äußerst detaillierte Beschreibungen bereit. Dies ist bei Weitem der wichtigste Faktor für die Tool-Leistung. Deine Beschreibungen sollten jedes Detail über das Tool erklären, einschließlich:

  • Was das Tool tut
  • Wann es verwendet werden sollte (und wann nicht)
  • Was jeder Parameter bedeutet und wie er das Verhalten des Tools beeinflusst
  • Alle wichtigen Vorbehalte oder Einschränkungen

Erwäge die Verwendung von input_examples für komplexe Tools. Für Tools mit verschachtelten Objekten, optionalen Parametern oder formatsensitiven Eingaben kannst du mit dem Feld input_examples (Beta) konkrete Beispiele bereitstellen. Dies zeigt Claude die erwarteten Eingabemuster. Siehe Beispiele für Tool-Nutzung bereitstellen für Details.

Beispiel für eine gute Tool-Beschreibung:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Claudes Ausgabe steuern

Tool-Nutzung erzwingen

Du kannst Claude zwingen, ein bestimmtes Tool zu verwenden, indem du das Tool im Feld tool_choice angibst:

tool_choice = {"type": "tool", "name": "get_weather"}

Bei der Arbeit mit dem Parameter tool_choice gibt es vier mögliche Optionen:

  • auto erlaubt Claude zu entscheiden, ob bereitgestellte Tools aufgerufen werden oder nicht (Standard).
  • any teilt Claude mit, dass es eines der bereitgestellten Tools verwenden muss.
  • tool zwingt Claude, immer ein bestimmtes Tool zu verwenden.
  • none verhindert, dass Claude Tools verwendet.

Auf Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 und Claude Mythos 5.1 geben any und tool einen 400-Fehler zurück. Belasse tool_choice auf auto und setze "strict": true in der Tool-Definition, um zu garantieren, dass jeder Aufruf, den Claude tätigt, dem input_schema des Tools entspricht. Siehe Strikte Tool-Nutzung.

JSON-Ausgabe

Tools müssen nicht unbedingt Client-Funktionen sein. Du kannst Tools jederzeit verwenden, wenn das Modell eine JSON-Ausgabe zurückgeben soll, die einem bereitgestellten Schema folgt.

Parallele Tool-Nutzung

Standardmäßig kann Claude mehrere Tools verwenden, um eine Benutzeranfrage zu beantworten. Du kannst dieses Verhalten deaktivieren, indem du disable_parallel_tool_use=true setzt.

Umgang mit Tool-Use- und Tool-Result-Inhaltsblöcken

Umgang mit Ergebnissen von Client-Tools

Die Antwort hat einen stop_reason von tool_use und einen oder mehrere tool_use-Inhaltsblöcke, die Folgendes enthalten:

  • id: Eine eindeutige Kennung für diesen bestimmten Tool-Use-Block.
  • name: Der Name des verwendeten Tools.
  • input: Ein Objekt, das die an das Tool übergebene Eingabe enthält.
{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Wenn du eine Tool-Nutzungs-Antwort erhältst, solltest du:

  1. name, id und input aus dem tool_use-Block extrahieren.
  2. Das tatsächliche Tool in deiner Codebasis ausführen, das diesem Tool-Namen entspricht.
  3. Das Gespräch fortsetzen, indem du eine neue Nachricht mit einem tool_result sendest:
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

Umgang mit dem Stop-Grund max_tokens

Wenn Claudes Antwort abgeschnitten wird, weil sie während der Tool-Nutzung das max_tokens-Limit erreicht, wiederhole die Anfrage mit einem höheren max_tokens-Wert.

Umgang mit dem Stop-Grund pause_turn

Bei der Verwendung von Server-Tools wie der Websuche kann die API einen pause_turn-Stop-Grund zurückgeben. Setze das Gespräch fort, indem du die pausierte Antwort unverändert in einer nachfolgenden Anfrage zurückgibst.

Fehlerbehebung

Fehler bei der Tool-Ausführung

Wenn das Tool selbst während der Ausführung einen Fehler auslöst, gib die Fehlermeldung mit "is_error": true zurück:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Ungültiger Tool-Name

Wenn Claudes versuchte Nutzung eines Tools ungültig ist (zum Beispiel wegen fehlender erforderlicher Parameter), versuche die Anfrage erneut mit detaillierteren description-Werten in deinen Tool-Definitionen.

Streaming von Nachrichten

Beim Erstellen einer Message kannst du "stream": true setzen, um die Antwort inkrementell mithilfe von „server-sent events“ (vom Server gesendete Ereignisse), oder SSE, zu streamen.

Streaming mit SDKs

import anthropic

client = anthropic.Anthropic()

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

Ereignistypen

Jedes vom Server gesendete Ereignis enthält einen benannten Ereignistyp und zugehörige JSON-Daten. Jeder Stream verwendet den folgenden Ereignisablauf:

  1. message_start: enthält ein Message-Objekt mit leerem content.
  2. Eine Reihe von Inhaltsblöcken, jeweils mit content_block_start, einem oder mehreren content_block_delta-Ereignissen und content_block_stop.
  3. Ein oder mehrere message_delta-Ereignisse, die Änderungen auf oberster Ebene am endgültigen Message-Objekt anzeigen.
  4. Ein abschließendes message_stop-Ereignis.

Warnung: Die im Feld usage des message_delta-Ereignisses angezeigten Token-Zahlen sind kumulativ.

Delta-Typen für Inhaltsblöcke

Text-Delta

{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Hello frien" }
}

Input-JSON-Delta

Für tool_use-Inhaltsblöcke sind Deltas partielle JSON-Strings:

{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

Thinking-Delta

Bei der Verwendung von Nachdenken mit Streaming:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}

Beispiel für eine grundlegende Streaming-Anfrage

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

War diese Seite hilfreich?