Stac

Referência da API

Chat completions

Gere a resposta de um modelo a partir de uma lista de mensagens.

POST/v1/chat/completions

O endpoint principal. Recebe uma conversa e devolve a próxima mensagem do assistente, opcionalmente em streaming.

Corpo da requisição

modelstringObrigatório

O modelo que responde, por exemplo qwen/qwen3.5-9b. Veja em Modelos os valores que o seu plano inclui; o GET /v1/models lista os que a sua chave pode usar.

messagesMessage[]Obrigatório

A conversa até aqui, da mais antiga para a mais recente. Cada mensagem tem um role e um content.

streambooleanOpcionalPadrão: false

Devolve server-sent events em vez de um único corpo JSON. Veja Streaming.

temperaturenumberOpcionalPadrão: 0.7

Aleatoriedade da amostragem, de 0 a 2. Sobrepõe a configuração de comportamento da stack apenas nesta requisição.

top_pnumberOpcionalPadrão: 1

Amostragem por núcleo (nucleus sampling). Ajuste este parâmetro ou a temperature, não os dois.

max_tokensintegerOpcionalPadrão: 8000

Teto de tokens gerados. Fica limitado a um piso de 8000 e a um teto de 16000 — um valor baixo ou ausente nunca corta uma resposta no meio, e o piso conta contra a janela de contexto (veja Modelo de preços).

stopstring | string[]Opcional

Até quatro sequências que encerram a geração. A sequência em si não é devolvida.

toolsTool[]Opcional

Definições de funções que o modelo pode chamar. Mesmo schema das tools da OpenAI.

response_formatobjectOpcional

Defina como { "type": "json_object" } para restringir a saída a um JSON válido.

textjson_object
chat_template_kwargsobjectOpcional

Avançado, específico de cada família de modelos. Nos modelos Qwen3.x, envie { "enable_thinking": false } aqui para pular a etapa de raciocínio interno do modelo e responder direto — útil em tarefas fechadas e objetivas (classificação, extração), em que você prefere menor latência a profundidade de raciocínio. Precisa estar aninhado sob esta chave; um enable_thinking no nível de cima é ignorado em silêncio.

Objeto de mensagem

rolestringObrigatório

Quem produziu a mensagem.

systemuserassistanttool
contentstring | Part[]Opcional

Texto, ou um array de partes para entrada multimodal. Pode ser null numa mensagem do assistente que só chama uma tool.

tool_call_idstringOpcional

Obrigatório em mensagens tool — liga o resultado à chamada de origem.

Exemplo

curl "https://api.trystac.com/v1/chat/completions" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.5-9b",
    "messages": [{ "role": "user", "content": "Cite três cores primárias." }],
    "temperature": 0.2,
    "max_tokens": 64
  }'

Resposta

200 OKjson
{
  "id": "chatcmpl-9f2a1c",
  "object": "chat.completion",
  "created": 1770000000,
  "model": "qwen/qwen3.5-9b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Vermelho, azul e amarelo." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 7, "total_tokens": 21 }
}

finish_reason

ValorSignificado
stopO modelo terminou, ou encontrou uma sequência de parada
lengthAtingiu o max_tokens
tool_callsO modelo precisa do resultado de uma tool antes de continuar