Developers / Docs / API reference / Chat completions

Chat completions

POST /api/v1/chat/completions: generate a reply to a conversation, streamed or in one piece, with tools, reasoning, JSON output and images. For examples and explanations, see the Chat completions guide.

Create chat completion

POST /api/v1/chat/completions

Generates the model's next message for a conversation. Supports streaming, reasoning, tool calls, JSON output, image input and stateful sessions. Unknown top-level fields are rejected with 400 unknown_parameter.

Request body

modelstringrequired

The model id, for example arklabsai/Qwen3.6-35B-A3B. Use a causal_lm or multimodal model from List models.

messagesarrayrequired

The conversation so far, oldest first. At least one message.

rolestringrequired
system, developer (treated as system), user, assistant or tool.
contentstring or arrayoptional

Text, or an array of parts: {"type": "text", "text": …} and {"type": "image_url", "image_url": {"url": …}} with an https or base64 data: URL (vision models only).

namestringoptional

A speaker label passed to the model with the message.

tool_callsarrayoptional

On assistant messages: the tool calls the model made earlier.

max_tokensintegeroptional

Maximum tokens to generate, reasoning included. Defaults to the model's default (2,048 on ARK Cloud models). Must not exceed the model's context.

max_completion_tokensintegeroptional

Synonym of max_tokens; wins if both are set.

temperaturenumber, 0–2optional

Sampling temperature. Default 0.6.

top_pnumber, 0–1optional

Nucleus sampling.

stopstring or arrayoptional

Up to 4 stop strings. The output ends just before the first match. Not allowed with ark_stateful.

nintegeroptional

Must be 1.

streambooleanoptional

Stream the answer as server-sent events of chunks.

stream_optionsobjectoptional
include_usagebooleanoptional

Send a final chunk with the usage before [DONE].

continuous_usage_statsbooleanoptional

With include_usage: running token counts on every content chunk (not billed separately).

reasoning_effortstringoptional
none, minimal, low (default; no thinking), medium, high, xhigh or max. Also accepted as reasoning: {"effort": …}. See Reasoning.
toolsarrayoptional

Functions the model may call: {"type": "function", "function": {"name", "description", "parameters"}}, or custom tools {"type": "custom", "custom": {…}}.

tool_choicestring or objectoptional
"none", "auto", "required", {"type": "function", "function": {"name": …}} or {"type": "allowed_tools", …}.
parallel_tool_callsbooleanoptional
false returns at most one tool call.
response_formatobjectoptional
{"type": "text"}, {"type": "json_object"} or {"type": "json_schema", "json_schema": {"name", "schema", …}}. JSON is requested from the model, not enforced by decoding. See JSON output.
functions, function_calloptional

Legacy function calling, used when tools is absent.

ark_statefulstringARK extension

A session id. Keeps the conversation on the server; send only new messages. See Stateful sessions.

ark_max_session_tokensintegerARK extension

Required with ark_stateful: the most tokens the whole session may hold.

seed, presence_penalty, frequency_penalty, logit_bias, logprobs, top_logprobs, user, metadata, store, service_tier, prompt_cache_key, safety_identifieraccepted, no effect

Validated for compatibility and otherwise ignored.

Returns a chat completion object, or a stream of chunks.

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.6-35B-A3B",
    "messages": [
      {"role": "system", "content": "Answer in one sentence."},
      {"role": "user", "content": "What is a GPU?"}
    ],
    "max_tokens": 200
  }'
Response
{
  "id": "chatcmpl-0d1f…",
  "object": "chat.completion",
  "created": 1792345678,
  "model": "arklabsai/Qwen3.6-35B-A3B",
  "service_tier": "default",
  "system_fingerprint": null,
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "A GPU is a processor built to run many calculations in parallel.",
      "refusal": null,
      "annotations": []
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 14,
    "total_tokens": 40,
    "prompt_tokens_details": {"cached_tokens": 0, "audio_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0, "audio_tokens": 0,
      "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0},
    "credits_used": 7,
    "credit_balance": 4999993
  }
}

The chat completion object

idstring
chatcmpl- followed by a unique id.
objectstring
chat.completion.
createdinteger

Unix time of the response.

modelstring

The model that answered.

choicesarray

One choice.

message.contentstring

The answer text. Absent when the answer is only tool calls.

message.reasoningstring

The model's thinking, when reasoning was on.

message.tool_callsarray
{"id", "index", "type": "function", "function": {"name", "arguments"}}, where arguments is a JSON string.
finish_reasonstring
stop, length, tool_calls, function_call or inference_timeout.
usageobject
prompt_tokens, completion_tokens, total_tokensinteger

Completion tokens include reasoning tokens.

prompt_tokens_details.cached_tokensinteger

Prompt tokens served from ARK's prefix cache.

completion_tokens_details.reasoning_tokensinteger

Tokens spent thinking.

credits_used, credit_balanceintegerARK extension

On ARK Cloud: what the request cost, and the balance left.

service_tier, system_fingerprint

Always "default" and null.

Tool call
{
  "index": 0,
  "message": {
    "role": "assistant",
    "tool_calls": [{
      "id": "call_6f0f2c8d0b3c4f6a9d1e2b7c5a8e4f10",
      "index": 0,
      "type": "function",
      "function": {
        "name": "get_exchange_rate",
        "arguments": "{\"base\": \"EUR\", \"quote\": \"PLN\"}"
      }
    }],
    "refusal": null,
    "annotations": []
  },
  "finish_reason": "tool_calls"
}

The chat completion chunk

With stream: true, each event is a data: line holding one chunk; the stream ends with data: [DONE]. The first chunk arrives with the first generated token.

objectstring
chat.completion.chunk.
choices[].deltaobject
role, and new content, reasoning or complete tool_calls.
choices[].finish_reasonstring or null
null until the last content chunk.
usageobject or null

With include_usage: null on every chunk except a final chunk with empty choices and the full usage.

An error after the stream has started arrives as one data: {"error": {…}} event, and the stream ends without [DONE].

Stream
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1792345678,"model":"arklabsai/Qwen3.6-35B-A3B","service_tier":"default","system_fingerprint":null,"choices":[{"index":0,"delta":{"role":"assistant","content":"A"},"finish_reason":null}],"usage":null}

data: {…"choices":[{"index":0,"delta":{"role":"assistant","content":" GPU"},"finish_reason":null}],"usage":null}

data: {…"choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":"stop"}],"usage":null}

data: {…"choices":[],"usage":{"prompt_tokens":26,"completion_tokens":14,"total_tokens":40,…}}

data: [DONE]