Zum Hauptinhalt springen
Anthropic Claude ist ein sehr leistungsstarkes KI-Dialogsystem, das in der Lage ist, innerhalb von Sekunden flüssige und natürliche Antworten zu generieren, sobald ein Eingabewort eingegeben wird. Die Claude Messages API ist das offizielle native API-Format von Anthropic, das sich von dem kompatiblen Format von OpenAI (Chat Completion) unterscheidet. Es verwendet die eigene Anfrage- und Antwortstruktur von Anthropic, um die einzigartigen Fähigkeiten von Claude besser zu nutzen, wie multimodale Inhalteingabe, Werkzeugaufrufe, tiefes Denken (Extended Thinking) und andere fortgeschrittene Funktionen. Dieses Dokument beschreibt hauptsächlich den Ablauf der Nutzung der Claude Messages API. Damit können wir die Dialogfunktionen von Claude über die offizielle native Schnittstelle von Anthropic aufrufen.

Antragsprozess

Um die Claude Messages API zu nutzen, können Sie zunächst die Seite Claude Messages API besuchen und auf die Schaltfläche „Acquire“ klicken, um die erforderlichen Anmeldeinformationen zu erhalten: Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach der Anmeldung werden Sie automatisch zur aktuellen Seite zurückgeleitet. Bei der ersten Antragstellung gibt es ein kostenloses Kontingent, mit dem Sie die API kostenlos nutzen können.

Grundlegende Nutzung

Der Anfragepfad der Claude Messages API lautet /v1/messages und bleibt mit der offiziellen API von Anthropic konsistent. Wir müssen mindestens drei erforderliche Parameter bereitstellen:
  • model: Wählen Sie das zu verwendende Claude-Modell, wie claude-opus-4-20250514, claude-sonnet-4-20250514 usw.
  • messages: Eingabemeldungsarray, wobei jede Nachricht role (Rolle) und content (Inhalt) enthält, wobei role user und assistant unterstützt.
  • max_tokens: Maximale Anzahl von Tokens für die Ausgabe, um die Länge der einzelnen Antwort zu begrenzen.
Häufig verwendete optionale Parameter:
  • system: Systemaufforderung, um das Verhalten und die Rolle des Modells festzulegen.
  • temperature: Generierungsrandomisierung, zwischen 0-1, je höher der Wert, desto divergenter die Antwort.
  • stream: Ob die Streaming-Antwort verwendet werden soll, auf true gesetzt, um eine zeilenweise Rückgabe zu erreichen.
  • stop_sequences: Benutzerdefinierte Stoppsequenzen, bei denen das Modell die Generierung stoppt, wenn es auf diesen Text trifft.
  • top_p: Kernstichprobenparameter, der zusammen mit der Temperatur die Randomisierung der Generierung steuert.
  • top_k: Nur aus den K wahrscheinlichsten Optionen stichprobenartig auswählen.
  • tools: Werkzeugdefinition, um das Modell externe Funktionen aufrufen zu lassen.
  • tool_choice: Steuert, wie das Modell die bereitgestellten Werkzeuge verwendet.

cURL Beispiel

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Python Beispiel

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
Nach dem Aufruf sieht das Rückgabeergebnis wie folgt aus:
{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! Mein Name ist Claude. Wie kann ich Ihnen heute helfen?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}
Erläuterung der Rückgabeergebnisfelder:
  • id: Eindeutiger Identifikator für diese Nachricht.
  • type: Immer message.
  • role: Immer assistant.
  • content: Antwortinhaltsarray, wobei jedes Element type (z. B. text) und den entsprechenden Inhalt enthält.
  • model: Name des Modells, das die Anfrage bearbeitet.
  • stop_reason: Grund für das Stoppen, mögliche Werte sind end_turn (normal beendet), max_tokens (maximale Länge erreicht), stop_sequence (auf Stoppsequenz gestoßen), tool_use (Werkzeugaufruf).
  • stop_sequence: Wenn aufgrund einer benutzerdefinierten Stoppsequenz gestoppt wurde, wird der übereinstimmende Stoppsequenztext angezeigt.
  • usage: Token-Nutzungsstatistik, einschließlich input_tokens (Anzahl der Eingabe-Tokens) und output_tokens (Anzahl der Ausgabe-Tokens).

Systemaufforderungen

Die Claude Messages API unterstützt die Festlegung von Systemaufforderungen über das Feld system, um das Verhalten, die Rolle und den Kontext des Modells zu definieren.

