Beantragung und Nutzung der Claude Messages API

Anthropic Claude ist ein sehr leistungsstarkes KI-Dialogsystem, das durch die Eingabe eines Prompts in nur wenigen Sekunden flüssige und natürliche Antworten erzeugen kann. Die Claude Messages API ist das offizielle native API-Format von Anthropic. Anders als das mit OpenAI kompatible Format (Chat Completion) verwendet sie die eigene Anfrage- und Antwortstruktur von Anthropic und kann die einzigartigen Fähigkeiten von Claude besser nutzen, wie multimodale Inhaltseingaben, Tool-Aufrufe, Deep Thinking (Extended Thinking) und andere erweiterte Funktionen. Dieses Dokument stellt hauptsächlich den Nutzungsablauf der Claude Messages API vor. Damit können wir die Dialogfunktionen von Claude über eine native Schnittstelle aufrufen, die mit der offiziellen Schnittstelle von Anthropic übereinstimmt.

Beantragungsprozess

Um die Claude Messages API zu verwenden, rufen Sie zunächst die Ace Data Cloud-Konsole auf, um Ihren API-Token zu erhalten, und bewahren Sie ihn als Reserve auf.

Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Danach kehren Sie automatisch zu dieser Seite zurück. Ein API-Token kann alle Dienste der Plattform aufrufen, ohne dass jeder Dienst einzeln beantragt werden muss. Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben, das kostenlos ausprobiert werden kann; bei unzureichendem Guthaben können Sie in der Konsole ein allgemeines Guthaben aufladen.

📘 Vollständige Dokumentation: Claude Messages API →

Grundlegende Nutzung

Der Anfragepfad der Claude Messages API lautet /v1/messages und entspricht der offiziellen API von Anthropic. Wir müssen mindestens drei Pflichtparameter bereitstellen:

model: Wählt das zu verwendende Claude-Modell aus. claude-opus-5-5 wird nur über die Messages API bereitgestellt, unterstützt 1 Million Token Kontext, maximal 128K Ausgabe-Token und aktiviert stets adaptives Denken. Das neueste Flaggschiff ist claude-fable-5-1 (1 Million Token Kontext, maximal 128K Ausgabe-Token); das ursprüngliche claude-fable-5 bleibt weiterhin kompatibel verfügbar. claude-sonnet-5-5 wurde zur nativen Messages-Schnittstellenserie hinzugefügt und unterstützt Bildeingaben sowie adaptives Denken; die offiziellen Referenzpreise für Eingabe, Ausgabe und Cache-Lesen betragen jeweils 2, 10 und 0,20 US-Dollar pro Million Token.
messages: Das Array der eingegebenen Nachrichten. Jede Nachricht enthält role (Rolle) und content (Inhalt), wobei role user und assistant unterstützt.
max_tokens: Die maximale Anzahl an Ausgabe-Token, um die Länge einer einzelnen Antwort zu begrenzen.

Häufig verwendete optionale Parameter:

system: System-Prompt, der verwendet wird, um das Verhalten und die Rolle des Modells festzulegen.
temperature: Zufälligkeit der Generierung, zwischen 0 und 1; je größer der Wert, desto stärker streuen die Antworten.
stream: Ob eine Streaming-Antwort verwendet wird; bei Einstellung auf true kann eine zeichenweise Rückgabe erzielt werden.
stop_sequences: Benutzerdefinierte Stoppsequenzen; das Modell beendet die Generierung, wenn es auf diese Texte trifft.
top_p: Kern-Sampling-Parameter, der zusammen mit temperature die Zufälligkeit der Generierung steuert.
top_k: Sampling erfolgt nur aus den K Optionen mit der höchsten Wahrscheinlichkeit.
tools: Tool-Definitionen, die dem Modell ermöglichen, externe Funktionen aufzurufen.
tool_choice: Steuert, wie das Modell die bereitgestellten Tools verwendet.
cache_control: Erstellt automatisch einen Cache-Haltepunkt beim letzten zwischenspeicherbaren Inhaltsblock der Anfrage; kann auch in einem konkreten Inhaltsblock geschrieben werden.

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-fable-5-1",
    "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-fable-5-1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

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

