Chat API
Generate conversations with the OpenAI-compatible protocol, including standard responses, streaming, and tool calls.
The Chat API generates a model response from an ordered list of messages. Requests follow the OpenAI Chat Completions protocol and support standard JSON responses; SSE streaming and tool calls are available when the target model supports them.
Endpoint
POST /v1/chat/completionsThe following compatible entry points use the same request structure:
POST /v2/chat/completionsPOST /api/v3/chat/completions
Authentication
Authorization: Bearer <APIQIK_API_KEY>
Content-Type: application/jsonDo not expose API keys in browser code, mobile applications, or public repositories.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model identifier. Use the model catalog or the value returned by GET /v1/models. |
messages | array | Yes | Messages ordered by conversation sequence. |
temperature | number | No | Controls output randomness. The gateway accepts values from 0 to 2; the effect depends on the model. |
max_tokens | integer | No | Limits output tokens for the request. Must be an integer from 1 to 1000000. |
stream | boolean | No | Set to true to receive SSE delta events. |
stop | string or array | No | Stops generation when a stop sequence is matched. Support depends on the model. |
tools | array | No | Tool definitions that the model can call. |
tool_choice | string or object | No | Controls whether and how the model selects a tool. |
response_format | object | No | Requests JSON or another structured output format when supported by the target model. |
user | string | No | Identifier for the end user. |
Message structure
{
"role": "user",
"content": "Explain API intelligent routing."
}Common role values are system, user, assistant, and tool. content can be text; multimodal content and tool fields require target-model support. A tool result message must use tool_call_id to reference the corresponding tool call.
Request example
curl "${BASE_URL}/v1/chat/completions" \
-H "Authorization: Bearer ${APIQIK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-turbo",
"messages": [
{"role": "system", "content": "You are a concise and reliable assistant."},
{"role": "user", "content": "Explain API intelligent routing."}
],
"temperature": 0.7,
"max_tokens": 512
}'Standard response
{
"id": "chatcmpl-apiqik-example",
"object": "chat.completion",
"created": 1789987200,
"model": "qwen-turbo",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "API intelligent routing selects an inference path based on model capabilities and channel health."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 27,
"total_tokens": 51
}
}Clients usually read choices[0].message.content. finish_reason can be stop, length, or tool_calls; usage records input, output, and total token consumption.
Streaming response
Set "stream": true in the request to receive text/event-stream. Clients must parse SSE events rather than treating TCP packet boundaries as JSON boundaries.
data: {"id":"chatcmpl-apiqik-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"API"}}]}
data: [DONE]Incremental text is in choices[].delta.content. After receiving data: [DONE] or the connection closing, clients should combine the complete text. A streaming response can include usage information in its final event.
Tool calls
When the model returns finish_reason: "tool_calls", the application should execute the functions declared in tool_calls and append their results as role: "tool" messages in the next request. Tool definitions and arguments must use JSON Schema supported by the target model.
Error handling
400: Invalid request body, missingmodelormessages, or a parameter outside the gateway's accepted range.401: Missing or invalid API key.403: The API key is not authorized to call the model or capability.429: Request rate or account quota is limited.500,502, or503: Gateway or upstream model service failure.
Clients should handle failures using the HTTP status code and structured error fields, and retain X-Request-Id from the response for troubleshooting.