Python Beispiel

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "Du bist ein professioneller chinesischer Übersetzungsassistent. Bitte übersetze die vom Benutzer eingegebene englische Sprache ins Chinesische.",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
Durch das Setzen der system-Aufforderung kann die Rolle und das Verhalten von Claude präzise gesteuert werden.

Streaming-Antwort

Diese Schnittstelle unterstützt auch Streaming-Antworten. Setzen Sie den Parameter stream auf true, um eine schrittweise Rückgabe zu erhalten, die sich hervorragend für die Implementierung einer zeilenweisen Anzeige auf Webseiten eignet.

Python Beispiel

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))
Streaming-Antworten werden im Format Server-Sent Events (SSE) zurückgegeben, wobei jede Zeile mit event: und data: beginnt. Die Streaming-Ereignistypen umfassen:
  • message_start: Beginn der Nachricht, enthält grundlegende Informationen zur Nachricht und den Modellnamen.
  • content_block_start: Beginn des Inhaltsblocks.
  • content_block_delta: Inkrementelle Aktualisierung des Inhaltsblocks, enthält neu generierte Textabschnitte.
  • content_block_stop: Ende des Inhaltsblocks.
  • message_delta: Inkrementelle Aktualisierung auf Nachrichtenebene, enthält stop_reason und endgültige usage-Informationen.
  • message_stop: Ende der Nachricht.
Die Ausgabe sieht wie folgt aus:
event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

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":"Hallo"}}

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

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. Wie kann ich Ihnen heute helfen?"}}

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"}
Sie können sehen, dass das Streaming-Antwortereignis content_block_delta die schrittweise generierten Textinhalte enthält, und durch das Verketten aller text_delta kann die vollständige Antwort erhalten werden.

JavaScript Beispiel

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Hallo, Claude" }],
  }),
};

const response = await fetch("https://api.acedata.cloud/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Mehrere Runden im Dialog

Wenn Sie die Funktion für mehrere Runden im Dialog integrieren möchten, müssen Sie die Nachrichten der Rollen user und assistant im messages-Array abwechselnd anordnen und die vorherige Gesprächshistorie mit übergeben.

Python Beispiel

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hallo, mein Name ist Alice."},
        {"role": "assistant", "content": "Hallo Alice! Schön, Sie kennenzulernen. Wie kann ich Ihnen heute helfen?"},
        {"role": "user", "content": "Wie heiße ich?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
Das Rückgabeergebnis sieht wie folgt aus:
{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ihr Name ist Alice, wie Sie mir gerade gesagt haben!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}
Durch das Übermitteln der vollständigen Gesprächshistorie in messages kann Claude den Kontext für präzise Antworten nutzen.

Tiefes Denkmodell

Claude unterstützt die Funktion des Extended Thinking (tiefes Denken), die es dem Modell ermöglicht, vor der Antwort interne Überlegungen anzustellen, um die Genauigkeit bei der Bearbeitung komplexer Probleme zu erhöhen. Bei der Verwendung dieser Funktion muss der thinking-Parameter übergeben werden.

Python Beispiel

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "Was ist der Sinus von 30 Grad? Zeigen Sie Ihre Überlegungen."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
Das Rückgabeergebnis sieht wie folgt aus:
{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "Der Benutzer fragt nach dem Sinus von 30 Grad. Dies ist eine grundlegende Trigonometriefrage.\n\nIn einem 30-60-90-Dreieck sind die Seiten im Verhältnis 1:√3:2.\n\nFür einen 30°-Winkel:\n- Die gegenüberliegende Seite ist 1\n- Die Hypotenuse ist 2\n- Also sin(30°) = gegenüberliegend/Hypotenuse = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "Der Sinus von 30 Grad ist **1/2** oder **0.5**.\n\nDies ist einer der grundlegenden trigonometrischen Werte. In einem 30-60-90-Dreieck sind die Seiten im Verhältnis 1:√3:2, wobei die Seite gegenüber dem 30°-Winkel die Länge 1 hat und die Hypotenuse die Länge 2 hat, was uns sin(30°) = 1/2 gibt."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}
Es ist zu erkennen, dass das content-Array zwei Inhaltsblöcke enthält:
  • type: "thinking": Der interne Denkprozess des Modells, der die Überlegungsschritte zeigt.
  • type: "text": Das endgültige Antwortergebnis.
Hinweise:
  • Bei der Verwendung von thinking muss max_tokens größer als budget_tokens sein, da budget_tokens das Token-Budget für den Denkprozess ist.
  • Je größer budget_tokens, desto mehr Raum hat das Modell für tiefere Überlegungen, was sich für die Bearbeitung komplexer Probleme eignet.

Visuelles Modell

Claude unterstützt multimodale Eingaben und kann gleichzeitig Text und Bilder verarbeiten. In der Messages API kann die visuelle Fähigkeit genutzt werden, indem der content als Array-Format festgelegt und Bildinhaltsblöcke übergeben werden.

Verwendung von Base64-kodierten Bildern

import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# Bild lesen und kodieren
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "Was ist in diesem Bild?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Verwendung von Bild-URLs

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Was ist auf diesem Bild?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

cURL Beispiel

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "Was ist auf diesem Bild?"
          }
        ]
      }
    ]
  }'
