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.

RoleContentNotes
system, developertext onlyTone, language, output format. developer is accepted everywhere and treated like system.
usertext, or an array of partsParts: text, image_url, input_audio, video_url, file.
assistanttext, or null next to tool_callsAn earlier answer, sent back to continue the conversation.
tooltext or partsThe 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?" }
]
ParameterRangeMeaning
max_tokens, max_completion_tokensinteger from 1Upper bound of the output, reasoning tokens included. If both are set, the smaller counts. 0 or a string is ignored.
temperature0 to 2Randomness of the answer.
top_p, min_p, top_a0 to 1Sampling cut-offs.
top_kinteger from 0Candidates per token.
frequency_penalty, presence_penalty, repetition_penalty-2 to 2, -2 to 2, 0 to 2Discourage repetition.
seedintegerBest effort; not every provider repeats results.
stopstring or array of stringsThe answer ends before a stop sequence.
logprobs, top_logprobsboolean, 0 to 20Token probabilities, where the provider supports them.
streambooleanServer-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:

ValueMeaning
stopThe answer is complete.
lengthCut off at max_tokens or the end of the context.
tool_callsThe model asks you to run the tools in message.tool_calls.
content_filterThe provider's filter stopped the answer.
errorThe answer failed; in a stream the same event carries error.

Limits:

LimitValueWhen exceeded
Request body50 MiB413 payload_too_large
Promptthe model's context_length; the check estimates 4 bytes of text per token (messages and tools, no media)400 context_length_exceeded
Outputmax_tokens up to the output limit of the route400 invalid_parameter; remedy_hint names the maximum
Duration600 s per request; in a stream 120 s without a chunk408 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, audio or file if 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, typeCause and fix
400 invalid_parameterUnknown 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_foundThe model ID is not in the catalog. Fix: Use the ID from remedy_hint or GET /v1/models.
400 context_length_exceededEstimated 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_creditsThe 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_deniedThe key's policy does not allow this model. Fix: Use a model named in remedy_hint.
404 no_endpointNo 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_limitedA 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 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 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.