Text und Chat

Ein Gespräch senden und eine Antwort erhalten: Rollen, Parameter, Grenzen, Kosten und Fehler des Chat-Endpunkts.

Wann nutzen

POST /chat/completions bedient jede Textaufgabe: Fragen, Zusammenfassungen, Extraktion, Klassifikation, Code, Agenten mit Werkzeugen. Bilder, PDFs und Audio laufen als zusätzliche Inhaltsteile durch denselben Endpunkt (Bilder, PDFs und Dateien). Embeddings, Rerank und Transkription haben eigene Endpunkte. Das Modell speichert nichts: Jede Anfrage enthält das ganze Gespräch.

Minimalbeispiel

Eine Systemanweisung, eine Nutzernachricht und eine Obergrenze für die Antwort. Die SDK-Basisadresse endet auf /v1; bei direkten HTTP-Aufrufen kommt /chat/completions dazu.

curl

curl --request POST \
  --url 'https://api.tokenlane.de/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "system",
      "content": "Answer in one sentence."
    },
    {
      "role": "user",
      "content": "What is the capital of Portugal?"
    }
  ],
  "max_tokens": 400,
  "temperature": 0.2
}'

node

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.chat.completions.create({
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "system",
      "content": "Answer in one sentence."
    },
    {
      "role": "user",
      "content": "What is the capital of Portugal?"
    }
  ],
  "max_tokens": 400,
  "temperature": 0.2
}, {});
console.log(response);

python

import os
import json
from openai import OpenAI

