Verwendung der Messages API
Praktische Muster und Beispiele für die effektive Nutzung der Messages API
Anthropic bietet zwei Möglichkeiten, mit Claude zu entwickeln, die jeweils für unterschiedliche Anwendungsfälle geeignet sind:
| Messages API | Claude Managed Agents | |
|---|---|---|
| Was es ist | Direkter Zugriff auf das Prompting des Modells | Vorgefertigtes, konfigurierbares Agent-Harness, das in verwalteter Infrastruktur läuft |
| Am besten geeignet für | Benutzerdefinierte Agent-Schleifen und feingranulare Kontrolle | Lang laufende Aufgaben und asynchrone Arbeit |
Dieser Leitfaden behandelt gängige Muster für die Arbeit mit der Messages API, einschließlich einfacher Anfragen, Unterhaltungen mit mehreren Runden, Prefill-Techniken und Vision-Funktionen. Vollständige API-Spezifikationen findest du in der Messages API-ReferenzVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.. Für das verwaltete Agent-Harness siehe stattdessen die Übersicht zu Claude Managed Agents.
Einfache Anfrage und Antwort
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-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-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}Ablehnungsantworten (stop_reason: "refusal") enthalten bei jedem Modell außerdem ein stop_details-Objekt, das die Richtlinienkategorie angibt, die die Ablehnung ausgelöst hat. Die Feldreferenz und Beispielcode zur Behandlung findest du unter Wie eine Ablehnung aussieht.
Mehrere Gesprächsrunden
Die Messages API ist zustandslos, was bedeutet, dass du immer den vollständigen Gesprächsverlauf an die API sendest. Mit diesem Muster kannst du eine Unterhaltung schrittweise aufbauen. 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 Unterhaltung vorhalten, 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.
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){
"id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Sure, I'd be happy to provide..."
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 30,
"output_tokens": 309
}
}System-Rolle in Nachrichten
Um mitten in einer Unterhaltung eine neue Systemanweisung hinzuzufügen, füge direkt nach einer Benutzerrunde eine Nachricht mit "role": "system" ein. Diese Nachricht darf nicht der erste Eintrag in messages sein. Dies funktioniert auf Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5 und Claude Haiku 5.5. Siehe die vollständigen Platzierungsregeln.
Eine Systemnachricht mitten in der Unterhaltung hat dieselbe Autorität wie das Top-Level-Feld system, aber da sie an das Ende des Nachrichtenverlaufs angehängt wird, macht sie keinen zuvor gecachten Präfix ungültig. Verwende das Top-Level-Feld system für Anweisungen, die ab der allerersten Runde gelten sollen, und eine Systemnachricht mitten in der Unterhaltung für Anweisungen, die erst später relevant werden.
Den vollständigen Leitfaden, einschließlich der Kombination mit Prompt-Caching, findest du unter System-Nachrichten und Tool-Änderungen mitten im Gespräch.
Claudes Antwort vorausfüllen
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.
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){
"id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "C"
}
],
"model": "claude-sonnet-4-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 42,
"output_tokens": 1
}
}Vision
Claude kann in Anfragen sowohl Text als auch Bilder lesen. Du kannst Bilder über die Quelltypen base64, url oder file bereitstellen. Der Quelltyp file verweist auf ein Bild, das über die Files API hochgeladen wurde. Unterstützte Medientypen sind image/jpeg, image/png, image/gif und image/webp. Weitere Details findest du im Leitfaden zu Vision.
import base64
import httpx2
# Option 1: Base64-codiertes 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(message)
# 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(message_from_url){
"id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 1030,
"output_tokens": 350
}
}Nächste Schritte
Behandle jeden stop_reason-Wert und entscheide, was zu tun ist, wenn eine Antwort endet.
Gib Claude Tools, um externe Dienste und APIs aus der Messages API heraus aufzurufen.
Steuere Desktop-Computerumgebungen mit der Messages API.
Lass Claude in einem von dir betriebenen Browser navigieren, Webseiten lesen und mit ihnen interagieren.
Erhalte garantierte, schemavalidierte JSON-Ausgaben von Claude.
Lege mit output_config.task_budget ein empfehlendes Token-Budget für eine vollständige agentische Schleife fest.
Verfügbarkeit
Claude API
- Modelle
- Alle Modelle
Amazon Bedrock
- Modelle
- Alle Modelle
Amazon Bedrock (bedrock-runtime)
- Modelle
- Alle Modelle
Claude Platform on AWS
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Anthropic managed)
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Google managed)
- Modelle
- Alle Modelle
Microsoft Foundry
- Modelle
- Alle Modelle
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/messages
Ausgenommen: Abgedeckte Modelle
Standard-API-Aufrufe zum Generieren von Antworten von Claude.
War diese Seite hilfreich?