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, PDFs and files). 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 --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);
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. |
To continue a conversation, send the history again and append the new question:
"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. |
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), 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 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,audioorfileif you send media.routes: provider, jurisdiction and data handling (Privacy and compliance).
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.
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.
Best practice
- Always set
max_tokens. It bounds cost and the reservation. For reasoning models leave room for the thinking, see Reasoning. - Put stable instructions first in a
systemmessage 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_reasonbefore you usecontent:lengthmeans a truncated answer. - Read
x-ignored-params: it shows parameters that had no effect. - Never log prompts, answers or keys. Keep
x-request-idfor support. - For results a program reads, use Structured outputs instead of parsing prose.
For AI agents
- Endpoint: [
POST /chat/completions](https://tokenlane.de/docs/gateway/post-L2NoYXQvY29tcGxldGlvbnM.md?lang=en), headerAuthorization: Bearer $TOKENLANE_API_KEY. - Required:
model(ormodels),messageswith at least one object that hasrole(system,developer,user,assistant,tool) andcontent. - 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[].pathandremedy_hint; fix all issues before you retry. Retry only 408, 429, 502 and 503, with bounded backoff. - Never guess the model ID: copy an
idfromGET /v1/models.