Anthropic Messages API Dokumentation: Endpunkte, Anfragen, Vision und Agent-Backends

Die Anthropic Messages API ist die wichtigste HTTP-Schnittstelle zum Senden von Prompts an Claude. Der zentrale Endpunkt ist POST /v1/messages: Sie geben ein Modell, eine Liste von typisierten Nachrichten-Inhaltsblöcken und ein Token-Limit an und erhalten eine Assistenten-Nachricht mit einem oder mehreren Ausgabeblöcken.

Dieser Leitfaden verwandelt die Anthropic API-Dokumentation in eine Implementierungs-Checkliste. Er behandelt den Anfragevertrag, den Multi-Turn-Zustand, Streaming, Vision, die Files API, die Tool-Nutzung und die Entscheidungen, die anfallen, wenn ein Agent-Backend sowohl Anthropic-native als auch OpenAI-kompatible Modellanbieter unterstützen muss.

Messages API Endpunkt und erforderliche Header

Die native Messages API von Anthropic verwendet diesen Endpunkt:

POST https://api.anthropic.com/v1/messages

Direkte HTTP-Anfragen enthalten normalerweise diese Header:

Header	Zweck
x-api-key	Authentifiziert das Anthropic-Konto
anthropic-version	Wählt den dokumentierten API-Versionsvertrag aus
content-type: application/json	Deklariert einen JSON-Anfragekörper

Der API-Versions-Header ist keine Modellversion. Er steuert das Verhalten der HTTP-API, während das Feld model das für die Inferenz verwendete Claude-Modell auswählt. Bewahren Sie beide Werte in der Konfiguration auf, anstatt sie im Anwendungscode zu verstreuen.

Die Anfrage- und Antwortstruktur

Eine einfache Anfrage enthält drei Felder:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Explain idempotency keys in two paragraphs."
    }
  ]
}

Die Antwort ist eine Assistenten-Nachricht und kein bloßer String. Ihre content-Eigenschaft ist ein Array von typisierten Blöcken, daher sollte Produktionscode den type jedes Blocks überprüfen, bevor er seine Felder liest.

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "An idempotency key..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 126
  }
}

Dieses blockbasierte Design wird wichtig, sobald Sie Bilder oder Tools hinzufügen. Ein einzelner Assistenten-Durchlauf kann Text und eine Tool-Anfrage enthalten, und ein Benutzer-Durchlauf kann Text zusammen mit Bild- oder Dokumentblöcken enthalten.

Eine minimale curl-Anfrage

Speichern Sie Anmeldeinformationen in einer Umgebungsvariable und verwenden Sie eine Modell-ID, die derzeit für Ihr Anthropic-Konto verfügbar ist:

export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "Return three practical ways to reduce API latency."
      }
    ]
  }'

Härten Sie keinen Modellnamen ein, der aus einem alten Tutorial kopiert wurde. Modellverfügbarkeit und -Aliase können sich ändern. Daher sollte die Bereitstellungskonfiguration eine Modell-ID verwenden, die in der aktuellen Modelldokumentation oder -konsole des Anbieters verifiziert wurde.

Python-Nutzung mit dem Anthropic SDK

Das offizielle Python SDK übernimmt die Authentifizierungs-Header und wandelt die Antwort in typisierte Objekte um:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "Write a Python function that validates a UUID string.",
        }
    ],
)

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

Das Iterieren über Inhaltsblöcke ist sicherer, als anzunehmen, dass message.content[0] immer Text ist. Agent-Anwendungen können Tool-Use-Blöcke erhalten, und multimodale Funktionen können der Konversation andere Blocktypen hinzufügen.

Multi-Turn-Konversationen und System-Prompts

Die Messages API ist zustandslos. Ihre Anwendung sendet den relevanten Konversationsverlauf bei jeder Anfrage erneut mit:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 512,
  "system": "You are a concise API documentation assistant.",
  "messages": [
    {"role": "user", "content": "What does HTTP 429 mean?"},
    {"role": "assistant", "content": "It indicates rate limiting."},
    {"role": "user", "content": "How should my client retry?"}
  ]
}

Anthropic platziert die Systemanweisung im obersten Feld system und nicht in einer Nachricht mit role: "system". Das ist einer der wichtigen Unterschiede, die bei der Übersetzung von Anfragen aus OpenAI-kompatiblen Schemata zu berücksichtigen sind.

Senden Sie bei langlebigen Sitzungen kein unbegrenztes Transkript. Behalten Sie die letzten Durchläufe, bewahren Sie Entscheidungen und Tool-Ergebnisse, die die Aufgabe noch beeinflussen, und fassen Sie älteren Kontext zusammen, bevor der Prompt sich dem Kontextlimit des ausgewählten Modells nähert.

Streaming-Antworten