Unterstützte Bildformate sind: image/jpeg, image/png, image/gif, image/webp. Beispiel für eine Rückgabe:
{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Dieses Bild zeigt eine API-Anforderungs-Konfigurationsoberfläche für einen KI-Chat-Vervollständigungsdienst. Die Oberfläche enthält Parameter für die Modellauswahl, Nachrichten, Stream-Modus und maximale Token-Einstellungen."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Werkzeugaufruf (Tool Use)

Die Claude Messages API unterstützt nativ die Funktion des Werkzeugaufrufs, die es dem Modell ermöglicht, bei Bedarf vordefinierte Werkzeuge/Funktionen aufzurufen.

Python Beispiel

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Holen Sie sich das aktuelle Wetter an einem bestimmten Ort",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Die Stadt und der Bundesstaat, z.B. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Wie ist das Wetter in San Francisco?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
Wenn das Modell beschließt, ein Werkzeug aufzurufen, wird der Rückgabewert im content einen Inhaltstyp tool_use enthalten:
{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Lass mich das Wetter in San Francisco für dich überprüfen."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}
Beachten Sie, dass stop_reason auf tool_use gesetzt ist, was bedeutet, dass das Modell ein Werkzeug aufrufen muss. Nach Erhalt dieses Ergebnisses müssen Sie die Werkzeugfunktion ausführen und das Ergebnis in Form von tool_result an das Modell zurückgeben:
payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Holen Sie sich das aktuelle Wetter an einem bestimmten Ort",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Die Stadt und der Bundesstaat, z.B. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Wie ist das Wetter in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Lass mich das Wetter in San Francisco für dich überprüfen."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Sonnig, 22°C"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
Das Modell wird basierend auf dem Ergebnis des Werkzeugs die endgültige natürliche Sprachantwort generieren.

Unterschied zur Chat Completion API

Ace Data Cloud bietet zwei Formate der Claude API an, die Hauptunterschiede sind wie folgt:
MerkmalMessages API (/v1/messages)Chat Completion API (/v1/chat/completions)
FormatAnthropic natives FormatOpenAI kompatibles Format
System-PromptUnabhängiges system FeldÜber messages mit role: "system" übergeben
Antwortstrukturcontent Array (unterstützt mehrere Typen)choices Array (enthält message)
Streaming-FormatSSE-Ereignisse (mehrere Ereignistypen)SSE data Zeilen
Tiefes DenkenNatives thinking ParameterDurch spezielle Modellnamen ausgelöst (z.B. -thinking Nachsatz)
WerkzeugaufrufNatives tools + input_schemaOpenAI kompatibles functions Format
Token-Zählunginput_tokens / output_tokensprompt_tokens / completion_tokens
Wenn Ihr System bereits mit der OpenAI-Format API verbunden ist, können Sie die Chat Completion API verwenden, um nahtlos zu wechseln. Wenn Sie die gesamten nativen Fähigkeiten von Claude nutzen möchten, wird empfohlen, die Messages API zu verwenden.

Fehlerbehandlung

Bei der API-Anforderung, wenn ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die Informationen zurück. Zum Beispiel:
  • 400 token_mismatched: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 400 api_not_implemented: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 401 invalid_token: Unbefugt, ungültiger oder fehlender Autorisierungstoken.
  • 429 too_many_requests: Zu viele Anfragen, Sie haben das Rate-Limit überschritten.
  • 500 api_error: Interner Serverfehler, etwas ist auf dem Server schiefgelaufen.

Beispiel für eine Fehlerantwort

{
  "error": {
    "code": "400",
    "message": "Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter."
  }
}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Abruf fehlgeschlagen"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Schlussfolgerung

Durch dieses Dokument haben Sie gelernt, wie Sie die Claude Messages API im nativen Format von Anthropic verwenden, um die Gesprächsfunktion von Claude aufzurufen. Die Messages API unterstützt eine Vielzahl von Funktionen wie grundlegende Gespräche, Systemaufforderungen, Streaming-Antworten, mehrstufige Gespräche, tiefes Denken, visuelles Verständnis und Toolaufrufe. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.