Überblick

Schnellstart

1. Melden Sie sich in der TOKENWERK-App an und erstellen Sie unter API-Keys einen neuen. Er beginnt mit tw- und wird nur einmal angezeigt.
2. Legen Sie ihn als Umgebungsvariable ab, alle Beispiele dieser Doku lesen ihn von dort.
3. Rufen Sie die Modellliste ab und stellen Sie die erste Anfrage.

export TOKENWERK_API_KEY="tw-..."

curl https://api.tokenwerk.ai/v1/models -H "Authorization: Bearer $TOKENWERK_API_KEY"

curl https://api.tokenwerk.ai/v1/chat/completions \
  -H "Authorization: Bearer $TOKENWERK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODELL",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Den Namen eines Modells (Feld model) finden Sie unter Modelle oder über GET /v1/models.

URLs

TOKENWERK spricht zwei Formate unter derselben Adresse. Welches Sie verwenden, entscheidet Ihr SDK oder Werkzeug.

Authentifizierung

Jede Anfrage braucht einen API-Key Ihrer Organisation, in einem der beiden Header:

Authorization: Bearer tw-...
x-api-key: tw-...

• OpenAI-SDKs senden Authorization: Bearer, Anthropic-SDKs x-api-key; beides funktioniert auf allen Endpunkten.
• API-Keys gehören zu Ihrer Organisation, optional zu einem Team, und können ein Ablaufdatum und Budgetlimits haben. Gesperrte oder abgelaufene API-Keys werden mit 401 abgewiesen.
• Verwenden Sie API-Keys nur serverseitig, nie im Browser oder in einer App, die Sie ausliefern.

Endpunkte

Alle anderen Pfade unter /v1 (Bilder, Audio, Dateien, Batches, …) antworten mit 404. Welche Endpunkte ein Modell tatsächlich unterstützt, hängt vom Modell ab: Embeddings etwa nur Embedding-Modelle.

Modelle

GET /v1/models listet die aktuell verfügbaren Modelle mit Kontextfenster und maximalem Output; Preise und Beschreibungen finden Sie unter Modelle.

{
  "object": "list",
  "data": [
    {
      "id": "MODELL",
      "object": "model",
      "created": 0,
      "owned_by": "tokenwerk",
      "context_window": 131072,
      "max_output_tokens": 32768
    }
  ]
}

Auto-Modelle (Art „Auto“) wählen künftig das passende Modell pro Anfrage. Das Routing ist noch nicht verfügbar, solche Anfragen werden vorerst mit 503 abgelehnt.

Streaming

Mit "stream": true kommt die Antwort als Server-Sent Events, im Format der jeweiligen API. Im OpenAI-Format liefert "stream_options": {"include_usage": true} zusätzlich einen letzten Chunk mit dem Tokenverbrauch.

curl -N https://api.tokenwerk.ai/v1/chat/completions \
  -H "Authorization: Bearer $TOKENWERK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODELL",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [{"role": "user", "content": "Hello"}]
  }'

curl -N https://api.tokenwerk.ai/v1/messages \
  -H "x-api-key: $TOKENWERK_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODELL",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Bricht Ihr Client einen Stream ab, wird die Anfrage beim Modell sofort beendet; abgerechnet werden nur die bis dahin verarbeiteten Tokens.

Tools & Bilder

Anfragen werden unverändert an das Modell weitergegeben, nur der Modellname wird übersetzt. Damit funktionieren Tool- bzw. Function-Calling (tools, tool_choice), strukturierte Ausgaben (response_format) und Bildeingaben (image_url bzw. image-Blöcke), sofern das gewählte Modell sie unterstützt. Coding-Agenten brauchen ein Modell mit Tool-Calling.

Fehler

Fehler kommen im Format der aufgerufenen API: im OpenAI-Format als {"error": {"message", "type", …}}, im Anthropic-Format als {"type": "error", "error": {"type", "message"}}.

Limits & Abrechnung

• Es gibt keine Anfrage-Limits pro API-Key. Begrenzt wird über Budgets: pro API-Key oder Team für Tag, Woche und Monat (UTC). Ist ein Budget aufgebraucht, beantworten wir weitere Anfragen mit 429. Ab einem einstellbaren Prozentsatz eines Budgets bekommen die Admins der Organisation eine Warnung per E-Mail.
• Abgerechnet wird pro Anfrage nach Tokens: Input, gecachter Input und Output, jeweils zum Preis pro 1 Million Tokens des Modells. Es gelten die Preise zum Start der Anfrage.
• Abgewiesene Anfragen kosten nichts. Ist das Guthaben aufgebraucht, beantworten wir Anfragen mit 402.
• Prompts und Antworten werden nicht gespeichert, nur Metadaten wie Tokens, Dauer und Preis.

API-Referenzen

TOKENWERK ist mit den APIs von OpenAI und Anthropic kompatibel. Alle Parameter finden Sie in deren Referenzen:

• OpenAI: Chat Completions ↗
• OpenAI: Responses ↗
• Anthropic: Messages ↗

Weiter: SDKs mit Beispielen für viele Sprachen und Agenten wie Claude Code oder opencode.