TokenLab

Text

Create Chat Completion

Creates a completion for the chat message

POST
/v1/chat/completions

Request Body

Supported optional parameters, accepted values, and defaults depend on the selected model. Check its model details before setting sampling, reasoning, or tool options. A control the model cannot honor, such as n above 1 on some models, is rejected with a 4xx error. Minor sampling controls such as seed or the penalties can be ignored instead.

modelstringrequired

ID of the model to use. See Models for available options.

messagesarrayrequired

A list of messages comprising the conversation.

Each message object contains:

  • role (string): system, developer, user, assistant, tool, function
  • content (string | array | null): The message content

For an assistant message containing tool_calls, content may be omitted or set to null.

When content is an array, TokenLab supports structured multimodal blocks for compatible models:

  • text: { "type": "text", "text": "..." }
  • image: { "type": "image_url", "image_url": { "url": "https://..." } }
  • video: { "type": "video_url", "video_url": { "url": "https://..." } }
  • audio: { "type": "input_audio", "input_audio": { "data": "https://... or base64 data URL", "format": "wav" } }, or { "type": "audio_url", "audio_url": { "url": "https://..." } }

For multimodal input, use publicly reachable https URLs. Images can also be sent as base64 data URLs. Supported media types depend on the selected model.

temperaturenumber

Sampling temperature. Support, allowed values, and the default depend on the selected model; omit this field to use its default.

max_tokensinteger

Maximum number of tokens to generate. Send either max_tokens or max_completion_tokens, not both: a model served over another protocol can reject a request that has both.

On a model that thinks, thinking tokens count against this limit. If the limit is too small, the whole budget can go to thinking and leave an empty message body, and the tokens used are still billed. Raise the limit, or turn thinking off where the model allows it, for example with "reasoning_effort": "none". On deepseek-v4.1-flash (alias deepseek-flash), "thinking": {"type": "disabled"} also turns it off.

Before the request runs, TokenLab checks that your balance covers this maximum. A very large value can return 402 on a low balance even when the answer is short.

streambooleandefault: false

If true, partial message deltas are sent as server-sent events (SSE). See Streaming.

For long outputs (thousands of tokens or more), set stream: true so clients and proxies do not time out while they wait for the full response.

stream_optionsobject

Options for streaming. Set include_usage: true to receive one extra chunk with token usage before data: [DONE]. Without it, the stream carries no usage.

top_pnumber

Nucleus sampling parameter. We recommend altering this or temperature, not both.

frequency_penaltynumber

Number between -2.0 and 2.0. Positive values penalize repeated tokens.

presence_penaltynumber

Number between -2.0 and 2.0. Positive values penalize tokens already in the text.

stopstring | array

Stop sequence or list of sequences. Support and sequence limits depend on the selected model.

toolsarray

A list of tools the model may call (function calling). Each tool is { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }. See Structured outputs and tool calling.

tool_choicestring | object

Controls how the model uses tools. Options: auto, none, required, or { "type": "function", "function": { "name": "..." } } to force one tool.

parallel_tool_callsboolean

Allow multiple tool calls in one assistant turn, when supported by the selected model.

max_completion_tokensinteger

Upper bound for the completion, including thinking tokens. Alternative to max_tokens used by newer OpenAI model families. Send only one of the two.

reasoning_effortstring

Reasoning effort for models that support it. Accepted values depend on the selected model.

For Claude models, the value sets the model's thinking: an effort level on models with adaptive thinking, or a thinking budget on models that use one. none turns thinking off on models that allow it. A value the model does not support is rejected with 400, code invalid_value, and the error lists the supported values. While thinking is on, Claude rejects a temperature other than 1, top_k, a top_p outside 0.95–1, and a prefilled assistant message. A forced tool_choice works with adaptive thinking but not with a thinking budget.

anthropic_optionsobject