Setzen Sie stream: true, wenn die Oberfläche die Ausgabe inkrementell anzeigen soll:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with client.messages.stream(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain database connection pooling."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Streaming verbessert die wahrgenommene Latenz, erhöht aber den Aufwand für die Zustandsverwaltung. Ihre Anwendung muss eine Verbindung, die frühzeitig geschlossen wird, partiellen Text, Ereignisreihenfolge und abschließende Nutzungsmetadaten verarbeiten. Bei Tool-verwendenden Agenten puffern Sie den vollständigen Tool-Eingabeblock, bevor Sie ihn parsen oder ausführen.

Claude Vision API Anfragen

Die Claude Vision API verwendet denselben Messages-Endpunkt. Fügen Sie einen Bild-Inhaltsblock vor der zugehörigen Textfrage hinzu. Bilder können als unterstützte base64-Daten oder über einen erlaubten Quelltyp bereitgestellt werden, der in der aktuellen Vision-Dokumentation beschrieben ist.

import base64
import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with open("architecture.png", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode("utf-8")

message = client.messages.create(
    model=os.environ["ANTHROPIC_VISION_MODEL"],
    max_tokens=700,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Identify two reliability risks in this architecture diagram.",
                },
            ],
        }
    ],
)

Verkleinern Sie überdimensionierte Bilder, bevor Sie sie senden. Große Bilder erhöhen die Übertragungszeit und den Token-Verbrauch, ohne unbedingt die Antwort zu verbessern. Validieren Sie auch den MIME-Typ; die Deklaration von JPEG-Daten als PNG ist eine häufige Ursache für abgelehnte Anfragen.

Nutzung der Anthropic Files API

Die Anthropic Files API ist nützlich, wenn eine Datei einmal hochgeladen und von späteren Messages API-Aufrufen referenziert werden soll, anstatt sie wiederholt zu kodieren und zu übertragen. Die genaue Verfügbarkeit, unterstützte Dateitypen und Anfragefelder können je nach Feature-Status variieren. Überprüfen Sie daher die aktuelle Files API-Dokumentation, bevor Sie sich in der Produktion darauf verlassen.

Eine typische Integration hat zwei Phasen:

1. Laden Sie die Datei hoch und speichern Sie die zurückgegebene Dateikennung zusammen mit dem Dokumentdatensatz Ihrer Anwendung.
2. Referenzieren Sie diese Kennung in einem unterstützten Inhaltsblock, wenn Sie eine Nachricht erstellen.

Behandeln Sie Datei-IDs als anbieterspezifische Ressourcen. Notieren Sie, welcher Anbieter und welches Konto jede ID erstellt hat, wenden Sie Ihre eigenen Zugriffskontrollen an und definieren Sie eine Löschrichtlinie. Eine Dateikennung sollte nicht direkt von einem nicht vertrauenswürdigen Benutzer ohne Autorisierungsprüfungen akzeptiert werden.

Für gelegentliche kleine Bilder ist base64 unkompliziert. Für Dokumente, die in vielen Anfragen verwendet werden, kann eine Anbieter-Dateiressource wiederholte Uploads reduzieren. Wenn Ihre Anwendung mit mehreren Anbietern arbeiten muss, behalten Sie das Originalobjekt in Ihrem eigenen Speicher und erstellen Sie anbieterspezifische Datei-IDs als Cache.

Tool-Nutzung für Agent-Backends

Tools ermöglichen es Claude, eine anwendungsdefinierte Funktion anzufordern. Ihr Backend beschreibt jedes Tool mit einem Namen, einem Zweck und einem JSON-Schema-Eingabevertrag. Das Modell kann dann einen tool_use-Block zurückgeben, anstatt vorzutäuschen, es hätte die Operation ausgeführt.

{
  "name": "get_order_status",
  "description": "Look up the current status of a customer order.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order identifier shown to the customer."
      }
    },
    "required": ["order_id"]
  }
}

Die sichere Ausführungsschleife ist:

1. Senden Sie Nachrichten und Tool-Definitionen an das Modell.
2. Erkennen Sie einen tool_use-Inhaltsblock.
3. Validieren Sie seine Eingabe gegen das Schema und Ihre Autorisierungsregeln.
4. Führen Sie das Tool in einer kontrollierten Umgebung aus.
5. Geben Sie einen passenden tool_result-Block im nächsten Benutzer-Durchlauf zurück.
6. Fahren Sie fort, bis das Modell eine normale Antwort produziert oder Ihr Schleifenlimit erreicht ist.

Führen Sie Tool-Argumente niemals als vertrauenswürdige Shell-, SQL- oder Dateipfade aus. Führen Sie bei Code-Agenten generierte Befehle in einer isolierten Umgebung wie Novita Agent Sandbox mit expliziten Zeit-, Netzwerk-, Dateisystem- und Ressourcenlimits aus.

