API Reference

Chat completions

Generate a model response from a list of messages.

POST/v1/chat/completions

The primary endpoint. Accepts a conversation and returns the next assistant message, optionally streamed.

Request body

modelstringRequired

Model configured on the stack. GET /v1/models lists valid values.

messagesMessage[]Required

The conversation so far, oldest first. Each message has a role and content.

streambooleanOptionalDefault: false

Return server-sent events instead of a single JSON body. See Streaming.

temperaturenumberOptionalDefault: 0.7

Sampling randomness, 0–2. Overrides the stack's behavior setting for this request only.

top_pnumberOptionalDefault: 1

Nucleus sampling. Prefer adjusting this or temperature, not both.

max_tokensintegerOptionalDefault: 8000

Cap on generated tokens. Clamped to a floor of 8000 and a ceiling of 16000 — a low or missing value never truncates a response mid-answer, and the floor counts against the context window (see Pricing model).

stopstring | string[]Optional

Up to four sequences that end generation. The sequence itself is not returned.

toolsTool[]Optional

Function definitions the model may call. Same schema as OpenAI tools.

response_formatobjectOptional

Set to { "type": "json_object" } to constrain output to valid JSON.

textjson_object
chat_template_kwargsobjectOptional

Advanced, model-family-specific. On Qwen3.x models, pass { "enable_thinking": false } here to skip the model's internal reasoning step and answer directly — useful for closed, objective tasks (classification, extraction) where you want lower latency over reasoning depth. It must be nested under this key; a top-level enable_thinking is silently ignored.

Message object

rolestringRequired

Who produced the message.

systemuserassistanttool
contentstring | Part[]Optional

Text, or an array of parts for multimodal input. May be null on an assistant message that only calls a tool.

tool_call_idstringOptional

Required on tool messages — links the result back to the call.

Example

curl "https://api.trystac.com/v1/chat/completions" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-stack-model",
    "messages": [{ "role": "user", "content": "Name three primary colors." }],
    "temperature": 0.2,
    "max_tokens": 64
  }'

Response

200 OKjson
{
  "id": "chatcmpl-9f2a1c",
  "object": "chat.completion",
  "created": 1770000000,
  "model": "your-stack-model",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Red, blue, and yellow." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 7, "total_tokens": 21 }
}

finish_reason

ValueMeaning
stopModel finished, or hit a stop sequence
lengthHit max_tokens
tool_callsModel wants a tool result before continuing