Options for Claude models.

  • prompt_caching (boolean): Set true to cache the start of the prompt. TokenLab marks the end of the system prompt and the latest user message as cache points. A later request that starts with the same content reads it from the cache. Use either this option or your own cache_control marks, not both.
  • prompt_caching_ttl (string): 5m (default) or 1h. When the service that handles the request cannot keep a cache for one hour, TokenLab can use the five-minute cache instead of rejecting the request.

extra.prompt_caching and extra.prompt_caching_ttl are accepted as the same options. See Prompt caching for prices and how to check the cached tokens.

seedinteger

Sampling seed for models that support it. Identical output is not guaranteed.

ninteger

Number of completions to generate. Models that support it accept 1-128. Many models support only 1.

logprobsboolean

Whether to return log probabilities.

top_logprobsinteger

Number of top log probabilities to return (0-20). Requires logprobs: true.

top_kinteger

Top-K sampling for models that support it.

response_formatobject

Response format. Use {"type": "text"} (default), {"type": "json_object"} for JSON mode, or {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} for a JSON schema. Support depends on the selected model. See Structured outputs and tool calling.

logit_biasobject

Modify the likelihood of specified tokens appearing. Map token IDs (as strings) to bias values from -100 to 100. Support depends on the selected model.

service_tierstring

TokenLab serves and bills Chat requests at the standard service tier. auto and default are accepted. Other values, such as flex or priority, are removed from the request, and the request is billed at the standard price.

userstring

A unique identifier representing your end-user for abuse monitoring.

Response

idstring

Unique identifier for the completion.

objectstring

Always chat.completion.

createdinteger

Unix timestamp of when the completion was created.

modelstring

The model used for completion.

choicesarray

List of completion choices.

Each choice contains:

  • index (integer): Index of the choice
  • message (object): The generated message
  • finish_reason (string): Why the model stopped, for example stop, length, tool_calls, or content_filter

When the model thinks, message can also contain:

  • reasoning_content (string): The thinking text. Some models return only a summary, or no text.
  • reasoning_details (array): Thinking blocks with their signatures. To continue a conversation with thinking, for example after a tool call, send them back unchanged in the assistant message.

In a stream, the same fields arrive as delta.reasoning_content and delta.reasoning_details.

usageobject

Token usage statistics.

  • prompt_tokens (integer): Tokens in the prompt
  • completion_tokens (integer): Tokens in the completion, including thinking tokens
  • total_tokens (integer): Total tokens used
  • prompt_tokens_details.cached_tokens (integer): Prompt tokens read from the cache
  • cache_creation_input_tokens (integer): Prompt tokens written to the cache. Present only when the value is greater than 0
  • completion_tokens_details.reasoning_tokens (integer): Thinking tokens, when the model reports them

In a stream, usage arrives only when stream_options.include_usage is true.

Request

curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

Multimodal Example

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

Response

Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Streaming

With stream: true, the response is a text/event-stream. Each event is data: {...} with a chat.completion.chunk object whose choices[].delta carries the new text, tool call arguments, or thinking text. The stream ends with data: [DONE]. Lines that start with : are keep-alive comments: ignore them. A stream that ends without [DONE] or without a finish_reason is incomplete. See Streaming.

Errors

Errors use the OpenAI-style error object. Common cases: 400 for an invalid field or a value the model does not accept, 401 for an invalid key, 402 for insufficient balance, 413 for input over the size limit, and 429 for the rate limit. See Handle API errors.

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Value in

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Optional key that stops a second run of the same request. Send a new unique value, such as a UUID, for each request, and keep it for retries after a timeout. A retry with the same key does not run again: it returns 409 with idempotency_replay_unavailable, or usually idempotency_conflict when the body changed. Exception: when a non-stream result finished after the client disconnected, a retry with the same key and body within 24 hours returns that result (up to 1 MB) with the header Idempotent-Replayed: true and no second charge. A key longer than 255 characters is ignored, and the request then has no idempotency protection. See Retry safely with an idempotency key.

Length1 <= length <= 255

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json