Documentation

Quickstart

Welcome to the Kaiko API V2! This guide will get you making your first requests in minutes with the new 6 EQ dimensions, trajectory tracking, and advanced features.

1. Get an API Key

All requests must include:

x-api-key: YOUR_API_KEY

Key format: kaiko_live_xxxxxxxxxxxxx (production) or kaiko_test_xxxxxxxxxxxxx (staging)

2. Base URL

V2 endpoints are prefixed with:

https://api.kaikostudios.xyz/v2(Production)

https://stg.api.kaikostudios.xyz/v2(Staging)

3. Make Your First Calls

Example 1: Stateless Emotion Analysis (V2)

Use the V2 Analysis API to analyze a single message with 6 EQ dimensions.

curl -X POST https://api.kaikostudios.xyz/v2/emotions/analysis \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "emotion-v2",
    "messages": [{
      "role": "user",
      "content": {"text": "I feel a bit unsure about this"}
    }]
  }'

Response with V2 EQ Dimensions:

{
  "object": "emotions.analysis",
  "model": "emotion-v2",
  "emotions": {
    "user": {
      "text": "I feel a bit unsure about this",
      "category": "fear",
      "intensity": 0.52,
      "intensityLevel": "subtle",
      "valence": -0.35,
      "arousal": 0.45,
      "complexity": "simple",
      "wonderIndex": 0.20,
      "discoveryLevel": "normal",
      "raw": {
        "fear": 0.52,
        "sadness": 0.21,
        "joy": 0.09,
        "anger": 0.08,
        "love": 0.05,
        "surprise": 0.05
      }
    }
  }
}

V2 Features: Note the new fields: intensity, intensityLevel, valence, arousal, complexity, wonderIndex, and discoveryLevel.

Example 2: Context-Based Analysis with Trajectory

For agents that need memory and trajectory tracking across a session:

curl -X POST https://api.kaikostudios.xyz/v2/emotions/user-session-123/analysis \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "emotion-v2",
    "messages": [{
      "role": "user",
      "externalId": "msg-1",
      "content": {"text": "This is amazing! I never expected such great results!"},
      "timestamp": "2025-01-15T10:30:00Z"
    }]
  }'

Response with trajectory insights:

{
  "object": "emotions.analysis",
  "model": "emotion-v2",
  "emotions": {
    "user": {
      "category": "joy",
      "intensity": 0.88,
      "intensityLevel": "high",
      "valence": 0.82,
      "arousal": 0.85,
      "complexity": "layered",
      "wonderIndex": 0.65,
      "discoveryLevel": "breakthrough"
    }
  },
  "trajectory": {
    "trend": {
      "direction": "improving",
      "valenceTrend": 0.12
    }
  }
}

Retrieve the stored state later:

curl https://api.kaikostudios.xyz/v2/emotions/user-session-123 \
  -H "x-api-key: $KAIKO_API_KEY"

Example 3: Unified Chat + Emotion (V2)

Talk to an LLM and get V2 emotion inference with conversation mode detection:

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": "user-session-alpha-789",
    "messages": [
      {"role": "system", "content": "You are a helpful and empathetic assistant."},
      {"role": "user", "content": "I am stressed about my deadline tomorrow."}
    ],
    "model_params": {
      "temperature": 0.7,
      "max_tokens": 500
    }
  }'

Response with emotions and conversation mode:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4",
  "emotion_model": "emotion-v2",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "I understand how stressful deadlines can be. Let me help you break this down..."
    },
    "finish_reason": "stop"
  }],
  "emotions": {
    "user": {
      "category": "fear",
      "intensity": 0.72,
      "intensityLevel": "moderate",
      "valence": -0.55,
      "arousal": 0.68,
      "complexity": "layered",
      "wonderIndex": 0.15,
      "discoveryLevel": "normal"
    },
    "assistant": {
      "category": "love",
      "intensity": 0.65,
      "valence": 0.70,
      "arousal": 0.45
    }
  },
  "conversationMode": {
    "mode": "emotional_support",
    "confidence": 0.85,
    "responseStrategy": {
      "tone": "empathetic",
      "approach": "validation_first"
    }
  }
}

V2 Conversation Mode: The API automatically detects the appropriate conversation mode (emotional_support, crisis_intervention, analytical_deep_dive, etc.) and provides response strategy guidance.

Example 4: Batch Analysis for Sentiment Pipelines

Analyze multiple texts in a single request for high-throughput use cases:

curl -X POST https://api.kaikostudios.xyz/v2/emotions/batch-analysis \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "emotion-v2",
    "messages": [
      {"content": {"text": "I love this product!"}},
      {"content": {"text": "This is frustrating and annoying."}},
      {"content": {"text": "I am worried about the quality."}}
    ]
  }'

Perfect for social media monitoring, customer feedback analysis, and content moderation.

V2 EQ Dimensions Reference

Dimension	Range	Description
intensity	0.0-1.0	Overall strength of dominant emotion
valence	-1.0 to +1.0	Emotional tone (negative to positive)
arousal	0.0-1.0	Energy level (calm to excited)
complexity	enum	simple, layered, paradoxical, transcendent
wonderIndex	0.0-1.0	Curiosity and openness to discovery
discoveryLevel	enum	routine, normal, significant, breakthrough, transcendent

You're ready to build with Kaiko V2! See Unified Chat API for full schema details or V2 EQ Dimensions for deeper understanding.