📊 EmoVision API

🚀 Getting Started

Welcome to the EmoVision API! This API allows you to integrate advanced video honesty analysis, emotion detection, and body language insights into your applications.

Overview

EmoVision provides a RESTful API that enables developers to:

• Upload videos for AI-powered honesty and emotion analysis
• Retrieve detailed analysis results including emotion breakdowns, body language insights, and honesty scores
• Monitor API usage and costs in real-time
• Receive webhook notifications for analysis completion
• Integrate seamlessly with your existing HR, sales, therapy, or research platforms

Quick Start

1. Create an organization and generate an API key from your dashboard
2. Store your API key securely (it's only shown once)
3. Make authenticated requests using the Authorization: Bearer YOUR_API_KEY header
4. Upload videos for analysis and retrieve results
5. Set up webhooks to receive real-time notifications

🔐 Authentication

API Keys

All API requests require an API key. Include your API key in the Authorization header:

Authorization: Bearer ek_live_your_api_key_here

Generating API Keys

Generate API keys through the web interface at /api/keys/generate (requires admin or manager role):

curl -X POST https://your-domain.com/api/keys/generate \
  -H "Content-Type: application/json" \
  -H "Cookie: session_token=YOUR_SESSION_TOKEN" \
  -d '{
    "org_id": 1,
    "name": "Production API Key",
    "rate_limit_per_minute": 60
  }'

import requests

response = requests.post(
    'https://your-domain.com/api/keys/generate',
    headers={'Cookie': 'session_token=YOUR_SESSION_TOKEN'},
    json={
        'org_id': 1,
        'name': 'Production API Key',
        'rate_limit_per_minute': 60
    }
)

api_key = response.json()['api_key']
print(f"API Key: {api_key}")
# Save this securely - it won't be shown again!

const response = await fetch('https://your-domain.com/api/keys/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    org_id: 1,
    name: 'Production API Key',
    rate_limit_per_minute: 60
  })
});

const data = await response.json();
console.log('API Key:', data.api_key);
// Save this securely - it won't be shown again!

📡 API Endpoints

{
  "recording_id": "rec_a1b2c3d4e5f6",
  "duration_minutes": 5.25,
  "overall_honesty_score": 78.5,
  "emotion_breakdown": {
    "happy": 0.35,
    "neutral": 0.45,
    "surprised": 0.12,
    "sad": 0.08
  },
  "key_moments": [
    {
      "timestamp_ms": 45000,
      "type": "honesty_drop",
      "score": 0.45
    }
  ],
  "cost_usd": 1.31,
  "status": "completed"
}

curl -X POST https://your-domain.com/api/v1/analyze \
  -H "Authorization: Bearer ek_live_your_api_key" \
  -F "video=@interview.mp4" \
  -F 'metadata={"candidate": "John Doe", "position": "Senior Engineer"}'

import requests

api_key = "ek_live_your_api_key"

with open('interview.mp4', 'rb') as video_file:
    response = requests.post(
        'https://your-domain.com/api/v1/analyze',
        headers={'Authorization': f'Bearer {api_key}'},
        files={'video': video_file},
        data={'metadata': '{"candidate": "John Doe", "position": "Senior Engineer"}'}
    )

result = response.json()
print(f"Honesty Score: {result['overall_honesty_score']}%")
print(f"Recording ID: {result['recording_id']}")

const formData = new FormData();
formData.append('video', videoFile);
formData.append('metadata', JSON.stringify({
  candidate: 'John Doe',
  position: 'Senior Engineer'
}));

const response = await fetch('https://your-domain.com/api/v1/analyze', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ek_live_your_api_key'
  },
  body: formData
});

const result = await response.json();
console.log(`Honesty Score: ${result.overall_honesty_score}%`);

{
  "month": "2025-01",
  "total_analyses": 150,
  "total_minutes_analyzed": 487.5,
  "total_cost_usd": 121.88,
  "rate_limit": {
    "limit": 60,
    "remaining": 45,
    "reset": 1706745600
  }
}

📦 SDKs & Libraries

pip install emotionchat

from emotionchat import EmotionChat

client = EmotionChat(api_key="ek_live_your_api_key")
result = client.analyze("interview.mp4")
print(f"Score: {result.honesty_score}%")

npm install @emotionchat/sdk

import { EmotionChat } from '@emotionchat/sdk';

const client = new EmotionChat({ apiKey: 'ek_live_your_api_key' });
const result = await client.analyze('interview.mp4');
console.log(`Score: ${result.honestyScore}%`);

🔔 Webhooks

Set up webhooks to receive real-time notifications when analysis completes.

Webhook Events

Webhook Payload

{
  "event": "analysis.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "recording_id": "rec_a1b2c3d4e5f6",
    "overall_honesty_score": 78.5,
    "status": "completed",
    "cost_usd": 1.31
  }
}

Verifying Webhooks

All webhook payloads are signed with HMAC-SHA256. Verify the signature using the X-EmotionChat-Signature header:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your Flask endpoint:
@app.route('/webhooks/emotionchat', methods=['POST'])
def handle_webhook():
    payload = request.get_data(as_text=True)
    signature = request.headers.get('X-EmotionChat-Signature')
    
    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    
    # Process webhook event
    return 'OK', 200

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express endpoint:
app.post('/webhooks/emotionchat', (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-emotionchat-signature'];
  
  if (!verifyWebhook(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook event
  res.status(200).send('OK');
});

Retry Logic

Failed webhook deliveries are retried up to 3 times with exponential backoff:

• 1st retry: after 1 minute
• 2nd retry: after 5 minutes
• 3rd retry: after 15 minutes

⚡ Rate Limits

Rate Limit Headers

All API responses include rate limit headers to help you manage your usage:

Tier-Based Rate Limits

Rate Limit Exceeded

When you exceed your rate limit, the API returns a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "retry_after": 42
}

💰 Billing & Pricing

Usage-Based Pricing

Monitoring Usage

Use the /api/v1/usage endpoint to track your monthly consumption and costs in real-time.

❌ Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "Description of what went wrong",
  "code": "INVALID_VIDEO_FORMAT",
  "details": {
    "supported_formats": ["mp4", "avi", "mov", "webm"]
  }
}

Best Practices

• Always check the HTTP status code before parsing the response
• Implement exponential backoff for retries on 429 and 5xx errors
• Monitor rate limit headers to avoid hitting limits
• Use webhooks instead of polling for real-time updates
• Store API keys securely using environment variables or secret managers
• Log errors with request IDs for easier debugging

📝 API Changelog

Track the evolution of the EmotionChat API and stay updated with new features, improvements, and fixes.