Nach dem Aufruf lautet das Rückgabeergebnis wie folgt:

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Erläuterung der Felder des Rückgabeergebnisses:

id: Eindeutige Kennung dieser Nachricht.
type: Immer message.
role: Immer assistant.
content: Array mit Antwortinhalten, wobei jedes Element type (wie text) und den entsprechenden Inhalt enthält.
model: Name des Modells, das die Anfrage verarbeitet.
stop_reason: Grund für das Beenden. Stabile Werte umfassen end_turn, max_tokens, stop_sequence, tool_use, pause_turn (der aktuelle assistant-Inhalt kann unverändert zurückgesendet werden, um fortzufahren), refusal und model_context_window_exceeded.
stop_sequence: Wenn aufgrund einer benutzerdefinierten Stoppsequenz angehalten wurde, wird der übereinstimmende Text der Stoppsequenz angezeigt.
stop_details: Wenn stop_reason refusal ist, kann dies die Ablehnungskategorie und eine Erläuterung enthalten.
usage: Token-Nutzungsstatistik. input_tokens sind nicht zwischengespeicherte Eingaben; cache_creation_input_tokens und cache_read_input_tokens stehen jeweils für Cache-Schreiben und -Lesen; output_tokens ist die Gesamtzahl aller Ausgabe-Token. Wenn output_tokens_details.thinking_tokens zurückgegeben wird, ist dieser Wert eine Teilmenge von output_tokens; bei der Berechnung der Gesamtmenge oder der Kosten darf er nicht erneut addiert werden. Wenn keine maßgebliche Zählung für diese Aufschlüsselung vorhanden ist, kann sie null sein oder ausgelassen werden.
usage.cache_creation: Optionale TTL-Details für Cache-Schreiben, einschließlich ephemeral_5m_input_tokens und ephemeral_1h_input_tokens. Wenn das Objekt vorhanden ist, entspricht die Summe beider Werte cache_creation_input_tokens; ein Feld mit null oder ein ausgelassenes Feld bedeutet, dass für die aktuelle Antwort keine verfügbare TTL-Aufschlüsselung besteht und nicht als 0 interpretiert werden darf.
usage.cost: Nicht-streamende Antworten können ein von Ace Data Cloud aufgezeichnetes Objekt zum Guthabenverbrauch enthalten, wobei amount der tatsächliche Verbrauch dieser Anfrage, currency die Maßeinheit und list_amount der Betrag vor Rabatt ist (falls vorhanden). Der offizielle Grundpreis für das Cache-Lesen von Fable 5.1 beträgt 0,25 $/Million Token, und die Grundpreise für 5-Minuten- und 1-Stunden-Cache-Schreiben betragen jeweils 12,50 und 20$ /Million Token; die tatsächlichen Plattformpreise werden entsprechend dem Tarifrabatt umgerechnet.

System-Prompt

Die Claude Messages API unterstützt das Festlegen eines System-Prompts ü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": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。",
    "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 Festlegen des system-Prompts können die Rolle und das Verhalten von Claude präzise gesteuert werden.

Streaming-Antworten

Diese Schnittstelle unterstützt auch Streaming-Antworten. Setzen Sie den Parameter stream auf true, um einen schrittweisen Rückgabe-Effekt zu erhalten, der sich hervorragend für die zeichenweise 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 Server-Sent-Events-(SSE)-Format zurückgegeben, wobei jede Zeile mit event: und data: beginnt. Zu den Streaming-Ereignistypen gehören:

message_start: Nachricht beginnt und enthält die grundlegenden Informationen der Nachricht sowie den Modellnamen.
content_block_start: Inhaltsblock beginnt.
content_block_delta: Inkrementelle Aktualisierung des Inhaltsblocks, die neu generierte Textfragmente enthält.
content_block_stop: Inhaltsblock endet.
message_delta: Inkrementelle Aktualisierung auf Nachrichtenebene, die stop_reason und die endgültigen usage-Informationen enthält. Der maßgebliche Wert von output_tokens_details.thinking_tokens sollte nur aus dem letzten message_delta.usage gelesen und nicht ereignisübergreifend summiert werden.
message_stop: Nachricht endet.

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

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! My name is"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. How can I help you today?"}}

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

Wie zu sehen ist, enthalten die content_block_delta-Ereignisse in der Streaming-Antwort den schrittweise generierten Textinhalt. Durch das Zusammenfügen 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: "Hello, 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 Dialogrunden

Wenn Sie die Funktion für mehrere Dialogrunden anbinden möchten, müssen Sie Nachrichten mit den Rollen user und assistant abwechselnd im messages-Array anordnen und den bisherigen Dialogverlauf gemeinsam ü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": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you. How can I help you today?"},
        {"role": "user", "content": "What is my name?"}
    ]
}

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

Das Rückgabeergebnis lautet wie folgt:

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Your name is Alice, as you just told me!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

Durch die Übergabe des vollständigen Dialogverlaufs in messages kann Claude unter Berücksichtigung des Kontexts präzise antworten.

Modell für tiefgehendes Denken

Claude’s Thinking und Thinking Summary sind zwei unterschiedliche Konzepte: Das Modell kann interne Schlussfolgerungen durchführen, aber die API gibt nicht die ursprüngliche Gedankenkette zurück. Wenn der Schlussfolgerungsprozess angezeigt werden soll, gibt die API eine verarbeitete Zusammenfassung zurück. Für aktuelle Modelle wird die Verwendung von Adaptive Thinking empfohlen, wobei der gesamte Schlussfolgerungsaufwand über output_config.effort gesteuert wird:

import requests

url = "https://api.acedata.cloud/v1/messages"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive",
        "display": "summarized"
    },
    "output_config": {
        "effort": "high"
    },
    "messages": [
        {"role": "user", "content": "What is the sine of 30 degrees?"}
    ]
}

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

Der Thinking-Block in der Antwort sieht wie folgt aus:

{
  "type": "thinking",
  "thinking": "The problem asks for a standard trigonometric value...",
  "signature": "opaque-signature"
}

