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.
| Rolle | Inhalt | Hinweise |
|---|---|---|
system, developer | nur Text | Ton, Sprache, Ausgabeformat. developer wird überall angenommen und wie system behandelt. |
user | Text oder ein Array von Teilen | Teile: text, image_url, input_audio, video_url, file. |
assistant | Text, oder null neben tool_calls | Eine frühere Antwort, zurückgesendet, um das Gespräch fortzusetzen. |
tool | Text oder Teile | Das 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?" }
]
| Parameter | Bereich | Bedeutung |
|---|---|---|
max_tokens, max_completion_tokens | Ganzzahl ab 1 | Obergrenze der Ausgabe, Reasoning-Tokens eingeschlossen. Sind beide gesetzt, gilt der kleinere Wert. 0 oder ein String wird ignoriert. |
temperature | 0 bis 2 | Zufälligkeit der Antwort. |
top_p, min_p, top_a | 0 bis 1 | Grenzen der Stichprobe. |
top_k | Ganzzahl ab 0 | Kandidaten je Token. |
frequency_penalty, presence_penalty, repetition_penalty | -2 bis 2, -2 bis 2, 0 bis 2 | Bremsen Wiederholungen. |
seed | Ganzzahl | Bestmöglich; nicht jeder Anbieter wiederholt Ergebnisse. |
stop | String oder Array von Strings | Die Antwort endet vor einer Stoppfolge. |
logprobs, top_logprobs | Boolean, 0 bis 20 | Token-Wahrscheinlichkeiten, soweit der Anbieter sie liefert. |
stream | Boolean | Server-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:
| Wert | Bedeutung |
|---|---|
stop | Die Antwort ist vollständig. |
length | Bei max_tokens oder am Ende des Kontexts abgeschnitten. |
tool_calls | Das Modell bittet darum, die Werkzeuge in message.tool_calls auszuführen. |
content_filter | Der Filter des Anbieters hat die Antwort gestoppt. |
error | Die Antwort ist fehlgeschlagen; im Stream trägt dasselbe Ereignis error. |
Grenzen:
| Grenze | Wert | Bei Überschreitung |
|---|---|---|
| Request-Body | 50 MiB | 413 payload_too_large |
| Prompt | context_length des Modells; die Prüfung schätzt 4 Bytes Text je Token (Nachrichten und Werkzeuge, ohne Medien) | 400 context_length_exceeded |
| Ausgabe | max_tokens bis zum Ausgabelimit der Route | 400 invalid_parameter; remedy_hint nennt das Maximum |
| Dauer | 600 s je Anfrage; im Stream 120 s ohne Chunk | 408 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,audiooderfile, 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, Typ | Ursache und Abhilfe |
|---|---|
400 invalid_parameter | Unbekannte 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_found | Die Modell-ID steht nicht im Katalog. Abhilfe: Die ID aus remedy_hint oder GET /v1/models nutzen. |
400 context_length_exceeded | Geschä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_credits | Die 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_denied | Die Policy des Keys erlaubt dieses Modell nicht. Abhilfe: Ein in remedy_hint genanntes Modell nutzen. |
404 no_endpoint | Keine 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_limited | Ein 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_tokenssetzen. 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
contentfinish_reasonprüfen:lengthbedeutet eine abgeschnittene Antwort. x-ignored-paramslesen: Der Header zeigt Parameter ohne Wirkung.- Nie Prompts, Antworten oder Keys loggen.
x-request-idfü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), HeaderAuthorization: Bearer $TOKENLANE_API_KEY. - Pflicht:
model(odermodels),messagesmit mindestens einem Objekt ausrole(system,developer,user,assistant,tool) undcontent. - 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[].pathundremedy_hintlesen; vor einer Wiederholung alle Probleme beheben. Nur 408, 429, 502 und 503 begrenzt wiederholen, mit Backoff. - Die Modell-ID nie raten: eine
idausGET /v1/modelskopieren.