# Text and chat
Send a conversation and get an answer: roles, parameters, limits, costs and errors of the chat endpoint.

## When to use it
`POST /chat/completions` serves every text task: questions, summaries, extraction, classification, code, agents with tools. Images, PDFs and audio travel through it as extra content parts ([images](https://tokenlane.de/docs/guides/images.md?lang=en), [PDFs and files](https://tokenlane.de/docs/guides/files.md?lang=en)). Embeddings, reranking and transcription have their own endpoints. The model keeps no state: every request carries the whole conversation.

## Minimal example
A system instruction, one user message and a bound on the answer. SDK base URLs end in `/v1`; direct HTTP calls append `/chat/completions`.

### 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);
```

The answer is in `choices[0].message.content`. Check `choices[0].finish_reason` before you use it.

## Request format
`messages` holds at least one message, oldest first; the model answers the last one.

| Role | Content | Notes |
|---|---|---|
| `system`, `developer` | text only | Tone, language, output format. `developer` is accepted everywhere and treated like `system`. |
| `user` | text, or an array of parts | Parts: `text`, `image_url`, `input_audio`, `video_url`, `file`. |
| `assistant` | text, or `null` next to `tool_calls` | An earlier answer, sent back to continue the conversation. |
| `tool` | text or parts | The result of a tool call; needs `tool_call_id`. See [Tool calling](https://tokenlane.de/docs/guides/tool-calling.md?lang=en). |

To continue a conversation, send the history again and append the new question:

```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 | Range | Meaning |
|---|---|---|
| `max_tokens`, `max_completion_tokens` | integer from 1 | Upper bound of the output, reasoning tokens included. If both are set, the smaller counts. `0` or a string is ignored. |
| `temperature` | 0 to 2 | Randomness of the answer. |
| `top_p`, `min_p`, `top_a` | 0 to 1 | Sampling cut-offs. |
| `top_k` | integer from 0 | Candidates per token. |
| `frequency_penalty`, `presence_penalty`, `repetition_penalty` | -2 to 2, -2 to 2, 0 to 2 | Discourage repetition. |
| `seed` | integer | Best effort; not every provider repeats results. |
| `stop` | string or array of strings | The answer ends before a stop sequence. |
| `logprobs`, `top_logprobs` | boolean, 0 to 20 | Token probabilities, where the provider supports them. |
| `stream` | boolean | Server-sent events, see [Streaming](https://tokenlane.de/docs/guides/streaming.md?lang=en). |

A value outside its range fails with 400 `invalid_parameter` and the field path. A parameter the chosen provider does not support is left out and named in the `x-ignored-params` response header; with `provider.require_parameters: true` such routes are skipped instead. Unknown names are ignored the same way, whatever `require_parameters` says. `n` is one of them: a request yields one choice.

Further fields: `models` (fallbacks after `model`), `provider` (see [Routing](https://tokenlane.de/docs/guides/routing-and-fallbacks.md?lang=en)), `response_format`, `tools`, `reasoning`, `plugins` (feature guides), `session_id` or header `x-session-id` (1 to 256 characters from letters, digits, `-`, `_`, `.`, `:`; groups generations), `user` (your end-user ID, passed on) and `cache_control` on a text part (marks a long unchanged prefix for providers with prompt caching).

In the response, `usage` holds `prompt_tokens`, `completion_tokens` (reasoning included), `total_tokens`, `cost` in EUR and `cost_details`. `model` names the model that answered, which differs from the request after an alias or a fallback. `finish_reason` is one of:

| Value | Meaning |
|---|---|
| `stop` | The answer is complete. |
| `length` | Cut off at `max_tokens` or the end of the context. |
| `tool_calls` | The model asks you to run the tools in `message.tool_calls`. |
| `content_filter` | The provider's filter stopped the answer. |
| `error` | The answer failed; in a stream the same event carries `error`. |

Limits:

| Limit | Value | When exceeded |
|---|---|---|
| Request body | 50 MiB | 413 `payload_too_large` |
| Prompt | the model's `context_length`; the check estimates 4 bytes of text per token (messages and tools, no media) | 400 `context_length_exceeded` |
| Output | `max_tokens` up to the output limit of the route | 400 `invalid_parameter`; `remedy_hint` names the maximum |
| Duration | 600 s per request; in a stream 120 s without a chunk | 408 `timeout`; stream long answers |

## Choosing a model
Read the catalog, not memory: `GET /v1/models` is public, and the [catalog](https://tokenlane.de/models) shows the same data. Look at:

- `context_length`, `top_provider.max_completion_tokens`: how much fits.
- `pricing.prompt`, `pricing.completion`: EUR per token; times 1,000,000 for the price per million.
- `supported_parameters`: `tools`, `response_format`, `reasoning`, sampling. A parameter missing there is dropped.
- `architecture.input_modalities`: `image`, `audio` or `file` if you send media.
- `routes`: provider, jurisdiction and data handling ([Privacy and compliance](https://tokenlane.de/docs/guides/privacy-and-compliance.md?lang=en)).

A catalog alias follows the current version of a model; `model` in the response names the model behind it.

## Costs
The charge is `prompt_tokens` times the prompt price plus `completion_tokens` times the completion price, in EUR, reported as `usage.cost`. Reasoning tokens bill like output unless the model prices them separately; cached prompt tokens use the cache-read price where a route has one. `cost_details` shows each line. If a provider reports no token counts, `cost` is absent, not zero.

Example: a request with 1,200 prompt tokens and 300 answer tokens costs 1,200 times the prompt price plus 300 times the completion price. Current prices are on each model page in the [catalog](https://tokenlane.de/models).

Before the call, the gateway reserves the estimated prompt plus `max_tokens`; without `max_tokens` it reserves the route's default output allowance of 16,384 tokens. The reservation must fit the key limit and the organization's credits, otherwise the request fails with 402 `insufficient_credits`. The unused part is released afterwards. Set `max_tokens` on keys with a small limit.

## Common errors
| Status, type | Cause and fix |
|---|---|
| 400 `invalid_parameter` | Unknown role, empty `messages`, an image in a `system` message, a number out of range. `issues` lists every problem with its path. **Fix:** Fix all listed paths, then retry once. |
| 400 `model_not_found` | The model ID is not in the catalog. **Fix:** Use the ID from `remedy_hint` or `GET /v1/models`. |
| 400 `context_length_exceeded` | Estimated prompt plus `max_tokens` exceeds the context of every route. **Fix:** Shorten the history, lower `max_tokens` or choose a model with more context. |
| 402 `insufficient_credits` | The reservation exceeds the key limit or the organization's credits; `message` says which. **Fix:** Lower `max_tokens`, top up credits, or raise the key limit. |
| 403 `permission_denied` | The key's policy does not allow this model. **Fix:** Use a model named in `remedy_hint`. |
| 404 `no_endpoint` | No route fits: media the model cannot read, `provider` filters, `max_price`, or `require_parameters`. **Fix:** Read `issues` per provider; relax the request-level filter or change the model. |
| 429 `rate_limited` | A key limit or the provider's rate limit. **Fix:** Wait `Retry-After` seconds, with backoff and jitter. |

All errors share one shape; see [Errors and retries](https://tokenlane.de/docs/guides/errors-and-retries.md?lang=en).

## Best practice
- Always set `max_tokens`. It bounds cost and the reservation. For reasoning models leave room for the thinking, see [Reasoning](https://tokenlane.de/docs/guides/reasoning.md?lang=en).
- Put stable instructions first in a `system` message and keep them identical between requests; providers with prompt caching charge less for an unchanged prefix.
- You pay for the history on every request. Summarize or drop old turns instead of resending everything.
- Check `finish_reason` before you use `content`: `length` means a truncated answer.
- Read `x-ignored-params`: it shows parameters that had no effect.
- Never log prompts, answers or keys. Keep `x-request-id` for support.
- For results a program reads, use [Structured outputs](https://tokenlane.de/docs/guides/structured-outputs.md?lang=en) instead of parsing prose.

## For AI agents
- Endpoint: [`POST /chat/completions`](https://tokenlane.de/docs/gateway/post-L2NoYXQvY29tcGxldGlvbnM.md?lang=en), header `Authorization: Bearer $TOKENLANE_API_KEY`.
- Required: `model` (or `models`), `messages` with at least one object that has `role` (`system`, `developer`, `user`, `assistant`, `tool`) and `content`.
- Optional: `max_tokens` (integer from 1), `temperature` (0 to 2), `top_p` (0 to 1), `stop`, `seed`, `stream`, `tools`, `response_format`, `reasoning`, `provider`, `plugins`, `session_id`.
- Response: `choices[0].message.content`, `choices[0].finish_reason`, `usage.prompt_tokens`, `usage.completion_tokens`, `usage.cost` (EUR), `model`, `provider`.
- Limits: body 50 MiB; prompt estimate 4 bytes of text per token against `context_length`; 600 s per request.
- Errors: read `error.metadata.type`, `issues[].path` and `remedy_hint`; fix all issues before you retry. Retry only 408, 429, 502 and 503, with bounded backoff.
- Never guess the model ID: copy an `id` from `GET /v1/models`.
