Documentation

Unified Chat API

The Unified Chat API lets you interact with LLMs while automatically analyzing the emotional tone of both user and assistant messages.

Endpoint

POST/v1/chat/completions

Headers

x-api-key: YOUR_API_KEYContent-Type: application/json

Request Body

Field	Type	Required	Description
model	string	✔	Text generation model (e.g., gpt-4.1-nano)
emotion_model	string	✔	Emotion model to apply (e.g., emotion-v1)
context_id	string	✖	Session ID for emotional memory (≤128 bytes). If omitted, response is stateless.
messages	array	✔	Conversation history. Each object: {role: "user" \| "assistant", content: string}
model_params	object	✖	Pass-through parameters to the text model (temperature, max_tokens, etc.)
emotion_model_params	object	✖	Options for emotion analysis (thresholds, smoothing)
stream	boolean	✖	Stream results in chunks (default: false)
tools	array	✖	Tool definitions if using function/tool calling

Example Request

curl https://api.kaiko.ai/v1/chat/completions \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-nano",
    "emotion_model": "emotion-v1",
    "context_id": "chat-123",
    "messages": [
      {"role": "user", "content": "I'm nervous about my interview tomorrow."}
    ],
    "model_params": {"temperature": 0.7},
    "stream": false
  }'

Example Response

{
  "id": "chatcmpl-1757595153467",
  "object": "chat.completion",
  "created": 1757595153,
  "model": "gpt-4.1-nano",
  "emotion_model": "emotion-v1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "It's natural to feel nervous. Want me to share some quick interview tips?"
      },
      "finish_reason": "stop"
    }
  ],
  "emotions": {
    "user": {
      "category": "fear",
      "text": "Moderate FEAR",
      "raw": {
        "fear": 0.78,
        "joy": 0.11,
        "sadness": 0.06
      }
    },
    "assistant": {
      "category": "calm",
      "text": "Calm / Supportive",
      "raw": {
        "joy": 0.42,
        "love": 0.33,
        "fear": 0.05
      }
    }
  },
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 23,
    "analyse_tokens": 12
  }
}

Error Codes

Code	Meaning	When it happens
401	Unauthorized	Missing/invalid API key or auth header missing
404	Not Found	Wrong model name or expired context_id
413	Payload Too Large	Too many messages / oversized input
429	Rate Limited	Exceeded quota; retry with backoff
500	Server Error	Unexpected error; try again or contact support if persistent

Notes

• Use context_id for multi-turn conversations to maintain emotional state.
• Without context_id, emotions are evaluated per-call (stateless).
• Emotions are returned for both user and assistant messages.
• Token usage includes prompt_tokens, completion_tokens, and analyse_tokens.

Next: see Emotion APIs for standalone emotion analysis.