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. |
| 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 | — | Conversation messages in order. Each message must contain at least role and content. Options / constraints: role: system, user, assistant. |
messages[].content | string | array | Yes | — | Message content. Use a string for plain text. Multimodal models can accept an array of content items formatted according to the model requirements. Options / constraints: Content-item type: text, image_url, or video_url. |
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: Use when type=image_url. Field: url. |
messages[].content[].video_url | object | No | — | Video resource object containing an accessible video URL. Options / constraints: Use when type=video_url. Field: url. |
max_completion_tokens | integer | No | — | Limits the maximum number of tokens the model can generate. Reasoning models may interpret it as the maximum reasoning length. Options / constraints: Use this or max_tokens, depending on model support. |
max_tokens | integer | No | — | Maximum number of generated tokens for compatibility with older models. Options / constraints: Some models use max_completion_tokens. Check the model details page. |
temperature | float | No | — | Controls output randomness. Higher values generally produce more varied output. Options / constraints: Range: 0.0–2.0; usually adjust either this parameter or top_p. |
top_p | float | No | — | Nucleus-sampling parameter that controls the candidate token set whose cumulative probability reaches top_p. Options / constraints: Range: 0.0–1.0; usually adjust either this parameter or temperature. |
top_k | integer | No | — | Limits the number of candidate tokens retained at each sampling step. Options / constraints: Must be greater than 0; the OpenAI Python SDK does not directly support this parameter. |
presence_penalty | float | No | — | Reduces the probability of repeated topics by penalizing content that has already appeared. Options / constraints: Range: -2.0–2.0; support depends on the model. |
stream | boolean | No | false | Whether to return incremental content through SSE. When enabled, the client must process each chunk and handle disconnections and retries. Options / constraints: true / false. |
stream_options | object | No | — | Additional options for streaming responses. Options / constraints: include_usage: boolean; defaults to true. |
modalities | string | No | text | Expected output type. Text is the default. Options / constraints: Currently supports text. Check the model details page for specific capabilities. |
response_format | object | No | — | Constrains the model response format. Options / constraints: type: text or json_object. Only some models support structured output. |
tools | array | No | — | Declares tools the model may select. Your application server must execute tool calls and return the results. Options / constraints: Use the Chat Completions tool format supported by the current model. |
extra_body | object | No | — | Extension field for the unified API, used for provider routing and platform-policy controls. Options / constraints: provider, enable_thinking, timeout. |
extra_body.enable_thinking | boolean | No | — | Enables or disables reasoning. Only some reasoning models support this option. Options / constraints: true or false. Actual behavior depends on the model. |
extra_body.timeout | integer | No | — | Adjusts the timeout for waiting for the first token. Options / constraints: Unit: seconds. |
Without provider, the platform uses its default policy. Pass extra_body.provider only 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 | — | Preferred provider order. When routing policies rank providers equally, array order takes precedence. Options / constraints: Provider names are case-sensitive. |
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 | — | Limits the input-price range and retains providers whose input price falls within it. Options / constraints: Unit: ¥ per 1M tokens. Example: [1, 2]. |
output_price_range | [number, number] | No | — | Limits the output-price range and retains providers whose output price falls within it. Options / constraints: Unit: ¥ per 1M tokens. |
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. |
allow_filter_prompt_length | boolean | No | true | Whether to automatically filter providers by the prompt length for this request so it does not exceed channel capabilities. Options / constraints: true / false. |
ignore | string[] | No | — | Provider denylist. Excludes the specified providers from candidate channels. Options / constraints: Provider names are case-sensitive. |
allow_fallbacks | boolean | No | true | Whether to fall back to other available channels according to the sort policy when no filter matches. Options / constraints: true or false. Keep fallback enabled when filters are narrow. |
The platform normalizes text responses from different providers into a Chat Completions-compatible structure and includes information about the provider that served the request.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | No | — | Unique ID for this response, used to correlate logs, troubleshoot issues, and track retries. |
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 | — | ID of the model that actually processed the request. |
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 provider channel that served the request, useful for observing routing results. |
choices[].message.reasoning_content | string | null | No | — | Reasoning trace in a non-streaming response. Only reasoning-capable models may return it. Options / constraints: Models may omit this field or return null when they do not support reasoning, the request disables reasoning, or they produce no reasoning trace. |
choices[].delta.reasoning_content | string | null | No | — | Incremental reasoning trace in a streaming response chunk. Concatenate it separately in chunk order. Options / constraints: Continue reading the final answer from choices[].delta.content. |
usage.completion_tokens_details.reasoning_tokens | integer | null | No | — | When the model includes usage details, this field reports the number of tokens consumed by reasoning. Options / constraints: Models or providers that do not support detailed usage may omit this field. |
Best for short text and requests that need the complete result at once. Read message.content from choices.
When stream is true, the API returns incremental chunks through SSE. The client should handle disconnections, empty choices, and a limited number of retries.
Non-2xx responses use an OpenAI-compatible error object. Clients should check both the HTTP status and error.code and must not depend on message text, which may change. The example below shows the error shape when hard routing constraints leave no candidate provider.
{
"error": {
"message": "<HUMAN_READABLE_MESSAGE>",
"type": "<ERROR_TYPE>",
"param": null,
"code": "no_available_provider"
}
}The examples below use the <MODEL_ID> placeholder. Replace it with a real model ID from the Model Market or a 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
}
}
}'