Anthropic-native vs. OpenAI-kompatible Anfragen

Anthropic-native und OpenAI-kompatible APIs lösen das gleiche allgemeine Problem, aber ihre Drahtformate sind nicht identisch.

Aspekt	Anthropic Messages API	OpenAI-kompatible Chat-API
Gemeinsamer Endpunkt	/v1/messages	/v1/chat/completions
Systemanweisung	Oberstes Feld system	Üblicherweise eine system- oder developer-Nachricht
Ausgabedarstellung	Typisierte Inhaltsblöcke	Üblicherweise choices[].message
Tool-Anfrage	tool_use-Block	Üblicherweise tool_calls
Tool-Ergebnis	tool_result-Inhaltsblock	Üblicherweise eine Nachricht mit der Rolle tool

Ein OpenAI-kompatibler Endpunkt ist wertvoll, wenn Ihre Anwendung bereits das OpenAI SDK verwendet oder zwischen Open-Source-Modellen mit minimalen Transportänderungen wechseln muss. Novita AI stellt eine OpenAI-kompatible LLM-API bereit, sodass dieselbe Client-Struktur mehrere verfügbare Modelle ansprechen kann, indem die Basis-URL und die Modellkonfiguration geändert werden.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/v3/openai",
)

response = client.chat.completions.create(
    model=os.environ["NOVITA_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Review this retry strategy for failure modes.",
        }
    ],
)

print(response.choices[0].message.content)

Dies ist keine direkte Übersetzung jedes Anthropic-Features. Wenn Ihre Anwendung von Anthropic-spezifischen Inhaltsblöcken, Tool-Semantiken, Zitaten oder Beta-Funktionen abhängt, behalten Sie einen Anthropic-native Adapter. Verwenden Sie den gemeinsamen OpenAI-kompatiblen Pfad für Workloads, die in das gemeinsame Anfragemodell passen.

Aufbau eines anbieterneutralen Agent-Backends

Ein anbieterneutrales Backend sollte Anwendungskonzepte normalisieren, ohne vorzutäuschen, dass alle Anbieter identisch sind. Ein praktisches Design hat vier Schichten:

1. Konversationsmodell: Speichern Sie Rollen, Text, Bilder, Tool-Aufrufe und Tool-Ergebnisse in einem internen Schema.
2. Anbieter-Adapter: Übersetzen Sie das interne Schema in Anthropic Messages- oder OpenAI-kompatible Nutzlasten.
3. Fähigkeitsregister: Verfolgen Sie, ob das ausgewählte Modell Vision, Tools, strukturierte Ausgabe oder andere erforderliche Verhaltensweisen unterstützt.
4. Ausführungsschicht: Führen Sie Tools und Code getrennt vom Inferenzanbieter aus.

Diese Trennung ermöglicht es einem Team, Claude dort zu verwenden, wo Anthropic-natives Verhalten wichtig ist, während kompatible Workloads über Novita AI an ein Open-Source-Modell weitergeleitet werden. Der Open-Source-Pfad kann nützlich sein für Kostenkontrolle, Modellexperimente, Datenstandortanforderungen oder die Vermeidung einer Abhängigkeit von einem einzigen Anbieter. Testen Sie die Ausgabequalität und Tool-Zuverlässigkeit an Ihren eigenen Aufgaben, anstatt anzunehmen, dass zwei Modelle austauschbar sind, weil beide Chat-Nachrichten akzeptieren.

Bei Agent-Workloads verdient die Ausführungsschicht gleiche Aufmerksamkeit. Der Modellwechsel schützt Ihre Infrastruktur nicht vor unsicheren Befehlen. Verwenden Sie eine isolierte Sandbox, erzwingen Sie Tool-Whitelists, begrenzen Sie Iterationen und protokollieren Sie jede Modellentscheidung und jedes Tool-Ergebnis ohne Geheimnisse.

Häufige Fehler und Fehlersuche

400 Bad Request

Überprüfen Sie die JSON-Form, die Typen der Inhaltsblöcke, die erforderlichen Felder und ob das ausgewählte Modell die angeforderte Funktion unterstützt. Protokollieren Sie die Anforderungs-ID des Anbieters und den strukturierten Fehlertext, aber schwärzen Sie Anmeldeinformationen und base64-Dateidaten.

401 Authentifizierungsfehler

Stellen Sie sicher, dass der API-Schlüssel in der Laufzeitumgebung vorhanden ist und zum vorgesehenen Anbieter gehört. Anthropic verwendet x-api-key für direkte HTTP-Anfragen; ein OpenAI-kompatibler Client sendet normalerweise automatisch ein Bearer-Token.

404 Modell oder Ressource nicht gefunden

Überprüfen Sie die Modell-ID anhand der aktuellen Anbieterdokumentation oder -konsole. Stellen Sie bei Files API-Ressourcen auch sicher, dass die Datei zum selben Konto und zur selben Umgebung gehört, die von der Anfrage verwendet werden.