display: "summarized" gibt eine lesbare Zusammenfassung der Überlegungen zurück; es ist nicht die ursprüngliche Gedankenkette.
display: "omitted" gibt thinking: "" zurück, behält jedoch die opaque signature zur Unterstützung nachfolgender Gespräche bei.
display: "updates" ist ein Beta-Modus von Anthropic und muss anthropic-beta: thinking-display-updates-2026-08-18 enthalten. Die offizielle Definition ist, den Textkörper der Überlegungen auszublenden und kurze Fortschrittsupdates zwischen Tool-Aufrufen anzuzeigen. Die Plattform leitet diesen Parameter und den Beta-Request-Header unverändert weiter und schreibt ihn nicht zwangsweise zu summarized um; der tatsächliche Ausgabeinhalt hängt von der Unterstützung des ausgewählten Modells ab.
thinking, output_config, effort, Sampling-Parameter und neu hinzugefügte Erweiterungsfelder werden unverändert weitergeleitet. Die Plattform verwaltet keine hartcodierten Werteaufzählungen oder Kombinationsbeschränkungen nach Modell und schreibt den thinking-Modus auch nicht automatisch um; ob diese Parameter akzeptiert werden, entscheidet das ausgewählte Modell, und vom Modell zurückgegebene Parameterfehler werden an den Client weitergeleitet.
Der Standardwert für display bei Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 und Opus 4.7 ist omitted; Opus 4.6, Sonnet 4.6 und frühere Modelle mit thinking-Unterstützung verwenden standardmäßig summarized.
Display beeinflusst nur den zurückgegebenen Inhalt und die Streaming-Latenz, deaktiviert die Überlegungen nicht und reduziert auch nicht die Abrechnung von thinking-Token.
Ob thinking standardmäßig aktiviert ist und welcher display-Standardwert gilt, sind zwei unabhängige Fragen. Opus 5 und Sonnet 5 aktivieren standardmäßig adaptive thinking; bei Opus 5 entspricht das Weglassen von thinking adaptive, und das Weglassen von output_config.effort entspricht high. Opus 4.8, 4.7 und 4.6 müssen explizit aktiviert werden.
Thinking und der endgültige Textkörper teilen sich das Ausgabebudget von max_tokens. Ist das Budget zu klein, kann thinking den Großteil des Budgets belegen, sodass der Textkörper leer bleibt oder abgeschnitten wird; erhöhen Sie bitte max_tokens, oder verwenden Sie low / medium effort, um den Aufwand für die Überlegungen zu steuern.
Für Modelle, bei denen thinking deaktiviert werden darf, kann thinking: {"type":"disabled"} übergeben werden. Neue Modi wie between_tools sowie effort-Kombinationen hängen vom ausgewählten Modell ab; die Plattform lehnt sie nicht vorab anhand alter Modellregeln ab.
Ein festes Überlegungsbudget kann über budget_tokens weitergegeben werden; neue Modelle verwenden normalerweise thinking.type=adaptive und output_config.effort. Ob ein festes Budget oder das Deaktivieren von thinking unterstützt wird, richtet sich nach den aktuellen Fähigkeiten des ausgewählten Modells.
Bei mehrstufigen Gesprächen und Tool-Aufrufen sollten der vollständige vom assistant zurückgegebene thinking-Block sowie die signature unverändert zurückgegeben werden; ändern oder generieren Sie die signature nicht selbst.
Die Parameterweiterleitung bedeutet nicht, dass jedes Modell alle Funktionen unterstützt. Protokollübergreifende Aufrufe müssen weiterhin konvertiert werden; der Unterstützungsumfang und Fehler von Inhalten wie redacted_thinking werden vom Modelldienst bestimmt, der die Anfrage tatsächlich verarbeitet.

In Streaming-Anfragen erzeugt summarized thinking_delta; omitted erzeugt kein thinking_delta und behält nur den Lebenszyklus des thinking-Blocks und signature_delta bei.

Visuelle Modelle

Claude unterstützt multimodale Eingaben und kann Text und Bilder gleichzeitig verarbeiten. In der Messages API können Sie visuelle Fähigkeiten verwenden, indem Sie content auf ein Array-Format setzen und Bildinhaltsblöcke übergeben.

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

# 读取并编码图片
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": "What's in this image?"
                }
            ]
        }
    ]
}

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

Verwendung von URL-Bildern

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": "What's in this image?"
                }
            ]
        }
    ]
}

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": "What'\''s in this image?"
          }
        ]
      }
    ]
  }'

Unterstützte Bildformate umfassen: image/jpeg, image/png, image/gif, image/webp.

Dokumente und PDF

PDF verwendet den document-Inhaltsblock und unterstützt zwei stabile Quellen: Base64 und URL. Die Base64-Quelle muss application/pdf verwenden:

import base64

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Quarterly report"
            },
            {"type": "text", "text": "Summarize this PDF."}
        ]
    }]
}

Die URL-Quelle wird als {"type":"url","url":"https://example.com/report.pdf"} geschrieben. document unterstützt außerdem text/plain sowie eine content-Quelle, die aus text/image-Blöcken besteht; optionale Felder umfassen title, context und citations. Die file_id-Quelle der Files API gehört zu einer eigenständigen Beta-Funktion und ist nicht Teil des stabilen Vertrags dieser Schnittstelle.