client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "system",
      "content": "Answer in one sentence."
    },
    {
      "role": "user",
      "content": "What is the capital of Portugal?"
    }
  ],
  "max_tokens": 400,
  "temperature": 0.2
}''')
response = client.chat.completions.create(
    model=body["model"],
    messages=body["messages"],
    max_tokens=body["max_tokens"],
    temperature=body["temperature"]
)
print(response)

vercel

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

const tokenlane = createOpenAICompatible({ name: 'tokenlane', baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY, includeUsage: true });
const result = await generateText({
  model: tokenlane("deepseek/deepseek-v4-flash-0731"),
  system: "Answer in one sentence.",
  messages: [
  {
    "role": "user",
    "content": "What is the capital of Portugal?"
  }
],
  maxOutputTokens: 400,
  temperature: 0.2,
});
console.log(result.text);

Die Antwort steht in choices[0].message.content. Vor der Verwendung choices[0].finish_reason prüfen.

Anfrageformat

messages enthält mindestens eine Nachricht, älteste zuerst; das Modell beantwortet die letzte.

RolleInhaltHinweise
system, developernur TextTon, Sprache, Ausgabeformat. developer wird überall angenommen und wie system behandelt.
userText oder ein Array von TeilenTeile: text, image_url, input_audio, video_url, file.
assistantText, oder null neben tool_callsEine frühere Antwort, zurückgesendet, um das Gespräch fortzusetzen.
toolText oder TeileDas Ergebnis eines Werkzeugaufrufs; braucht tool_call_id. Siehe Funktionsaufrufe.

Zum Fortsetzen den Verlauf erneut senden und die neue Frage anhängen:

"messages": [
  { "role": "system", "content": "Answer in one sentence." },
  { "role": "user", "content": "What is the capital of Portugal?" },
  { "role": "assistant", "content": "Lisbon." },
  { "role": "user", "content": "And how many people live there?" }
]
ParameterBereichBedeutung
max_tokens, max_completion_tokensGanzzahl ab 1Obergrenze der Ausgabe, Reasoning-Tokens eingeschlossen. Sind beide gesetzt, gilt der kleinere Wert. 0 oder ein String wird ignoriert.
temperature0 bis 2Zufälligkeit der Antwort.
top_p, min_p, top_a0 bis 1Grenzen der Stichprobe.
top_kGanzzahl ab 0Kandidaten je Token.
frequency_penalty, presence_penalty, repetition_penalty-2 bis 2, -2 bis 2, 0 bis 2Bremsen Wiederholungen.
seedGanzzahlBestmöglich; nicht jeder Anbieter wiederholt Ergebnisse.
stopString oder Array von StringsDie Antwort endet vor einer Stoppfolge.
logprobs, top_logprobsBoolean, 0 bis 20Token-Wahrscheinlichkeiten, soweit der Anbieter sie liefert.
streamBooleanServer-Sent Events, siehe Streaming.

Ein Wert außerhalb seines Bereichs ergibt 400 invalid_parameter mit dem Feldpfad. Ein Parameter, den der gewählte Anbieter nicht unterstützt, wird weggelassen und im Antwort-Header x-ignored-params genannt; mit provider.require_parameters: true werden solche Routen stattdessen übersprungen. Unbekannte Namen werden ebenso ignoriert, unabhängig von require_parameters. Dazu gehört n: Eine Anfrage liefert genau eine Antwort.

Weitere Felder: models (Ausweichmodelle nach model), provider (siehe Routing), response_format, tools, reasoning, plugins (Funktionsleitfäden), session_id oder Header x-session-id (1 bis 256 Zeichen aus Buchstaben, Ziffern, -, _, ., :; gruppiert Generierungen), user (die ID des Endnutzers, wird weitergereicht) und cache_control an einem Textteil (markiert einen langen unveränderten Anfang für Anbieter mit Prompt-Caching).

In der Antwort enthält usage die Felder prompt_tokens, completion_tokens (Reasoning eingeschlossen), total_tokens, cost in EUR und cost_details. model nennt das Modell, das geantwortet hat; nach einem Alias oder Ausweichen weicht es von der Anfrage ab. finish_reason ist einer von:

WertBedeutung
stopDie Antwort ist vollständig.
lengthBei max_tokens oder am Ende des Kontexts abgeschnitten.
tool_callsDas Modell bittet darum, die Werkzeuge in message.tool_calls auszuführen.
content_filterDer Filter des Anbieters hat die Antwort gestoppt.
errorDie Antwort ist fehlgeschlagen; im Stream trägt dasselbe Ereignis error.

Grenzen:

GrenzeWertBei Überschreitung
Request-Body50 MiB413 payload_too_large
Promptcontext_length des Modells; die Prüfung schätzt 4 Bytes Text je Token (Nachrichten und Werkzeuge, ohne Medien)400 context_length_exceeded
Ausgabemax_tokens bis zum Ausgabelimit der Route400 invalid_parameter; remedy_hint nennt das Maximum
Dauer600 s je Anfrage; im Stream 120 s ohne Chunk408 timeout; lange Antworten streamen

Modell wählen

Den Katalog lesen, nicht aus dem Gedächtnis wählen: GET /v1/models ist öffentlich, und der Katalog zeigt dieselben Daten. Wichtig sind:

  • context_length, top_provider.max_completion_tokens: wie viel hineinpasst.
  • pricing.prompt, pricing.completion: EUR je Token; mal 1.000.000 ergibt den Preis je Million.
  • supported_parameters: tools, response_format, reasoning, Sampling. Ein dort fehlender Parameter wird weggelassen.
  • architecture.input_modalities: image, audio oder file, wenn Medien gesendet werden.
  • routes: Anbieter, Rechtsraum und Datenbehandlung (Datenschutz und Compliance).

Ein Katalog-Alias folgt der aktuellen Version eines Modells; model in der Antwort nennt das Modell dahinter.

Kosten

Der Betrag ist prompt_tokens mal Prompt-Preis plus completion_tokens mal Completion-Preis, in EUR, ausgewiesen als usage.cost. Reasoning-Tokens werden wie Ausgabe abgerechnet, sofern das Modell sie nicht eigens bepreist; gecachte Prompt-Tokens nutzen den Cache-Lesepreis, wo eine Route einen hat. cost_details zeigt jede Position. Meldet ein Anbieter keine Tokenzahlen, fehlt cost, es ist nicht null.

Beispiel: Eine Anfrage mit 1.200 Prompt-Tokens und 300 Antwort-Tokens kostet 1.200 mal den Prompt-Preis plus 300 mal den Completion-Preis. Die aktuellen Preise stehen auf jeder Modellseite im Katalog.

Vor dem Aufruf reserviert das Gateway den geschätzten Prompt plus max_tokens; ohne max_tokens reserviert es die Standard-Ausgabemenge der Route von 16.384 Tokens. Die Reservierung muss in das Key-Limit und das Guthaben der Organisation passen, sonst scheitert die Anfrage mit 402 insufficient_credits. Der ungenutzte Teil wird danach freigegeben. Bei Keys mit kleinem Limit immer max_tokens setzen.

Häufige Fehler

Status, TypUrsache und Abhilfe
400 invalid_parameterUnbekannte Rolle, leeres messages, ein Bild in einer system-Nachricht, eine Zahl außerhalb des Bereichs. issues nennt jedes Problem mit Pfad. Abhilfe: Alle genannten Pfade korrigieren, dann einmal wiederholen.
400 model_not_foundDie Modell-ID steht nicht im Katalog. Abhilfe: Die ID aus remedy_hint oder GET /v1/models nutzen.
400 context_length_exceededGeschätzter Prompt plus max_tokens übersteigt den Kontext jeder Route. Abhilfe: Verlauf kürzen, max_tokens senken oder ein Modell mit mehr Kontext wählen.
402 insufficient_creditsDie Reservierung übersteigt das Key-Limit oder das Guthaben der Organisation; message nennt, welches. Abhilfe: max_tokens senken, Guthaben aufladen oder das Key-Limit erhöhen.
403 permission_deniedDie Policy des Keys erlaubt dieses Modell nicht. Abhilfe: Ein in remedy_hint genanntes Modell nutzen.
404 no_endpointKeine Route passt: Medien, die das Modell nicht lesen kann, provider-Filter, max_price oder require_parameters. Abhilfe: issues je Anbieter lesen; den Filter in der Anfrage lockern oder das Modell wechseln.
429 rate_limitedEin Key-Limit oder das Ratenlimit des Anbieters. Abhilfe: Retry-After Sekunden warten, mit Backoff und Jitter.

Alle Fehler haben dieselbe Form; siehe Fehler und Wiederholungen.

Bewährte Praxis

  • Immer max_tokens setzen. Es begrenzt Kosten und Reservierung. Bei Reasoning-Modellen Platz zum Denken lassen, siehe Reasoning.
  • Stabile Anweisungen zuerst in eine system-Nachricht und zwischen Anfragen unverändert lassen; Anbieter mit Prompt-Caching berechnen einen unveränderten Anfang günstiger.
  • Der Verlauf wird bei jeder Anfrage bezahlt. Alte Runden zusammenfassen oder weglassen, statt alles erneut zu senden.
  • Vor der Verwendung von content finish_reason prüfen: length bedeutet eine abgeschnittene Antwort.
  • x-ignored-params lesen: Der Header zeigt Parameter ohne Wirkung.
  • Nie Prompts, Antworten oder Keys loggen. x-request-id für den Support aufbewahren.
  • Für Ergebnisse, die ein Programm liest, Strukturierte Ausgaben statt Prosa-Parsing nutzen.

Für KI-Agenten

  • Endpunkt: [POST /chat/completions](https://tokenlane.de/docs/gateway/post-L2NoYXQvY29tcGxldGlvbnM.md?lang=de), Header Authorization: Bearer $TOKENLANE_API_KEY.
  • Pflicht: model (oder models), messages mit mindestens einem Objekt aus role (system, developer, user, assistant, tool) und content.
  • Optional: max_tokens (Ganzzahl ab 1), temperature (0 bis 2), top_p (0 bis 1), stop, seed, stream, tools, response_format, reasoning, provider, plugins, session_id.
  • Antwort: choices[0].message.content, choices[0].finish_reason, usage.prompt_tokens, usage.completion_tokens, usage.cost (EUR), model, provider.
  • Grenzen: Body 50 MiB; Prompt-Schätzung 4 Bytes Text je Token gegen context_length; 600 s je Anfrage.
  • Fehler: error.metadata.type, issues[].path und remedy_hint lesen; vor einer Wiederholung alle Probleme beheben. Nur 408, 429, 502 und 503 begrenzt wiederholen, mit Backoff.
  • Die Modell-ID nie raten: eine id aus GET /v1/models kopieren.