Developers / Docs / Chat completions

Chat completions

POST /api/v1/chat/completions turns a list of messages into the model's next message. It is the endpoint behind chat, reasoning, tool calls and image understanding.

API reference: Chat completions

POST https://api.ark-labs.cloud/api/v1/chat/completions

A basic request

from openai import OpenAI
import os

client = OpenAI(base_url="https://api.ark-labs.cloud/api/v1", api_key=os.environ["ARK_API_KEY"])

response = client.chat.completions.create(
    model="arklabsai/Qwen3.5-122B-A10B",
    messages=[
        {"role": "system", "content": "You are a precise assistant for a Polish bank."},
        {"role": "user", "content": "List three duties DORA puts on financial entities."},
    ],
    max_tokens=400,
    temperature=0.3,
)
print(response.choices[0].message.content)

const response = await client.chat.completions.create({
  model: "arklabsai/Qwen3.5-122B-A10B",
  messages: [
    { role: "system", content: "You are a precise assistant for a Polish bank." },
    { role: "user", content: "List three duties DORA puts on financial entities." },
  ],
  max_tokens: 400,
  temperature: 0.3,
});
console.log(response.choices[0].message.content);

curl https://api.ark-labs.cloud/api/v1/chat/completions \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "arklabsai/Qwen3.5-122B-A10B",
    "messages": [
      {"role": "system", "content": "You are a precise assistant for a Polish bank."},
      {"role": "user", "content": "List three duties DORA puts on financial entities."}
    ],
    "max_tokens": 400,
    "temperature": 0.3
  }'

Messages and roles

A conversation is an array of messages, oldest first. Each has a role and content.

Role	Use it for
`system`	Instructions that frame the whole conversation. Qwen models get "You are a helpful assistant." when you send none; it counts toward the prompt.
`developer`	Accepted and treated as `system`.
`user`	What the user says. Content can be a string or an array of `text` and `image_url` parts (Vision).
`assistant`	Earlier model replies, including their `tool_calls`.
`tool`	The result of a tool the model called (Tool calling).

A message's optional name is passed to the model as a speaker label, which helps in multi-party chats.

Generation parameters

max_tokensintegeroptional

The most tokens the model may generate, reasoning included. Defaults to the model's default (2,048 on ARK Cloud models). It must fit the model's context together with the prompt; see Limits. max_completion_tokens is accepted as a synonym and wins if both are set.

temperaturenumber 0–2optional

Sampling temperature. Defaults to 0.6. Lower is more deterministic; 0 is close to greedy.

top_pnumber 0–1optional

Nucleus sampling: sample only from the smallest set of tokens whose probability adds up to top_p.

stopstring or arrayoptional

Up to 4 strings. Generation stops when one appears; the returned text ends just before it and finish_reason is stop.

nintegeroptional

Must be 1. ARK returns one choice per request.

reasoning_effortstringoptional

low (the default: no thinking), medium or high. See Reasoning.

response_formatobjectoptional

{"type": "json_object"} or {"type": "json_schema", …} asks for JSON. See JSON output.

tools, tool_choice, parallel_tool_callsoptional

Let the model call your functions. See Tool calling.

stream, stream_optionsoptional

Receive the answer as server-sent events. See Streaming.

Accepted for compatibility, without effect

seed, presence_penalty, frequency_penalty, logit_bias, logprobs, top_logprobs, user, metadata, store and service_tier are validated and then ignored, so clients that always send them keep working. Any parameter ARK does not know is rejected with 400 unknown_parameter.

The response

The answer is in choices[0].message:

content: the text of the reply (an empty string if there is none; the key is absent when the reply is only tool calls).
reasoning: the model's thinking, present when reasoning was on and produced text.
tool_calls: the functions the model wants called, if any.

Finish reasons

`finish_reason`	Why generation ended
`stop`	The model finished, or a stop string was reached.
`length`	`max_tokens` was reached. The answer may be cut short.
`tool_calls`	The model asked for one or more tool calls.
`inference_timeout`	ARK-specific: generation ran into the server-side time limit; you receive what was generated so far.

Usage

usage reports prompt_tokens, completion_tokens (including reasoning tokens) and their sum. prompt_tokens_details.cached_tokens counts prompt tokens served from ARK's prefix cache, and completion_tokens_details.reasoning_tokens the tokens spent thinking. On ARK Cloud, credits_used and credit_balance show what the request cost. See Usage and billing.

Multi-turn conversations

To continue a conversation, send the earlier messages again, followed by the new one.

Python

history = [{"role": "user", "content": "Name a city on the Oder."}]
first = client.chat.completions.create(model="arklabsai/Qwen3.6-35B-A3B", messages=history)
history.append({"role": "assistant", "content": first.choices[0].message.content})
history.append({"role": "user", "content": "How far is it from the Baltic?"})
second = client.chat.completions.create(model="arklabsai/Qwen3.6-35B-A3B", messages=history)