Documentation

Guides & Recipes

This section provides hands-on examples of how to use Kaiko's APIs in common scenarios. Copy and adapt these recipes to jumpstart your own projects.

1. Build an Empathetic Chatbot

Goal: A chatbot that not only replies but also adjusts tone based on user emotion.

Steps

  1. Create a context_id for the conversation.
  2. Send user messages via Unified Chat API.
  3. Inspect the emotions.user.category to detect tone.
  4. Adapt assistant replies (e.g., calm if user shows anger, encouraging if sadness).
Request Examplebash
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-42",
    "messages": [{"role": "user", "content": "I'm so frustrated right now"}]
  }'

Response snippet:

"emotions": {
  "user": {"category": "anger"}
}

→ Your agent can now choose a calm, supportive response.

2. Add Emotion Analytics to Your App

Goal: Track trends in user mood over time.

Steps

  1. Use Context Emotion API with a unique context_id per user/session.
  2. Call .../analyse for each incoming message.
  3. Periodically call .../emotions/:context_id to retrieve the latest state.
  4. Store results in your analytics pipeline.
Retrieve State Examplebash
curl https://api.kaiko.ai/v1/emotions/user-789 \
  -H "x-api-key: $KAIKO_API_KEY"

→ Use this to chart mood trends across conversations.

3. Moderate Escalating Conversations

Goal: Route conversations to a human if user frustration spikes.

Steps

  1. Use Unified Chat API with emotion_model.
  2. Check emotions.user.raw.anger.
  3. If score > 0.7 for multiple turns, trigger escalation.
Pseudocodepython
if emotions["user"]["raw"]["anger"] > 0.7:
    escalate_to_human()
4. Personalize Learning Experiences

Goal: Tutor agent that adapts feedback style based on learner mood.

Steps

  1. Assign each learner a context_id.
  2. Analyze each response using Context Emotion API.
  3. If learner shows fear/sadness → reply with encouragement.
  4. If learner shows joy → increase challenge level.

→ Creates a more engaging and responsive learning flow.

5. Lightweight Sentiment Processing

Goal: Quickly process text streams without storing state.

Steps

  1. Use Non-Context Emotion API for stateless analysis.
  2. Pass in each message as a single request.
  3. Store only the category and raw scores in your database.
Stateless Analysisbash
curl https://api.kaiko.ai/v1/emotions/analyse \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "emotion-v1",
    "messages": [{"content": {"text": "Not sure how I feel"}}]
  }'

→ Best for pipelines or analytics where context is managed externally.

6. Marketing Insights

Goal: Measure emotional resonance of campaign responses.

Steps

  1. Collect user feedback (tweets, comments, survey responses).
  2. Send each through Non-Context Emotion API.
  3. Aggregate results (e.g., % joy vs % anger).
  4. Use insights to A/B test campaigns.

→ Identify which content drives the strongest positive reactions.

7. Custom Alerts

Goal: Notify a support team when a customer shows high distress.

Steps

  1. Use Context Emotion API per support session.
  2. On each message, check emotions.user.category.
  3. If sadness or fear > threshold, send a Slack/email alert.

→ Enables proactive intervention.

8. Next Steps