Prompt-Caching

Das übergeordnete cache_control setzt den Cache-Haltepunkt automatisch auf den letzten cachebaren Block:

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "You are an expert on this reference material.",
    "messages": [{"role": "user", "content": "Summarize the key points."}]
}

Wenn eine präzise Positionssteuerung erforderlich ist, kann derselbe cache_control auch auf text-, image-, document-, tool_use-, tool_result-Inhaltsblöcke oder Werkzeugdefinitionen geschrieben werden. ttl unterstützt 5m (Standard) und 1h; bitte verwenden Sie usage.cache_creation_input_tokens und usage.cache_read_input_tokens, um Cache-Schreibvorgänge und Cache-Treffer zu bestimmen. Wenn die Antwort usage.cache_creation bereitstellt, gilt ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens. Wenn cache_creation null ist oder weggelassen wird, bedeutet dies, dass nur die Gesamtmenge der Cache-Schreibvorgänge vorliegt und keine autoritative TTL-Aufschlüsselung vorhanden ist; behandeln Sie in diesem Fall keinen Bucket als bekanntermaßen 0, Abrechnung und Gesamtmenge richten sich weiterhin nach dem Aggregatfeld. Beispiel für ein Rückgabeergebnis:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an API request configuration interface for what appears to be an AI chat completion service. The interface includes parameters for model selection, messages, stream mode, and max tokens settings."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Werkzeugaufrufe (Tool Use)

Die Claude Messages API unterstützt nativ Werkzeugaufrufe und ermöglicht es dem Modell, bei Bedarf Ihre vordefinierten 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": "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"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
}

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

Wenn das Modell entscheidet, ein Werkzeug aufzurufen, enthält content im Rückgabeergebnis einen Inhaltsblock vom Typ tool_use:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me check the weather in San Francisco for you."
    },
    {
      "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 den Wert tool_use hat, was bedeutet, dass das Modell ein Werkzeug aufrufen muss. Nachdem Sie dieses Ergebnis erhalten haben, müssen Sie die Werkzeugfunktion ausführen und das Ergebnis in Form von tool_result an das Modell zurücksenden:

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "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"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Let me check the weather in San Francisco for you."},
                {"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": "Sunny, 72°F"
                }
            ]
        }
    ]
}

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

Das Modell generiert auf Grundlage des vom Werkzeug zurückgegebenen Ergebnisses die endgültige Antwort in natürlicher Sprache.

Unterschiede zur Chat Completion API

Ace Data Cloud bietet gleichzeitig zwei Claude-API-Formate an. Die wichtigsten Unterschiede zwischen beiden sind wie folgt: usage.input_tokens der Messages API steht nur für nicht zwischengespeicherte Eingaben, cache_read_input_tokens und cache_creation_input_tokens sind unabhängige Abrechnungs-Buckets; alle drei werden jeweils nach dem entsprechenden Preis berechnet.

Merkmal	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
Format	Anthropic-natives Format	OpenAI-kompatibles Format
System-Prompt	Eigenständiges `system`-Feld	Übergabe über `role: "system"` in `messages`
Antwortstruktur	`content`-Array (unterstützt mehrere Typen)	`choices`-Array (enthält `message`)
Streaming-Format	SSE-Ereignisse (mehrere Ereignistypen)	SSE-`data`-Zeilen
Tiefes Nachdenken	Natives `thinking` und `output_config.effort`	Standardstrategie des Modells und Kompatibilitätsparameter
Werkzeugaufrufe	Natives `tools` + `input_schema`	OpenAI-kompatibles `tools`-Format
Token-Statistiken	`output_tokens_details.thinking_tokens`	`completion_tokens_details.reasoning_tokens`

Wenn Ihr System bereits an eine API im OpenAI-Format angebunden ist, können Sie die Chat Completion API für einen nahtlosen Wechsel verwenden. Wenn Sie alle nativen Fähigkeiten von Claude nutzen müssen, wird empfohlen, die Messages API zu verwenden.

