

API-Nutzungsleitfaden 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, erweitertem Denken und sonst nichts.



Modelle

Smartest model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 4.6: claude-sonnet-4-6
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001



Aufrufen der API



Grundlegende Anfrage und Antwort

import anthropic
import os

message = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
).messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)



Claude Worte in den Mund legen

Du kannst einen Teil von Claudes Antwort an der letzten Position der Eingabenachrichtenliste vorausfüllen. Dies kann verwendet werden, um Claudes Antwort zu formen. Das folgende Beispiel verwendet "max_tokens": 1, um eine einzelne Multiple-Choice-Antwort von Claude zu erhalten.

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. Sowohl base64- als auch url-Quelltypen werden für Bilder unterstützt, zusammen mit den Medientypen image/jpeg, image/png, image/gif und image/webp.

import anthropic
import base64
import httpx

# Option 1: Base64-kodiertes Bild
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    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(message.content[0].text)

# Option 2: Per URL referenziertes Bild
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url.content[0].text)



Erweitertes Denken

„Extended thinking" (erweitertes Denken) kann Claude manchmal bei sehr schwierigen Aufgaben helfen. Bei Modellen vor Claude Opus 4.7 muss die Temperatur auf 1 gesetzt werden, wenn erweitertes Denken aktiviert ist.

Erweitertes Denken wird in den folgenden Modellen unterstützt:

• Claude Opus 4.8 (claude-opus-4-8, nur adaptives Denken)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)



Wie erweitertes Denken funktioniert

Wenn erweitertes 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-4-8",
    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 Denkblöcke und Textblö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}")

Bei Verwendung von manuellem erweitertem Denken (type: enabled) bestimmt der Parameter budget_tokens die maximale Anzahl von Tokens, die Claude für seinen internen Denkprozess verwenden darf. Bei Claude 4 und späteren Modellen gilt dieses Limit für die vollständigen Denk-Tokens und nicht für die zusammengefasste Ausgabe. Größere Budgets können die Antwortqualität verbessern, indem sie eine gründlichere Analyse für komplexe Probleme ermöglichen. Sofern du nicht Interleaved Thinking verwendest, muss budget_tokens kleiner als max_tokens sein, damit Claude nach Abschluss des Denkens Platz hat, seine Antwort zu schreiben.



Erweitertes Denken mit Tool-Nutzung

Erweitertes Denken 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: 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 Denken und Tool-Anfrage
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Extrahiere Thinking-Block und Tool-Use-Block
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 – Füge Thinking-Block und Tool-Ergebnis hinzu
continuation = client.messages.create(
    model="claude-opus-4-8",
    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)



Interleaved Thinking

Erweitertes Denken mit Tool-Nutzung in Claude 4-Modellen unterstützt „interleaved thinking" (verschachteltes Denken), das es Claude ermöglicht, zwischen Tool-Aufrufen zu denken. Um dies bei Claude 4-, 4.5- und Sonnet 4.6-Modellen zu aktivieren, füge den Beta-Header interleaved-thinking-2025-05-14 zu deiner API-Anfrage hinzu.

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 Interleaved Thinking und NUR mit Interleaved Thinking (nicht mit regulärem 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



Client-Tools spezifizieren

Client-Tools werden im Top-Level-Parameter tools der API-Anfrage spezifiziert. 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 extrem detaillierte Beschreibungen bereit. Dies ist bei weitem der wichtigste Faktor für die Tool-Performance. 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 formatabhängigen Eingaben kannst du konkrete Beispiele über das Feld input_examples (Beta) bereitstellen. Dies hilft Claude, erwartete Eingabemuster zu verstehen. 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 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 irgendwelche Tools verwendet.



JSON-Ausgabe

Tools müssen nicht unbedingt Client-Funktionen sein. Du kannst Tools immer dann verwenden, wenn du möchtest, dass das Modell eine JSON-Ausgabe zurückgibt, die einem bereitgestellten Schema folgt.



Gedankenkette

Bei der Verwendung von Tools zeigt Claude oft seine „chain of thought" (Gedankenkette), also die schrittweise Argumentation, die es verwendet, um das Problem aufzuschlüsseln und zu entscheiden, 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 max_tokens-Stop-Reason

Wenn Claudes Antwort aufgrund des Erreichens des max_tokens-Limits während der Tool-Nutzung abgeschnitten wird, wiederhole die Anfrage mit einem höheren max_tokens-Wert.



Umgang mit dem pause_turn-Stop-Reason

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



Fehlerbehebung



Tool-Ausführungsfehler

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 Versuch, ein Tool zu verwenden, ungültig ist (z. B. 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 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-4-8",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)



Event-Typen

Jedes Server-Sent-Event enthält einen benannten Event-Typ und zugehörige JSON-Daten. Jeder Stream verwendet den folgenden Event-Ablauf:

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-Events und content_block_stop.
3. Ein oder mehrere message_delta-Events, die Änderungen auf oberster Ebene am finalen Message-Objekt anzeigen.
4. Ein abschließendes message_stop-Event.

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



Content-Block-Delta-Typen



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 Verwendung von erweitertem Denken 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-4-8", "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"}