How do I get access to the EchoDepth API?

Request sandbox credentials via the contact form at echodepthfintec. Sandbox access is issued within one business day. Professional and Enterprise plans are available from £999/month + VAT.

What languages does EchoDepth support?

EchoDepth provides official SDKs for JavaScript (npm install @echodepth/client) and Python (pip install echodepth). The REST API and WebSocket stream can be integrated with any language.

How much does EchoDepth cost?

EchoDepth is available on three tiers: Sandbox (free, for evaluation), Professional (£999/month + VAT, includes professional services), and Enterprise (custom pricing for high-volume or regulated deployments).

Does EchoDepth work in real time?

Yes. EchoDepth provides a WebSocket streaming endpoint for real-time analysis during live video calls, as well as a REST API for frame-by-frame or post-session analysis of recorded video.

EchoDepth API Docs | REST, WebSocket & SDKs

v1.2 REST + WebSocket GDPR Compliant

EchoDepth API

The EchoDepth API gives you real-time access to facial Action Unit (FACS) analysis and Valence, Arousal, Dominance (VAD) scoring — the core emotional intelligence engine that powers EchoDepth for Financial Services.

The API is designed for two primary integration patterns:

REST (frame-by-frame): Submit individual frames for analysis. Suited for post-session processing of recorded video.
WebSocket (streaming): Maintain a persistent session connection for real-time analysis during live video calls.

No specialist infrastructure is required. A standard webcam or video stream is sufficient.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer ed_live_sk_1234567890abcdef

API keys are prefixed with ed_live_sk_ for production and ed_test_sk_ for sandbox. Keys are scoped per organisation and never logged in plaintext on our infrastructure.

Request API access via the contact form. Sandbox credentials are issued within one business day.

Base URL & versioning

https://api.echodepth.ai/v1

The API is versioned via the URL path. Breaking changes will always result in a new version prefix. The current stable version is v1.

Sessions

A session represents a single continuous interaction — a claims interview, a mortgage interview, a trading session. Sessions give you temporal coherence: EchoDepth computes baseline VAD from the opening of a session and scores all subsequent frames relative to that baseline.

Create a session

          POST /v1/sessions

{
  "label": "claims-interview-2025-001",
  "use_case": "insurance_claims",       // optional context hint
  "baseline_window_s": 60,               // seconds for baseline calibration
  "alert_thresholds": {
    "arousal_high": 0.80,
    "valence_low": 0.25,
    "dominance_low": 0.30
  }
}
        

Response includes a session_id used in all subsequent requests. Sessions expire after 4 hours of inactivity.

End a session

POST /v1/sessions/{session_id}/end

Ending a session triggers generation of the full session report (see Session report).

Analyse a frame

Submit a single image frame for analysis. Returns AU activations and current VAD scores for the session.

          POST /v1/sessions/{session_id}/frames

Content-Type: multipart/form-data

frame: [JPEG or PNG, max 4MB]
timestamp_ms: 1704067200000   // Unix timestamp in ms

Response

          {
  "frame_id": "frm_abc123",
  "session_id": "ses_xyz789",
  "timestamp_ms": 1704067200000,
  "vad": {
    "valence": 0.61,
    "arousal": 0.83,
    "dominance": 0.43,
    "delta_from_baseline": {
      "valence": -0.18,
      "arousal": +0.29,
      "dominance": -0.22
    }
  },
  "active_aus": [1, 4, 17, 24],
  "alert_triggered": true,
  "alert_reason": "arousal_high"
}
        

Streaming (WebSocket)

For real-time analysis during live video calls, use the WebSocket endpoint. Frames are processed as they arrive; the server pushes VAD updates back to the client continuously.

wss://api.echodepth.ai/v1/sessions/{session_id}/stream

JavaScript example

          // Connect to stream
const ws = new WebSocket(
  `wss://api.echodepth.ai/v1/sessions/${sessionId}/stream`,
  ['echo-depth-v1', `token.${apiKey}`]
);

ws.onopen = () => {
  console.log('EchoDepth stream connected');
};

// Send a frame every 500ms
setInterval(() => {
  const frame = captureFrame(videoElement);   // your capture logic
  ws.send(JSON.stringify({
    type: 'frame',
    data: frame.toDataURL('image/jpeg', 0.8),
    timestamp_ms: Date.now()
  }));
}, 500);

// Receive VAD updates
ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  // update.vad.valence, .arousal, .dominance
  // update.alert_triggered
  renderDashboard(update);
};
        

Session report

The session report is generated when a session is ended. It contains aggregated VAD trends, timestamped anomalies, alert history and a human-readable summary.

          GET /v1/sessions/{session_id}/report

