Chat completions guide
Build conversational AI with grounded chat completions.
Overview
Chat completions are the primary way to interact with the Unii API. You send a list of messages — system instructions, user questions, and assistant responses — and the API returns a generated message. When combined with a knowledge base, responses are grounded in your own documents.
Message structure
Every request includes a messages array. Each message has a role and content:
| Role | Description |
|---|---|
system | Sets the assistant's behavior and tone. Optional but recommended. |
user | The user's question or prompt. |
assistant | A previous assistant response (for multi-turn conversations). |
const messages = [{ role: "system", content: "You are a helpful technical support assistant.",},{ role: "user", content: "How do I reset my API key?",},];Single-turn request
The simplest request sends one user message and receives one response:
import { UniiClient } from "@unii/sdk";const client = new UniiClient({apiKey: process.env.UNII_API_KEY,});const response = await client.createChatCompletion({model: "unii-latest",messages: [{ role: "user", content: "What is retrieval-augmented generation?" },],});console.log(response.choices[0].message.content);Multi-turn conversation
Maintain conversation history by including previous messages:
const response = await client.createChatCompletion({model: "unii-latest",messages: [ { role: "system", content: "You are a helpful assistant.", }, { role: "user", content: "What is RAG?", }, { role: "assistant", content: "RAG (Retrieval-Augmented Generation) combines a knowledge base with an LLM to produce grounded responses.", }, { role: "user", content: "How does it differ from fine-tuning?", },],});Controlling output
Use temperature and max_tokens to shape the response:
- Temperature — Controls randomness. Lower values (e.g.,
0.1) produce focused, deterministic output. Higher values (e.g.,0.8) increase creativity. - Max tokens — Limits the maximum length of the response.
const response = await client.createChatCompletion({model: "unii-latest",messages: [ { role: "user", content: "Summarize the key benefits of RAG." },],temperature: 0.3,maxTokens: 256,});Tip
For factual, grounded responses, use a lower temperature (0.1–0.4). For creative or exploratory tasks, try 0.7 or higher.
Grounding with a knowledge base
Add a knowledgeBaseId to ground the response in your indexed documents:
const response = await client.createChatCompletion({model: "unii-latest",knowledgeBaseId: "kb_abc123",messages: [ { role: "user", content: "What is our refund policy?" },],});Next steps
- Enable streaming for real-time responses.
- Read the Chat completions API reference for the full parameter list.
- Learn about knowledge bases to ground responses.