Documentation

Unified Chat API

V2

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

Endpoint
POST/v2/chat/completions

Headers

x-api-key: YOUR_API_KEYContent-Type: application/json
Request Body
FieldTypeRequiredDescription
modelstringYesLLM model (gpt-4, gpt-4-turbo, gpt-3.5-turbo, claude-3-*, xai-grok)
emotion_modelstringYesEmotion model: emotion-v2 (recommended) or emotion-v1
context_idstringNoSession ID for emotional memory and trajectory tracking (max 128 bytes). Enables V2 advanced features.
messagesarrayYesConversation history. Each: {role: "system"|"user"|"assistant", content: string}
model_paramsobjectNoLLM parameters (temperature, max_tokens, top_p, frequency_penalty, presence_penalty)
emotion_model_paramsobjectNoV2 emotion options (sensitivity, includeSubEmotions)
streambooleanNoStream results in chunks (default: false)
toolsarrayNoTool definitions for function calling
Example Request
curl -X POST https://api.kaikostudios.xyz/v2/chat/completions \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "emotion_model": "emotion-v2",
    "context_id": "chat-123",
    "messages": [
      {"role": "system", "content": "You are a helpful and empathetic assistant."},
      {"role": "user", "content": "I am nervous about my interview tomorrow."}
    ],
    "model_params": {
      "temperature": 0.7,
      "max_tokens": 500
    },
    "stream": false
  }'
Example Response (V2)
{
  "id": "chatcmpl-abc123def456",
  "object": "chat.completion",
  "created": 1757595153,
  "model": "gpt-4",
  "emotion_model": "emotion-v2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "It's completely natural to feel nervous before an interview. Let me share some tips to help you feel more prepared..."
      },
      "finish_reason": "stop"
    }
  ],
  "emotions": {
    "user": {
      "category": "fear",
      "text": "I am nervous about my interview tomorrow.",
      "intensity": 0.72,
      "intensityLevel": "moderate",
      "valence": -0.45,
      "arousal": 0.65,
      "complexity": "simple",
      "wonderIndex": 0.20,
      "discoveryLevel": "normal",
      "raw": {
        "fear": 0.72,
        "sadness": 0.15,
        "joy": 0.05,
        "anger": 0.03,
        "love": 0.02,
        "surprise": 0.03
      }
    },
    "assistant": {
      "category": "love",
      "intensity": 0.68,
      "valence": 0.72,
      "arousal": 0.45,
      "raw": {
        "love": 0.68,
        "joy": 0.45,
        "fear": 0.02,
        "sadness": 0.01,
        "anger": 0.01,
        "surprise": 0.03
      }
    }
  },
  "conversationMode": {
    "mode": "emotional_support",
    "confidence": 0.88,
    "responseStrategy": {
      "tone": "empathetic",
      "approach": "validation_first"
    }
  },
  "usage": {
    "prompt_tokens": 85,
    "completion_tokens": 120,
    "analyse_tokens": 25
  }
}
V2 Response Fields
FieldDescription
emotions.*.intensityStrength of dominant emotion (0.0-1.0)
emotions.*.intensityLevelcritical, high, moderate, subtle, minimal
emotions.*.valenceEmotional tone (-1.0 to +1.0)
emotions.*.arousalEnergy level (0.0-1.0)
emotions.*.complexitysimple, layered, paradoxical, transcendent
emotions.*.wonderIndexCuriosity level (0.0-1.0)
emotions.*.discoveryLevelroutine, normal, significant, breakthrough, transcendent
conversationMode.modeDetected mode (emotional_support, crisis_intervention, etc.)
conversationMode.responseStrategySuggested tone and approach for response
Supported LLM Models
ProviderModels
OpenAIgpt-4, gpt-4-turbo, gpt-3.5-turbo, gpt-4o-mini
Anthropicclaude-3-opus, claude-3-sonnet, claude-3-haiku
XAIxai-grok
Error Codes
CodeMeaningWhen it happens
400Bad RequestInvalid request body or missing required fields
401UnauthorizedMissing/invalid API key
404Not FoundInvalid model name or expired context_id
413Payload Too LargeToo many messages or oversized input
429Rate LimitedExceeded quota; retry with backoff
500Server ErrorUnexpected error; contact support if persistent
Notes
  • Use context_id for multi-turn conversations to enable trajectory tracking and emotional memory.
  • Without context_id, emotions are evaluated per-call (stateless) but still include V2 EQ dimensions.
  • V2 emotions include intensity, valence, arousal, complexity, wonderIndex, and discoveryLevel.
  • conversationMode provides automatic response strategy recommendations.
  • Token usage includes prompt_tokens, completion_tokens, and analyse_tokens.

Next: see Emotion APIs for standalone V2 emotion analysis, or V2 EQ Dimensions for detailed explanations of each dimension.