// Response (abridged)
{
  "session_id": "ses_xyz789",
  "duration_s": 1122,
  "frame_count": 2244,
  "baseline_vad": { "v": 0.71, "a": 0.38, "d": 0.74 },
  "mean_vad": { "v": 0.55, "a": 0.61, "d": 0.58 },
  "alerts": [
    {
      "type": "arousal_high",
      "timestamp_ms": 1704067473000,
      "value": 0.89,
      "session_offset_s": 273
    }
  ],
  "summary": "Elevated arousal detected during minutes 4–6 and 14–17. Sustained AU1+4 brow tension observed. Valence drop of 0.39 at session offset 273s. Review recommended."
}
        

VAD score object

Field	Type	Range	Description
`valence`	float	0.0–1.0	Positive (1.0) to negative (0.0) emotional state
`arousal`	float	0.0–1.0	Calm (0.0) to excited / high-activation (1.0)
`dominance`	float	0.0–1.0	Submissive (0.0) to in-control / dominant (1.0)
`delta_from_baseline`	object	±1.0	Per-dimension deviation from session baseline
`confidence`	float	0.0–1.0	Model confidence for this frame (affected by occlusion, lighting)

Action Unit object

The active_aus field returns an array of AU numbers with intensity ≥ 0.3. The full AU detail object (available via ?detail=aus) includes:

AU	Description	Relevance
`AU1`	Inner brow raise	Worry, fear, sadness
`AU4`	Brow lowerer	Concentration, anger, stress
`AU6`	Cheek raiser	Genuine enjoyment (Duchenne smile)
`AU12`	Lip corner pull	Smile — genuine or social
`AU17`	Chin raiser	Doubt, apprehension
`AU24`	Lip press	Suppression, withholding

All 46 FACS Action Units are tracked per frame. The full AU schema is available in the extended documentation provided on API access.

Errors

HTTP code	Code	Description
401	`unauthorized`	Invalid or missing API key
403	`forbidden`	Key does not have access to this resource
404	`not_found`	Session or frame ID does not exist
413	`frame_too_large`	Frame exceeds 4MB limit
422	`no_face_detected`	No face detected in the frame — check lighting and framing
429	`rate_limited`	Rate limit exceeded for your plan tier
500	`internal_error`	Server error — contact support if persistent

JavaScript SDK

npm install @echodepth/client

          import { EchoDepth } from '@echodepth/client';

const ed = new EchoDepth({ apiKey: process.env.ECHODEPTH_API_KEY });

// Create a session
const session = await ed.sessions.create({
  label: 'interview-001',
  useCase: 'insurance_claims',
  alertThresholds: { arousalHigh: 0.80, valenceLow: 0.25 }
});

// Analyse a frame
const result = await ed.frames.analyse(session.id, frameBlob);
console.log(result.vad);  // { valence, arousal, dominance }

// Stream mode
const stream = ed.sessions.stream(session.id);
stream.on('vad', (update) => renderDashboard(update));
stream.on('alert', (alert) => handleAlert(alert));
stream.sendFrame(frameBlob);
        

Python SDK

pip install echodepth

          from echodepth import EchoDepth
import os

ed = EchoDepth(api_key=os.environ["ECHODEPTH_API_KEY"])

# Create a session
session = ed.sessions.create(
    label="interview-001",
    use_case="insurance_claims",
    alert_thresholds={"arousal_high": 0.80, "valence_low": 0.25}
)

# Analyse a frame from file
with open("frame.jpg", "rb") as f:
    result = ed.frames.analyse(session.id, f)

print(result.vad.valence, result.vad.arousal, result.vad.dominance)

# Retrieve session report after session ends
ed.sessions.end(session.id)
report = ed.sessions.report(session.id)
print(report.summary)
        

Webhook events

EchoDepth can POST events to your configured webhook URL as they occur. Events are delivered with a signature header for verification.

Event	Trigger
`session.created`	New session opened
`session.alert`	Alert threshold crossed (arousal, valence or dominance)
`session.ended`	Session closed
`session.report_ready`	Session report available (usually <30s after session ends)

Webhook payload format

          POST https://your-app.com/webhooks/echodepth
X-EchoDepth-Signature: sha256=abc123...

{
  "event": "session.alert",
  "session_id": "ses_xyz789",
  "label": "interview-001",
  "timestamp_ms": 1704067473000,
  "alert": {
    "type": "arousal_high",
    "value": 0.89,
    "threshold": 0.80
  }
}
        

Pricing

All plans include full API access, sandbox environment, and professional services support. Prices shown exclude VAT.

Sandbox

Free

For evaluation and development. No payment required.

500 session minutes / month
REST API + WebSocket
No session reports
Watermarked outputs

Get sandbox access

Rate limits

Plan	Frames / second	Concurrent sessions	API requests / min
Sandbox	2 fps	1	60
Professional	30 fps	20	1,000
Enterprise	Unlimited	Unlimited	Unlimited

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

EchoDepth Developer Documentation — API Reference, SDKs and Pricing