Text
Create Chat Completion
Creates a completion for the chat message
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.
ID of the model to use. See Models for available options.
A list of messages comprising the conversation.
Each message object contains:
role(string):system,developer,user,assistant,tool,functioncontent(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.
Sampling temperature. Support, allowed values, and the default depend on the selected model; omit this field to use its default.
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.
falseIf 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.
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.
Nucleus sampling parameter. We recommend altering this or temperature, not both.
Number between -2.0 and 2.0. Positive values penalize repeated tokens.
Number between -2.0 and 2.0. Positive values penalize tokens already in the text.
Stop sequence or list of sequences. Support and sequence limits depend on the selected model.
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.
Controls how the model uses tools. Options: auto, none, required, or { "type": "function", "function": { "name": "..." } } to force one tool.
Allow multiple tool calls in one assistant turn, when supported by the selected model.
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 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.
Options for Claude models.
prompt_caching(boolean): Settrueto 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 owncache_controlmarks, not both.prompt_caching_ttl(string):5m(default) or1h. 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.
Sampling seed for models that support it. Identical output is not guaranteed.
Number of completions to generate. Models that support it accept 1-128. Many models support only 1.
Whether to return log probabilities.
Number of top log probabilities to return (0-20). Requires logprobs: true.
Top-K sampling for models that support it.
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.
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.
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.
A unique identifier representing your end-user for abuse monitoring.
Response
Unique identifier for the completion.
Always chat.completion.
Unix timestamp of when the completion was created.
The model used for completion.
List of completion choices.
Each choice contains:
index(integer): Index of the choicemessage(object): The generated messagefinish_reason(string): Why the model stopped, for examplestop,length,tool_calls, orcontent_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.
Token usage statistics.
prompt_tokens(integer): Tokens in the promptcompletion_tokens(integer): Tokens in the completion, including thinking tokenstotal_tokens(integer): Total tokens usedprompt_tokens_details.cached_tokens(integer): Prompt tokens read from the cachecache_creation_input_tokens(integer): Prompt tokens written to the cache. Present only when the value is greater than 0completion_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
{
"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 API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
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"
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.
1 <= length <= 255Request Body
application/json
Response
application/json
application/json
application/json
application/json
application/json
application/json
application/json