Text & Chat

Nachricht erstellen

Erstellt eine Nachricht unter Verwendung des Anthropic Messages API-Formats

POST
/v1/messages

Ü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

x-api-keystringheader

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-versionstringheader

Anthropic API-Version. Anthropic SDKs senden diese automatisch; verwenden Sie 2023-06-01, wenn Sie die API direkt aufrufen.

anthropic-betastringheader

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.

modelstringerforderlich

ID eines Modells, das das anthropic_messages-Format unterstützt. Überprüfen Sie die Modelldetails auf aktuelle Fähigkeiten.

messagesarrayerforderlich

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

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.

systemstring | array

System-Prompt als String oder Array von Text-Inhaltsblöcken, getrennt vom messages-Array.

temperaturenumber

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.

streambooleanStandard: false

Gibt die Antwort als Stream von Server-Sent Events zurück. Siehe Streaming.

thinkingobject

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.

toolsarray

Verfügbare Tools für das Modell. Die Unterstützung hängt vom ausgewählten Modell ab.

tool_choiceobject

Natives Tool-Choice-Objekt, zum Beispiel {"type":"auto"}. Unterstützte Typen hängen vom ausgewählten Modell ab.

cache_controlobject

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.

top_pnumber

Nucleus-Sampling-Parameter. Verwenden Sie entweder temperature oder top_p, nicht beides. Die Unterstützung hängt vom ausgewählten Modell ab.

top_kinteger

Sampling nur aus den Top-K-Optionen für jedes Token. Die Unterstützung hängt vom ausgewählten Modell ab.

stop_sequencesarray

Benutzerdefinierte Stopp-Sequenzen, die das Modell dazu veranlassen, die Generierung zu beenden. Bis zu 8.191 Einträge.

metadataobject

Request-Metadaten im Anthropic-Format. user_id ist ein undurchsichtiger Identifikator für Ihren Endbenutzer.

service_tierstring

Nur auto und standard_only haben eine Wirkung. TokenLab berechnet nur den Standard-Tier und ignoriert jeden anderen Wert.

Antwort

idstring

Eindeutiger Nachrichten-Identifikator.

typestring

Immer message.

rolestring

Immer assistant.

contentarray

Array von Inhaltsblöcken, wie text, thinking oder tool_use.

modelstring

Modell, das die Antwort generiert hat.

stop_reasonstring

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.

stop_sequencestring | null

Die Stopp-Sequenz, die die Generierung beendet hat, oder null.

usageobject

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

Response
{
  "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-alive enthalten. SDKs ignorieren diese.
  • Der HTTP-Status kann bereits 200 sein, wenn ein Fehler auftritt. Ein Fehler nach Beginn des Streams kommt als event: 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"
}
Statuserror.typeTypische Ursache
400invalid_request_errorEin fehlendes oder ungültiges Feld, ein unbekanntes Modell oder ein Modell, das das Messages-Format nicht akzeptiert
401authentication_errorDer API-Key fehlt oder ist ungültig
402billing_errorDas 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
403permission_errorDer API-Key kann das angeforderte Modell nicht verwenden, oder das Konto ist gesperrt oder eingeschränkt
409conflict_errorEin erneuter Versuch mit demselben Idempotency-Key. Siehe Sicheres Wiederholen mit einem Idempotency-Key
413request_too_largeDie Eingabe der Anfrage ist zu groß
429rate_limit_errorZu viele Anfragen
500, 502, 503api_error oder overloaded_errorDie Anfrage konnte nicht abgeschlossen werden, oder es ist derzeit keine Route verfügbar. Versuchen Sie es später erneut
504timeout_errorDie Anfrage ist zeitlich abgelaufen

Verwandte Schnittstellen

Autorisierung

BearerAuth
AuthorizationBearer <token>

API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.

Ort: header

Header

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Länge1 <= length <= 255

Anfragekö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