Video analysis quickstart

Upload a video, wait for processing, read the emotion analysis. Three calls.

The same pattern works for audio, images and text — swap the media type and the detail endpoint.

1. Upload

Post the file as form fields — these endpoints take multipart/form-data, not JSON.

curl -X POST https://devapi.imentiv.ai/v2/videos \
  -H "X-API-Key: your_api_key" \
  -F "video_file=@interview.mp4" \
  -F "title=Candidate interview" \
  -F "transcription=true" \
  -F "text_emotion=true"

title is the only required field. You can also pass video_url instead of video_file to have Imentiv fetch it — a YouTube, Dropbox or direct link.

The response carries the id you will poll:

{
  "id": "vid_8f14e45fea6d",
  "title": "Candidate interview",
  "status": "processing",
  "duration": 184.2,
  "transcription": true,
  "text_emotion": true,
  "created_at": "2026-08-20T09:12:45Z"
}

2. Wait for processing

Poll the status endpoint. It reports each stage separately, because they finish at different times — the transcript is usually ready well before personality analysis.

curl "https://devapi.imentiv.ai/v2/videos/vid_8f14e45fea6d/statuses?status=true&speech_status=true" \
  -H "X-API-Key: your_api_key"

{
  "media_id": "vid_8f14e45fea6d",
  "media_type": "videos",
  "status": "completed",
  "speech_status": "completed"
}

Pass only the flags you care about — each stage is a separate optional query parameter, and there are eighteen of them.

Poll with backoff, or use a callback

Processing scales with video length. Rather than polling tightly, either back off progressively, or pass callback_url on the upload and have Imentiv notify you instead.

3. Read the analysis

curl https://devapi.imentiv.ai/v2/videos/vid_8f14e45fea6d \
  -H "X-API-Key: your_api_key"

The response is large, because it carries everything the analysis produced. The fields you most likely want first:

Field	What it holds
overall_emotions	Whole-video emotion summary — label to score
face_emotions	Emotion scores per detected face, keyed by face ID
faces	One entry per detected person
emotions_list	The emotion labels present in this video
audio_transcription	What was said
has_transcript	Whether a transcript exists at all
summary	Generated narrative summary
csv_analysis_url	The same data as a downloadable CSV
audio_id / text_id	The companion analyses — see below

transcription and text_emotion are switches, not results

Both are booleans, recording what you asked for at upload time. So are diarization and processing_fps. None of them holds content.

Drive your transcript UI off has_transcript, not transcription: a video whose transcript you supplied yourself has transcription: false and a transcript all the same.

Voice and text emotion live on their own records. A processed video links to them by id, so GET /v2/audios/{audio_id} gives you the voice-tone analysis and GET /v2/texts/{text_id} the emotion of what was said. Either may be null if that stage did not run.

Scores are explained in Understanding emotion scores. Note that this response does not carry the circumplex measures (valence, arousal and the rest) — those are on the realtime frames.

Then what

A PDF report. One endpoint both triggers generation and serves the result, so you can call it without checking first:

curl "https://devapi.imentiv.ai/v2/reports/pdf/vid_8f14e45fea6d?media_type=video" \
  -H "X-API-Key: your_api_key"

You get	It means
200 with application/pdf	Ready. That's the report
200 with JSON	Not there yet, so this call started generating it
202 with JSON	Generation was already running

Pass callback_url to be notified instead of polling. media_type is required and video is the only value accepted today.

An emotional-highlight reel. POST /v1/videos/highlights starts the cut; then poll highlight_status on the statuses endpoint and read highlight_url when it completes.

Answers about the video. The Insights API takes natural-language questions about an analysed video.

A live feed instead of a file. See the realtime quickstart.