Call text-chat models through one API with support for standard Chat Completions, streaming responses, structured output, tool calling, and provider routing policies.
https://api.tokensmarket.ai/v1POST /chat/completionsThe endpoint does not change. Use the current model details page for the model ID and available parameters.
${base_url}/chat/completions| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
Authorization | string | Yes | — | Bearer API Key. The complete API Key is shown only once, immediately after creation. |
Content-Type | string | Yes | application/json | Send the request body as JSON. |
X-Session-Id | string | No | — | Optional Session ID; used only if the request does not provide the top-level session_id or extra_body.session_id. Options / constraints: Maximum 256 characters. |
X-Client-Request-Id | string | No | — | Optional caller correlation ID; when provided, the response will echo this value. |
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | — | A real model ID from the Model Market. Supported parameters and capabilities vary by model; use the current model details page as the source of truth. Options / constraints: Get it from the model list or model details page. |
messages | array | Yes | — | Sequential conversation messages. content can be null when assistant carries tool_calls. Options / constraints: role: system, developer, user, assistant, tool; compatible with old function messages. |
messages[].name | string | No | — | Name of the message sender. Options / constraints: Can distinguish messages with the same role when supported by the model. |
messages[].content | string | array | null | No | — | Conditionally required: use a string for ordinary messages and a content array for multimodal models. It can be null when an assistant message returns only tool_calls. Options / constraints: Content item type: text, image_url, video_url, input_audio, file. |
messages[].content[].text | string | No | — | Body text for a text content item. Options / constraints: Use when type=text. |
messages[].content[].image_url | object | No | — | Image resource object containing an accessible image URL. Options / constraints: Used when type=image_url; fields: url and detail. |
messages[].content[].image_url.detail | string | No | — | Image detail level. Options / constraints: Used when type=image_url. |
messages[].content[].video_url | object | No | — | Video resource object containing an accessible video URL. Options / constraints: Use when type=video_url. Field: url. |
messages[].content[].input_audio | object | No | — | Input audio data and format. Options / constraints: Used when type=input_audio; fields: data and format. |
messages[].content[].file | object | No | — | Input file object. Options / constraints: Used when type=file; fields: file_data, file_id, and filename. |
messages[].content[].file.file_data | string | No | — | File data. Options / constraints: When type=file, send data using an encoding supported by the model. |
messages[].content[].file.file_id | string | No | — | Identifier of an uploaded file. Options / constraints: Used when type=file. |
messages[].content[].file.filename | string | No | — | File name. Options / constraints: Used when type=file. |
messages[].content[].prompt_cache_breakpoint | object | No | — | Prompt cache breakpoint for a content item. Options / constraints: Use when supported by the model. |
messages[].tool_call_id | string | No | — | When role=tool is used, associate the tool call ID to be returned with results. |
messages[].tool_calls | array | No | — | A tool call initiated by the assistant; the application is responsible for executing and returning the results in subsequent tool messages. |
messages[].audio | object | No | — | Audio information in the message. Options / constraints: Use when supported by the model. |
messages[].refusal | string | No | — | Content refused by the model. Options / constraints: Returned or sent when supported by the model. |
messages[].reasoning_content | string | No | — | Reasoning content in the message. Options / constraints: Use when supported by the model. |
messages[].reasoning | object|string | No | — | Reasoning settings or content in the message. Options / constraints: Use when supported by the model. |
messages[].reasoning_details | array | No | — | Reasoning details in the message. Options / constraints: Use when supported by the model. |
messages[].function_call | object | No | — | Deprecated legacy function call. Options / constraints: Deprecated; use tool_calls for new integrations. |
functions | array | No | — | Deprecated legacy function definitions. Options / constraints: Deprecated; use tools for new integrations. |
max_completion_tokens | integer | No | — | Limit the generation budget, including visible output and reasoning tokens. Options / constraints: Use either max_completion_tokens or max_tokens, based on the selected model. |
max_tokens | integer | No | — | The maximum number of generated tokens compatible with the old model. Options / constraints: Use either max_completion_tokens or max_tokens, based on the selected model. |
temperature / top_p | float | No | — | Sampling parameters. The value range and whether it is supported are determined by the model. Options / constraints: Usually only one of them is adjusted. |
presence_penalty / frequency_penalty | float | No | — | Adjusts the likelihood of repeating topics or tokens. Options / constraints: Support and the accepted value range depend on the model. |
logit_bias | object | No | — | Adjusts the sampling preference for specified tokens. Options / constraints: Use when supported by the model. |
n/stop/seed | integer | string | string[] | No | — | Number of candidates, stopping sequence, and repeatability control. Options / constraints: stop at most 4; only sent if supported by the model. |
stream | boolean | No | false | Whether to return incremental content via SSE streaming. After enabling it, the client needs to process chunks one by one, and handle disconnects and retries. Options / constraints: true/false. |
stream_options | object | No | — | Additional options for streaming responses. Options / constraints: include_usage: boolean, default true. |
logprobs / top_logprobs | boolean | integer | No | — | Returns token log probabilities when supported by the model. |
modalities | string[] | No | ["text"] | Expected output type. When audio is required, pass ["text", "audio"] and audio configuration at the same time. Options / constraints: Check the model details page for supported capabilities. |
audio | object | No | — | Audio output configuration. Options / constraints: voice, format; only used when modalities include audio. |
response_format | object | No | — | Constraint model return format. Options / constraints: type: text, json_object, json_schema; only supported by some models. |
moderation | object|string | No | — | Content moderation controls when supported by the model. |
tools / tool_choice / parallel_tool_calls | array | string | object | No | — | Tool definition, selection strategy and parallel tool invocation control. Options / constraints: Applications must verify parameters, execution permissions, and tool results. |
reasoning / reasoning_effort / prediction / verbosity | object|string | No | — | Inference and output control fields. Options / constraints: Only sent if supported by the model. |
metadata | object | No | — | Request metadata. |
cache_control | object | No | — | Prompt cache controls. |
store | boolean | No | — | Whether to store the response according to the protocol. |
safety_identifier | string | No | — | Safety identifier. |
user | string | No | — | End-user identifier. |
session_id | string | No | — | Top-level Session ID. Options / constraints: Takes precedence over extra_body.session_id and X-Session-Id; maximum 256 characters. |
prompt_cache_key | string | No | — | Prompt cache key. |
prompt_cache_options | object | No | — | Prompt cache options. |
prompt_cache_retention | string | No | — | Deprecated prompt cache retention policy. Options / constraints: Deprecated. |
service_tier | string | No | — | Service tier when supported by the model. |
thinking | object|string | No | — | Extended thinking configuration. Options / constraints: Use when supported by the model. |
web_search_options | object | No | — | Web Search configuration when supported by the model. |
extra_body | object | No | — | Extension fields for the Unified API. Options / constraints: Only provider and session_id are public extension fields. Place provider routing controls under extra_body.provider. |
When provider is omitted, the platform uses its default strategy. Place provider routing controls under extra_body.provider when you need explicit control over cost, latency, or fallback.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
only | string[] | No | — | Provider allowlist. Selects providers only from the specified set. Options / constraints: Provider names are case-sensitive. |
order | string[] | No | — | Applies the preferred provider order after filtering and sorting. Options / constraints: Processing order: ignore → ranges → only → sort → order. |
sort | string | string[] | No | — | Provider sort policy. Accepts multiple keywords; fields earlier in the array have higher priority. Options / constraints: input_price, output_price, throughput, latency, input_length. |
input_price_range | [number, number] | No | — | Filters providers by base USD input unit price. Options / constraints: Unit: USD per million tokens. A shared price.group_ratio does not change provider price ordering. |
output_price_range | [number, number] | No | — | Filters providers by base USD output unit price. Options / constraints: Unit: USD per million tokens. A shared price.group_ratio does not change provider price ordering. |
throughput_range | [number, number] | No | — | Limits the real-time throughput range and excludes providers below or above it. Options / constraints: Unit: tokens/s. |
latency_range | [number, number] | No | — | Limits the real-time latency range using latency data collected by the platform. Options / constraints: Unit: seconds. |
input_length_range | [number, number] | No | — | Limits the range of maximum input lengths supported by providers. Options / constraints: Unit: tokens. |
ignore | string[] | No | — | Service provider blacklist, excluded from candidate channels. Options / constraints: Service provider names are case-sensitive. |
allow_fallbacks | boolean | No | — | Defaults to false when only is non-empty; otherwise defaults to true. Options / constraints: When true, only, range, sort, and order are relaxed; ignore, model access, endpoint capabilities, or channel availability are not relaxed. |
The platform normalizes text responses from different service providers into structures compatible with Chat Completions. provider is only an optional field that may appear in non-streaming JSON.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | No | — | Chat protocol response ID; its meaning follows the protocol and does not replace the gateway associated response header. |
object | string | No | — | Response object type, compatible with the Chat Completions structure. Options / constraints: Usually chat.completion. Streaming chunk types depend on the actual response. |
created | integer | No | — | Unix timestamp indicating when the system created the response. |
model | string | No | — | Model identifier from the protocol response. Options / constraints: It is not guaranteed to always represent the actual upstream model. |
choices | array | No | — | List of model-output candidates. Read message for non-streaming responses and delta for streaming responses. Options / constraints: choices[].message.content or choices[].delta.content. |
choices[].finish_reason | string | No | — | Reason generation ended. Options / constraints: stop, length, tool_calls, and other values depending on the model response. |
usage.prompt_tokens | integer | No | — | Number of tokens consumed by input messages. |
usage.completion_tokens | integer | No | — | Number of tokens consumed by model output. |
usage.total_tokens | integer | No | — | Total input and output tokens. |
provider | string | No | — | Information about the service provider channel that actually carries the request. Options / constraints: Possible only for non-streaming JSON; all SSE, text, or binary responses are not guaranteed to contain this field. |
choices[].message.reasoning_content | string | null | No | — | Thought process in non-streaming responses; only models that support Reasoning may be returned. Options / constraints: This field may be missing or null when it is not supported, not enabled, or when the model does not return a thought process. |
choices[].delta.reasoning_content | string | null | No | — | Streaming responses return reasoning increments in chunks; concatenate them in order. Options / constraints: The final answer is still read from choices[].delta.content. |
usage.completion_tokens_details.reasoning_tokens | integer | null | No | — | When the model returns usage details, it indicates the number of Tokens consumed in the thinking process. Options / constraints: Models or providers that do not support usage details may not return this field. |
The following fields are HTTP response headers, not Chat JSON or SSE chunk body fields.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
X-Client-Request-Id | string | No | — | When provided by the caller, the response echoes this value; if not provided, it is not automatically generated. |
X-Upstream-Request-Id | string | No | — | Usually used for gateway request tracing; it is not the provider's original request ID. |
Best for short text and requests that need the complete result at once. Read message.content from choices.
Set stream to true and return incremental chunks through SSE. Normal OpenAI Chat flow ends with data: [DONE] after the protocol termination event; usage may appear in an empty choices chunk. Aggregate increments according to choice and tool index, and handle errors in the stream; when the stream is interrupted abnormally, there is no guarantee that the termination event or data: [DONE] will be received.
Non-2xx responses use an OpenAI-compatible error object. HTTP 400 / invalid_request indicates parameter validation failure; HTTP 402 indicates insufficient available balance or quota; HTTP 429 indicates rate limiting. When hard candidate filters leave no channel, the gateway returns HTTP 503 / no_available_provider. Clients should check both the HTTP status and error.code.
{
"error": {
"message": "<HUMAN_READABLE_MESSAGE>",
"type": "<ERROR_TYPE>",
"param": null,
"code": "no_available_provider"
}
}The examples use the <MODEL_ID> placeholder. Replace it with the real model ID shown in Model Market or on the model details page.
curl https://api.tokensmarket.ai/v1/chat/completions \
-H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<MODEL_ID>",
"messages": [{
"role": "user",
"content": "Please introduce the unified API in one sentence."
}],
"stream": false
}'Use streaming to improve the frontend experience, while keeping routing controls in server-side configuration or controlled request parameters.
curl https://api.tokensmarket.ai/v1/chat/completions \
-H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<MODEL_ID>",
"messages": [{"role": "user", "content": "Hello"}],
"stream": true,
"extra_body": {
"provider": {
"sort": ["latency", "output_price"],
"allow_fallbacks": true
}
}
}'