Text & Chat
Nachricht erstellen
Erstellt eine Nachricht unter Verwendung des Anthropic Messages API-Formats
Übersicht
Dieser Endpunkt akzeptiert das native Anthropic Messages-Format, sodass die Anthropic SDKs und darauf aufbauende Tools mit der TokenLab-Basis-URL funktionieren. Er funktioniert mit Modellen, deren accepted_request_formats den Wert anthropic_messages auflisten: Claude-Modelle und einige andere Modelle.
messages enthält user- und assistant-Turns. Platzieren Sie Systemanweisungen im system-Feld auf oberster Ebene. max_tokens ist erforderlich. Für Nachrichten im OpenAI-Stil mit Rollen wie system oder tool verwenden Sie Chat Completions.
Basis-URL für das Anthropic SDK: https://api.tokenlab.sh (kein /v1-Suffix)
Request-Header
Ihr TokenLab API-Key. Senden Sie entweder x-api-key oder Authorization: Bearer <API_KEY>. Wenn Sie beide mit unterschiedlichen Werten senden, verwendet TokenLab x-api-key.
Anthropic API-Version. Anthropic SDKs senden diese automatisch; verwenden Sie 2023-06-01, wenn Sie die API direkt aufrufen.
Namen von Anthropic-Beta-Funktionen, durch Kommas getrennt. TokenLab leitet den Header weiter; ob eine Beta-Funktion funktioniert, hängt vom Modell ab. Inhalte, die auf eine file_id verweisen, benötigen files-api-2025-04-14.
Request-Body
Unterstützte optionale Parameter, akzeptierte Werte und Standardwerte hängen vom ausgewählten Modell ab. Überprüfen Sie die Modelldetails, bevor Sie Sampling-, Reasoning- oder Tool-Optionen festlegen.
ID eines Modells, das das anthropic_messages-Format unterstützt. Überprüfen Sie die Modelldetails auf aktuelle Fähigkeiten.
Array von Nachrichtenobjekten mit role (user oder assistant) und content. Bis zu 100.000 Nachrichten.
content kann ein einfacher String oder ein Array von Inhaltsblöcken sein. Um Bilder zu senden, verwenden Sie strukturierte Inhaltsblöcke, anstatt Bild-URLs oder Base64-Strings direkt in den Klartext einzufügen. Andere native Blöcke wie tool_use, tool_result, thinking und document werden für Modelle akzeptiert, die diese unterstützen.
Beispiele für Inhaltsblöcke:
- Textblock:
{ "type": "text", "text": "Beschreibe dieses Bild" } - Bildblock via URL:
{ "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } } - Bildblock via Base64:
{ "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
Maximale Anzahl der zu generierenden Token. Erforderlich: TokenLab fügt keinen Standardwert hinzu. Das nutzbare Maximum hängt vom Modell ab; siehe max_output_tokens in den Modelldetails. Ein hoher Wert erhöht den Betrag, den TokenLab während der Anfrage von Ihrem Guthaben reserviert; ein Guthaben, das die Reservierung nicht decken kann, führt zu einem 402-Fehler.
System-Prompt als String oder Array von Text-Inhaltsblöcken, getrennt vom messages-Array.
Sampling-Temperatur. Unterstützung, zulässige Werte und Standardwerte hängen vom ausgewählten Modell ab; lassen Sie dieses Feld weg, um den Standardwert zu verwenden.
falseGibt die Antwort als Stream von Server-Sent Events zurück. Siehe Streaming.
Native Thinking-Konfiguration, zum Beispiel {"type":"enabled","budget_tokens":10000}. Unterstützte Modi, Budgets und Kombinationen mit anderen Parametern hängen vom ausgewählten Modell ab. Bei einem Modell, das ein manuelles Budget ablehnt, führt TokenLab {"type":"enabled"} als adaptives Thinking aus und ignoriert budget_tokens.
Verfügbare Tools für das Modell. Die Unterstützung hängt vom ausgewählten Modell ab.
Natives Tool-Choice-Objekt, zum Beispiel {"type":"auto"}. Unterstützte Typen hängen vom ausgewählten Modell ab.
Prompt-Caching-Marker, zum Beispiel {"type":"ephemeral"}; fügen Sie "ttl": "1h" für einen einstündigen Cache hinzu. Auf oberster Ebene aktiviert dies das automatische Caching. Sie können dies auch für system-Blöcke, tools und Inhaltsblöcke festlegen. Die Unterstützung hängt vom Modell ab; Modelle, die dies unterstützen, führen prompt-cache in ihren capabilities auf.
Nucleus-Sampling-Parameter. Verwenden Sie entweder temperature oder top_p, nicht beides. Die Unterstützung hängt vom ausgewählten Modell ab.
Sampling nur aus den Top-K-Optionen für jedes Token. Die Unterstützung hängt vom ausgewählten Modell ab.
Benutzerdefinierte Stopp-Sequenzen, die das Modell dazu veranlassen, die Generierung zu beenden. Bis zu 8.191 Einträge.
Request-Metadaten im Anthropic-Format. user_id ist ein undurchsichtiger Identifikator für Ihren Endbenutzer.
Nur auto und standard_only haben eine Wirkung. TokenLab berechnet nur den Standard-Tier und ignoriert jeden anderen Wert.
Antwort
Eindeutiger Nachrichten-Identifikator.
Immer message.
Immer assistant.
Array von Inhaltsblöcken, wie text, thinking oder tool_use.
Modell, das die Antwort generiert hat.
Grund für das Stoppen der Generierung, wie end_turn, max_tokens, stop_sequence oder tool_use. Ein Modell kann andere Werte zurückgeben, zum Beispiel refusal.
Die Stopp-Sequenz, die die Generierung beendet hat, oder null.
Token-Verbrauch mit input_tokens und output_tokens. Wenn das Modell Prompt-Cache-Token meldet, enthält usage auch cache_creation_input_tokens und cache_read_input_tokens.
Jede Antwort enthält die Request-ID in den Headern request-id und X-Request-ID. Geben Sie diese an, wenn Sie den Support kontaktieren.
Anfrage
curl -X POST "https://api.tokenlab.sh/v1/messages" \
-H "x-api-key: sk-your-api-key" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"system": "You are a helpful assistant.",
"messages": [
{"role": "user", "content": "Hello, Claude!"}
]
}'Antwort
{
"id": "msg_abc123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello! How can I help you today?"
}
],
"model": "claude-sonnet-5",
"stop_reason": "end_turn",
"usage": {
"input_tokens": 15,
"output_tokens": 10
}
}Vision-Input-Beispiel
Für Claude-Modelle mit Vision-Unterstützung platzieren Sie Bilder innerhalb von messages[].content als strukturierte Bildblöcke.
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Please describe this image."
},
{
"type": "image",
"source": {
"type": "url",
"url": "https://example.com/demo.jpg"
}
}
]
}
]
}{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Please describe this image."
},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRgABAQ..."
}
}
]
}
]
}Erweitertes Thinking-Beispiel
Verwenden Sie ein Modell mit der reasoning-Fähigkeit. Passen Sie max_tokens und budget_tokens an die Limits des Modells an; einige Modelle benötigen eine andere Thinking-Konfiguration.
from anthropic import Anthropic
client = Anthropic(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh"
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 10000
},
messages=[{"role": "user", "content": "Solve this math problem..."}]
)
for block in message.content:
if block.type == "thinking":
print(f"Thinking: {block.thinking}")
elif block.type == "text":
print(f"Response: {block.text}")Streaming
Setzen Sie "stream": true, um Anthropic Server-Sent Events zu empfangen: message_start, content_block_start, content_block_delta, content_block_stop, message_delta und message_stop. Der Token-Verbrauch wird in message_start und message_delta übermittelt.
from anthropic import Anthropic
client = Anthropic(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh"
)
with client.messages.stream(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)- Während das Modell arbeitet, kann der Stream SSE-Kommentarzeilen wie
: keep-aliveenthalten. SDKs ignorieren diese. - Der HTTP-Status kann bereits
200sein, wenn ein Fehler auftritt. Ein Fehler nach Beginn des Streams kommt alsevent: error-Ereignis mit demselben Fehler-Body wie unten an.
Fehler
Fehler verwenden das Anthropic-Fehlerformat. request_id ist die TokenLab-Request-ID. Einige Fehler fügen Felder wie code und hint hinzu.
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
},
"request_id": "req_01JEXAMPLE"
}| Status | error.type | Typische Ursache |
|---|---|---|
| 400 | invalid_request_error | Ein fehlendes oder ungültiges Feld, ein unbekanntes Modell oder ein Modell, das das Messages-Format nicht akzeptiert |
| 401 | authentication_error | Der API-Key fehlt oder ist ungültig |
| 402 | billing_error | Das Guthaben reicht nicht für die Anfrage aus (error.code ist insufficient_balance). Ein API-Key, der sein Ausgabenlimit erreicht hat, erhält ebenfalls 402, mit error.code quota_exceeded und error.type rate_limit_error |
| 403 | permission_error | Der API-Key kann das angeforderte Modell nicht verwenden, oder das Konto ist gesperrt oder eingeschränkt |
| 409 | conflict_error | Ein erneuter Versuch mit demselben Idempotency-Key. Siehe Sicheres Wiederholen mit einem Idempotency-Key |
| 413 | request_too_large | Die Eingabe der Anfrage ist zu groß |
| 429 | rate_limit_error | Zu viele Anfragen |
| 500, 502, 503 | api_error oder overloaded_error | Die Anfrage konnte nicht abgeschlossen werden, oder es ist derzeit keine Route verfügbar. Versuchen Sie es später erneut |
| 504 | timeout_error | Die Anfrage ist zeitlich abgelaufen |
Verwandte Schnittstellen
- Nachrichten-Token zählen: Schätzen Sie die Eingabe-Token einer Anfrage, bevor Sie diese senden.
- Message Batches führen viele Messages-Anfragen asynchron aus: erstellen, auflisten, abrufen, abbrechen, Ergebnisse abrufen und löschen.
Autorisierung
BearerAuth API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.
Ort: header
Header
Zustellungsrichtlinie pro Anfrage. Überschreibt die API-Key- und Workspace-Standardeinstellungen. Versucht automatisch zuerst TokenLab Verified und kann vor der Ausgabe, der Annahme der Anfrage oder der Erstellung persistenter Ressourcen einmalig auf Official umstellen.
Zulässige Werte
- "auto"
- "verified"
- "official"
Optionaler Schlüssel, der eine zweite Ausführung derselben Anfrage verhindert. Senden Sie für jede Anfrage einen neuen eindeutigen Wert, wie z. B. eine UUID, und behalten Sie diesen für Wiederholungsversuche nach einem Timeout bei. Ein Wiederholungsversuch mit demselben Schlüssel wird nicht erneut ausgeführt: Er gibt 409 mit idempotency_replay_unavailable zurück, oder bei geändertem Body in der Regel idempotency_conflict. Ausnahme: Wenn ein Nicht-Streaming-Ergebnis nach der Trennung des Clients abgeschlossen wurde, gibt ein Wiederholungsversuch mit demselben Schlüssel und Body innerhalb von 24 Stunden dieses Ergebnis (bis zu 1 MB) mit dem Header Idempotent-Replayed: true zurück, ohne dass eine zweite Gebühr anfällt. Ein Schlüssel mit mehr als 255 Zeichen wird ignoriert, und die Anfrage verfügt dann über keinen Idempotenz-Schutz. Siehe Sichere Wiederholungsversuche mit einem Idempotenz-Schlüssel.
1 <= length <= 255Anfragekörper
application/json
Antwort
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json