Skip to main content
POST
/
analyze
Analyze media file
curl --request POST \
  --url https://api.illocution.ai/analyze \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file'
{
  "conversation_id": "analysis_f38de2c0c1",
  "utterances": 123,
  "timeline": [
    {
      "utterance_id": "<string>",
      "speaker": "<string>",
      "t_start": 123,
      "t_end": 123,
      "text": "<string>",
      "asr_confidence": 123,
      "prosody": {},
      "prosody_desc": "<string>",
      "emotion": {},
      "sentiment": {},
      "polarity": 123,
      "subjectivity": 123,
      "cognitive": {},
      "commitment_score": 123,
      "commitment_level": "<string>",
      "passion_score": 123,
      "passion_level": "<string>",
      "conviction_score": 123,
      "lexical_markers": {},
      "acoustic_reasoning": "<string>",
      "confidence": 123
    }
  ],
  "summary": {
    "overview": "<string>",
    "key_insights": [
      "<string>"
    ],
    "notable_patterns": [
      "<string>"
    ],
    "recommendations": [
      "<string>"
    ],
    "what_went_well": [
      "<string>"
    ],
    "what_went_wrong": [
      "<string>"
    ],
    "speaker_dynamics": {},
    "conversation_quality": "<string>"
  },
  "insights": {
    "overall_sentiment": {
      "mean": 123,
      "std": 123,
      "trend": "<string>"
    },
    "dominant_emotions": [
      "<string>"
    ],
    "engagement_pattern": "increasing",
    "key_moments": [
      {
        "moment_id": "<string>",
        "category": "objection",
        "speaker_id": "<string>",
        "start_ms": 123,
        "end_ms": 123,
        "utterance_ids": [
          "<string>"
        ],
        "summary": "<string>",
        "labels": [
          "<string>"
        ],
        "confidence": 123
      }
    ],
    "speaker_profiles": {},
    "conversation_dynamics": {},
    "cognitive_profile": {}
  },
  "transitions": [
    {
      "transition_id": "<string>",
      "at_ms": 123,
      "from_state": {},
      "to_state": {},
      "evidence_utterance_ids": [
        "<string>"
      ],
      "drivers": {},
      "confidence": 123,
      "stability": "<string>"
    }
  ],
  "moments": [
    {
      "moment_id": "<string>",
      "category": "objection",
      "speaker_id": "<string>",
      "start_ms": 123,
      "end_ms": 123,
      "utterance_ids": [
        "<string>"
      ],
      "summary": "<string>",
      "labels": [
        "<string>"
      ],
      "confidence": 123
    }
  ],
  "segmentation": {
    "phases": [
      {
        "phase_id": "<string>",
        "phase_name": "<string>",
        "start_timestamp": 123,
        "end_timestamp": 123,
        "start_utterance_id": "<string>",
        "end_utterance_id": "<string>",
        "utterance_count": 123,
        "theme": "<string>",
        "summary": "<string>",
        "emotional_tone": "<string>",
        "key_moments": [
          {
            "moment_id": "<string>",
            "category": "objection",
            "speaker_id": "<string>",
            "start_ms": 123,
            "end_ms": 123,
            "utterance_ids": [
              "<string>"
            ],
            "summary": "<string>",
            "labels": [
              "<string>"
            ],
            "confidence": 123
          }
        ],
        "transition_signal": {
          "transition_id": "<string>",
          "at_ms": 123,
          "from_state": {},
          "to_state": {},
          "evidence_utterance_ids": [
            "<string>"
          ],
          "drivers": {},
          "confidence": 123,
          "stability": "<string>"
        }
      }
    ],
    "total_phases": 123,
    "segmentation_rationale": "<string>",
    "narrative_arc": "<string>",
    "key_transitions": [
      {
        "transition_id": "<string>",
        "at_ms": 123,
        "from_state": {},
        "to_state": {},
        "evidence_utterance_ids": [
          "<string>"
        ],
        "drivers": {},
        "confidence": 123,
        "stability": "<string>"
      }
    ]
  },
  "agent_results": [
    "<any>"
  ],
  "artifact_dir": "<string>",
  "upload_path": "<string>",
  "agent_outputs_path": "<string>",
  "goal": "<string>"
}

Authorizations

X-API-Key
string
header
required

API key for authentication. Can also be passed as query parameter: api_key=

Query Parameters

stream
boolean
default:false

When true, behave like /analyze/stream and emit SSE instead of a JSON body

Body

multipart/form-data
file
file
required

Audio/video media file (.mp4, .mov, .webm, .mp3, .wav, .m4a, .aac)

goal
string

Optional analysis focus (e.g., "Highlight objections about pricing")

Response

Analysis complete

conversation_id
string

Unique identifier for the analysis

Example:

"analysis_f38de2c0c1"

utterances
integer

Count of diarized utterances

timeline
object[]

Array of enriched utterances

summary
object
insights
object
transitions
object[]

Affective state transitions

moments
object[]

Key moment detections

segmentation
object
agent_results
any[]

Per-utterance raw agent payloads (emotion, sentiment, cognitive)

artifact_dir
string

Server-side path for debugging

upload_path
string

Server-side path for debugging

agent_outputs_path
string

Server-side path for debugging

goal
string

Echo of the provided context string