API-Nutzungsleitfaden für Claude

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

Modelle

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

Aufrufen der API

Grundlegende Anfrage und Antwort

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-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.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-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)

Vorausfüllen von Claudes Antwort

Du kannst einen Teil von Claudes Antwort an der letzten Position der Liste der Eingabenachrichten vorausfüllen („prefill“). Verwende diese Technik, um Claudes Antwort zu formen. 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 in Anfragen sowohl Text als auch Bilder 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",
    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",
    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"))

Denken

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

Die Temperatur muss auf allen Modellen auf 1 gesetzt (oder nicht gesetzt) sein, wenn Denken aktiviert ist. Auf Claude 4.7 und neueren Modellen sowie Claude Mythos Preview ist temperature abgekündigt und es wird nur der Standardwert akzeptiert, auch wenn Denken deaktiviert ist.

Denken wird in den folgenden Modellen unterstützt:

• Claude Opus 5 (claude-opus-5, nur adaptives Denken, standardmäßig aktiviert)
• Claude Sonnet 5 (claude-sonnet-5, nur adaptives Denken, standardmäßig aktiviert)
• Claude Opus 4.8 (claude-opus-4-8, nur adaptives Denken)
• Claude Opus 4.7 (claude-opus-4-7, nur adaptives Denken)
• Claude Opus 4.6 (claude-opus-4-6, adaptives oder veraltetes manuelles Denken)
• Claude Sonnet 4.6 (claude-sonnet-4-6, adaptives oder veraltetes manuelles Denken)
• Claude Opus 4.5 (claude-opus-4-5-20251101, nur veraltetes manuelles Denken)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929, nur veraltetes manuelles Denken)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001, nur veraltetes manuelles Denken)

Wie Denken funktioniert

Wenn Denken aktiviert ist, erstellt Claude thinking-Inhaltsblöcke, in denen es seine internen Überlegungen 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",
    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:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Manuelles erweitertes Denken (thinking: {"type": "enabled", "budget_tokens": N}) ist der veraltete Mechanismus. Es funktioniert nur auf Claude-4- bis 4.6-Modellen, die Denken unterstützen; Claude 4.7 und neuere Modelle lehnen type: enabled mit einem 400-Fehler ab und verwenden stattdessen adaptives Denken. Beim manuellen erweiterten Denken 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 Denk-Token, nicht für die zusammengefasste Ausgabe. Sofern du nicht verschachteltes Denken verwendest, muss budget_tokens kleiner als max_tokens sein, damit Claude nach Abschluss des Denkens Platz hat, seine Antwort zu schreiben.

Denken mit Tool-Nutzung

Denken kann zusammen mit „tool use“ (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: Unterstützt nur tool_choice: {"type": "auto"} (Standard) oder tool_choice: {"type": "none"}.
2. Beibehalten von Thinking-Blöcken: Während der Tool-Nutzung musst du thinking-Blöcke für die letzte Assistant-Nachricht an die API zurückgeben.

Beibehalten von Thinking-Blöcken

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 Thinking und Tool-Anfrage
response = client.messages.create(
    model="claude-opus-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 einbeziehen
continuation = client.messages.create(
    model="claude-opus-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 Denken

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

Auf älteren Modellen, die manuelles erweitertes Denken verwenden (Claude-4-, 4.5- und Sonnet-4.6-Modelle), aktivierst du verschachteltes Denken, 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:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool call: {block.name}({block.input})")
    elif block.type == "text":
        print(f"Response: {block.text}")

Mit verschachteltem Denken und NUR mit verschachteltem Denken (nicht mit regulärem manuellem erweitertem Denken) 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

Angeben von Client-Tools

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

{
  "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 formatsensiblen Eingaben kannst du über das Feld input_examples (Beta) konkrete Beispiele bereitstellen. Dies hilft Claude, erwartete Eingabemuster zu verstehen. Siehe Bereitstellen von Beispielen zur Tool-Nutzung für Details.

Beispiel einer guten 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"]
  }
}

Steuern von Claudes Ausgabe

Erzwingen der Tool-Nutzung

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 es eines der bereitgestellten Tools aufruft 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.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 macht, 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 du möchtest, dass das Modell JSON-Ausgaben zurückgibt, die einem bereitgestellten Schema folgen.

Gedankenkette

Bei der Verwendung von Tools zeigt Claude oft seine „chain of thought“ (Gedankenkette), also die schrittweise Argumentation, mit der es das Problem zerlegt und bestimmt, welche Tools verwendet werden sollen.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

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.

Wenn du eine Tool-Use-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 den Stop-Grund pause_turn 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 Verwendung eines Tools ungültig ist (zum Beispiel fehlende erforderliche Parameter), versuche die Anfrage erneut mit detaillierteren description-Werten in deinen Tool-Definitionen.

Streaming von Nachrichten

Beim Erstellen einer Nachricht kannst du "stream": true setzen, um die Antwort mithilfe von „server-sent events“ (vom Server gesendete Ereignisse), oder SSE, inkrementell 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",
) 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 Top-Level-Änderungen 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 Denken mit Streaming:

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

Beispiel einer grundlegenden Streaming-Anfrage

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-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"}