# 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](https://tokenlane.de/docs/guides/images.md?lang=de), [PDFs und Dateien](https://tokenlane.de/docs/guides/files.md?lang=de)). 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
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

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

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

```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](https://tokenlane.de/docs/guides/tool-calling.md?lang=de). |

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

```json
"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](https://tokenlane.de/docs/guides/streaming.md?lang=de). |

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](https://tokenlane.de/docs/guides/routing-and-fallbacks.md?lang=de)), `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](https://tokenlane.de/models) 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](https://tokenlane.de/docs/guides/privacy-and-compliance.md?lang=de)).

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](https://tokenlane.de/models).

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](https://tokenlane.de/docs/guides/errors-and-retries.md?lang=de).

## Bewährte Praxis
- Immer `max_tokens` setzen. Es begrenzt Kosten und Reservierung. Bei Reasoning-Modellen Platz zum Denken lassen, siehe [Reasoning](https://tokenlane.de/docs/guides/reasoning.md?lang=de).
- 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](https://tokenlane.de/docs/guides/structured-outputs.md?lang=de) 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.
