Quickstart Playbook

30-Second Test (Choose Your Language)

cURL
Python
JavaScript

# Download sample audio
curl -o demo_call.mp4 https://api.illocution.ai/samples/demo_call.mp4

# Analyze it
curl -X POST https://api.illocution.ai/analyze \
  -H "X-API-Key: demo_12345_public_test_key" \
  -F "file=@demo_call.mp4"

import requests

# Download sample
with open('demo_call.mp4', 'wb') as f:
    f.write(requests.get('https://api.illocution.ai/samples/demo_call.mp4').content)

# Analyze it
response = requests.post(
    'https://api.illocution.ai/analyze',
    headers={'X-API-Key': 'demo_12345_public_test_key'},
    files={'file': open('demo_call.mp4', 'rb')}
)

print(response.json())

// Download sample
const fileResponse = await fetch('https://api.illocution.ai/samples/demo_call.mp4');
const blob = await fileResponse.blob();

// Analyze it
const formData = new FormData();
formData.append('file', blob, 'demo_call.mp4');

const response = await fetch('https://api.illocution.ai/analyze', {
  method: 'POST',
  headers: {
    'X-API-Key': 'demo_12345_public_test_key'
  },
  body: formData
});

const result = await response.json();
console.log(result);

You’ll receive a complete analysis including speaker diarization, emotions, sentiment, and conversation insights in ~10-20 seconds. ✨

Prerequisites

curl installed (or use Postman)
Outbound HTTPS access to https://api.illocution.ai

Download our sample audio file to test immediately:

curl -O https://api.illocution.ai/samples/demo_call.mp4

Batch Upload in 3 Steps

1. Send the file

curl -X POST https://api.illocution.ai/analyze \
  -H "X-API-Key: $ILLOCUTION_KEY" \
  -F "file=@demo_call.mp4"

2. Inspect the response

(truncated example):

{
  "conversation_id": "analysis_1234abcd",
  "summary": { "overview": "...", "key_insights": ["[00:12] ..."] },
  "timeline": [{ "utterance_id": "utt_0", "speaker": "Speaker_0", ... }],
  "insights": { "overall_sentiment": { "mean": 0.35, "trend": "positive" } }
}

3. Download artifacts

If needed, use the returned artifact_dir to access persisted analysis files.

Realtime Replay Walkthrough

1. Start the SSE stream

curl -N https://api.illocution.ai/analyze/stream \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: $ILLOCUTION_KEY" \
  -F "file=@demo_call.mp4"

2. Listen for events

(sample output):

event: final_transcript
data: {"utterance_id":"analysis_utt_0003","speaker":"Speaker_0","text":"Thanks for joining..."}

event: emotion
data: {"utterance_id":"analysis_utt_0003","emotion":{"joy":0.62,...},"scores":{"valence":0.41,...}}

3. Close the stream

After the done event fires or when idle.

Live Capture End-to-End

1. Start a session

curl -X POST https://api.illocution.ai/analyze/live/start \
  -H "X-API-Key: $ILLOCUTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "live_demo.wav", "ttl_seconds": 1200}'

Response includes session_id, chunk_endpoint, events_endpoint, and control_endpoint.

2. Upload sequential chunks

(pseudo-example using bash loop):

CHUNK_URL="https://api.illocution.ai/analyze/live/$SESSION_ID/chunk"
seq 0 4 | while read N; do
  curl -X POST "$CHUNK_URL" \
    -H "X-API-Key: $ILLOCUTION_KEY" \
    -F "chunk_seq=$N" \
    -F "chunk=@chunks/$N.pcm"
done

3. Attach to the SSE feed

curl -N https://api.illocution.ai/analyze/live/$SESSION_ID/events \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: $ILLOCUTION_KEY"

4. Finalize when done

curl -X POST https://api.illocution.ai/analyze/live/$SESSION_ID/control \
  -H "X-API-Key: $ILLOCUTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"finalize"}'

The SSE client will then receive the final summary_update and done events. These flows can be copied directly into Mintlify pages (“Batch Quickstart”, “Replay Quickstart”, “Live Quickstart”) for customer onboarding.

Introduction

Endpoints

Cookbooks

Reference

30-Second Test (Choose Your Language)

Prerequisites

Batch Upload in 3 Steps

1. Send the file

2. Inspect the response

3. Download artifacts

Realtime Replay Walkthrough

1. Start the SSE stream

2. Listen for events

3. Close the stream

Live Capture End-to-End

1. Start a session

2. Upload sequential chunks

3. Attach to the SSE feed

4. Finalize when done

​30-Second Test (Choose Your Language)

​Prerequisites

​Batch Upload in 3 Steps

​1. Send the file

​2. Inspect the response

​3. Download artifacts

​Realtime Replay Walkthrough

​1. Start the SSE stream

​2. Listen for events

​3. Close the stream

​Live Capture End-to-End

​1. Start a session

​2. Upload sequential chunks

​3. Attach to the SSE feed

​4. Finalize when done

30-Second Test (Choose Your Language)

Prerequisites

Batch Upload in 3 Steps

1. Send the file

2. Inspect the response

3. Download artifacts

Realtime Replay Walkthrough

1. Start the SSE stream

2. Listen for events

3. Close the stream

Live Capture End-to-End

1. Start a session

2. Upload sequential chunks

3. Attach to the SSE feed

4. Finalize when done