429 Rate Limit

Wiederholen Sie den Vorgang mit exponentiellem Backoff und Jitter, aber begrenzen Sie die Anzahl der Versuche. Stellen Sie Hintergrundarbeiten in die Warteschlange, begrenzen Sie die Parallelität pro Anbieter und vermeiden Sie es, jede fehlgeschlagene Anfrage sofort im gleichen Intervall zu wiederholen.

Kontext- oder Token-Limit-Fehler

Reduzieren Sie den Konversationsverlauf, die Bildgröße, den Dateiinhalt oder die angeforderte Ausgabelänge. Zählen Sie die gesamte Anfrage, einschließlich Systemanweisungen, Tool-Schemata, früherer Tool-Ergebnisse und multimodaler Inhalte.

Empfohlene Artikel

• What Are Coding Agents? Architecture, Tools, and Execution Loops
• What Is MCP? A Developer’s Guide to Model Context Protocol
• Open-Source LLM Guide 2026: Models, Tradeoffs, and Deployment

Implementierungs-Checkliste

• Bewahren Sie API-Schlüssel, Modell-IDs, Basis-URLs und API-Versionen in der Laufzeitkonfiguration auf.
• Parsen Sie typisierte Inhaltsblöcke anstatt einen einzelnen Textstring anzunehmen.
• Speichern Sie genügend Konversationszustand, um jede zustandslose Anfrage zu rekonstruieren.
• Validieren Sie Tool-Eingaben und führen Sie sie außerhalb des Modellprozesses aus.
• Fügen Sie Timeouts, Wiederholungslimits, Anforderungs-IDs und geschwärzte Beobachtbarkeit hinzu.
• Steuern Sie die Anbieterweiterleitung nach Modellfähigkeit, nicht nur nach Preis oder Name.
• Überprüfen Sie vor der Bereitstellung erneut Modell-IDs, Feature-Status, Limits und Preise.

Die Messages API ist auf der HTTP-Ebene unkompliziert. Die schwierigere Ingenieursarbeit tritt auf, wenn eine Anwendung Streaming, multimodale Eingabe, Tools, persistente Dateien oder mehrere Modellanbieter hinzufügt. Halten Sie diese Belange hinter expliziten Adaptern, und Ihr Agent-Backend kann sich weiterentwickeln, ohne die Geschäftslogik an ein Anfrageformat zu binden.

FAQ

Was ist der Endpunkt der Anthropic Messages API?

Der native Endpunkt ist POST https://api.anthropic.com/v1/messages. Anfragen erfordern Authentifizierung, einen Anthropic API-Versions-Header, eine Modell-ID, ein Token-Limit und ein Nachrichten-Array.

Ist die Anthropic Messages API OpenAI-kompatibel?

Nein. Die Konzepte überschneiden sich, aber System-Prompts, Inhaltsblöcke, Antwortobjekte und Tool-Use-Nachrichten unterscheiden sich. Verwenden Sie einen Anbieter-Adapter, wenn eine Anwendung beide Formate unterstützen muss.

Verwendet die Claude Vision API einen separaten Endpunkt?

Nein. Vision-Anfragen verwenden die Messages API mit Bild- und Text-Inhaltsblöcken. Das ausgewählte Claude-Modell muss Bildeingabe unterstützen.

Wann sollte ich die Anthropic Files API verwenden?

Verwenden Sie sie, wenn unterstützte Dateien über mehrere Anfragen hinweg referenziert werden müssen und wiederholte base64-Uploads verschwenderisch wären. Behalten Sie Ihre eigene Quelldatei und Autorisierungsaufzeichnung, da Anbieter-Datei-IDs kontospezifische Ressourcen sind.

Kann Claude Code ein benutzerdefiniertes API-Backend verwenden?

Die Claude Code-Integration hängt von der Authentifizierung und Anbieterkonfiguration ab, die von der aktuellen Claude Code-Version unterstützt wird. Gehen Sie nicht davon aus, dass ein OpenAI-kompatibler Endpunkt die Anthropic Messages API implementiert. Für einen benutzerdefinierten Agenten ist ein anbieterneutraler Adapter in der Regel klarer, als zu versuchen, verschiedene Protokolle identisch erscheinen zu lassen.

Wann sollte ich ein Open-Source-Modell über Novita AI wählen?

Ziehen Sie es in Betracht, wenn Sie OpenAI-kompatiblen Modellwechsel, Open-Model-Experimente oder einen zweiten Anbieter für kompatible Workloads wünschen. Behalten Sie Anthropic-native Anfragen für Funktionen bei, die Claude-spezifisches API-Verhalten erfordern, und evaluieren Sie beide Pfade mit Ihren eigenen Prompts und Tools.