Fehlerbehandlung

Die Fehlerantworten der öffentlichen Schnittstelle verwenden das Ace Data Cloud Plattform-Envelope: error.code ist ein stabiler Fehlercode, error.message ist eine Beschreibung, und trace_id wird zur Untersuchung von Anfragen verwendet. Häufige HTTP-Statuswerte umfassen:

400: Anfrageparameter oder Protokollinhalt ungültig.
401: Autorisierungstoken ungültig, fehlt oder ist abgelaufen.
403: Zugriff verboten, unzureichendes Guthaben oder eingeschränktes Kontingent.
404: API oder Modell existiert nicht.
413: Anfragekörper zu groß.
429: Zu viele Anfragen.
500 / 503 / 504: Dienstfehler, vorübergehend nicht verfügbar oder Verarbeitungs-Timeout.

Beispiel für eine Fehlerantwort

{
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Diese Fehlerstruktur ist der Laufzeitvertrag von Ace Data Cloud und entspricht nicht dem offiziellen Fehler-Envelope von Anthropic; bitte behandeln Sie sie anhand des HTTP-Status und von error.code.

Fazit

Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Claude Messages API verwenden können, um Claudes Konversationsfunktionen im nativen Anthropic-Format aufzurufen. Die Messages API unterstützt umfangreiche Funktionen wie grundlegende Konversationen, System-Prompts, Streaming-Antworten, mehrteilige Konversationen, tiefes Denken, visuelles Verständnis, PDFs, Prompt-Caching und Tool-Aufrufe. Bei Fragen können Sie sich jederzeit an unser technisches Support-Team wenden.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

Beantragung und Nutzung der Claude Messages API

Beantragungsprozess

Grundlegende Nutzung

cURL-Beispiel

Python-Beispiel

System-Prompt

Python-Beispiel

Streaming-Antworten

Python-Beispiel

JavaScript-Beispiel

Mehrere Dialogrunden

Python-Beispiel

Modell für tiefgehendes Denken

Visuelle Modelle

Verwendung von Base64-kodierten Bildern

Verwendung von URL-Bildern

cURL-Beispiel

Dokumente und PDF

Prompt-Caching

Werkzeugaufrufe (Tool Use)

Python-Beispiel

Unterschiede zur Chat Completion API

Fehlerbehandlung

Beispiel für eine Fehlerantwort

Fazit

​Beantragungsprozess

​Grundlegende Nutzung

​cURL-Beispiel

​Python-Beispiel

​System-Prompt

​Python-Beispiel

​Streaming-Antworten

​Python-Beispiel

​JavaScript-Beispiel

​Mehrere Dialogrunden

​Python-Beispiel

​Modell für tiefgehendes Denken

​Visuelle Modelle

​Verwendung von Base64-kodierten Bildern

​Verwendung von URL-Bildern

​cURL-Beispiel

​Dokumente und PDF

​Prompt-Caching

​Werkzeugaufrufe (Tool Use)

​Python-Beispiel

​Unterschiede zur Chat Completion API

​Fehlerbehandlung

​Beispiel für eine Fehlerantwort

​Fazit

Beantragungsprozess

Grundlegende Nutzung

cURL-Beispiel

Python-Beispiel

System-Prompt

Python-Beispiel

Streaming-Antworten

Python-Beispiel

JavaScript-Beispiel

Mehrere Dialogrunden

Python-Beispiel

Modell für tiefgehendes Denken

Visuelle Modelle

Verwendung von Base64-kodierten Bildern

Verwendung von URL-Bildern

cURL-Beispiel

Dokumente und PDF

Prompt-Caching

Werkzeugaufrufe (Tool Use)

Python-Beispiel

Unterschiede zur Chat Completion API

Fehlerbehandlung

Beispiel für eine Fehlerantwort

Fazit