Skip to main content
Use this quickstart to get your first successful analysis response in a few minutes. In this guide, you will:
  1. Submit a local video file to POST /v2/upload/analyze, which creates an analysis job
  2. Poll the job until it finishes
  3. Read each window’s engagement_status and signals[] (including per-signal rationale), plus the optional whole-file signals list and conversation_quality output
You’ll need an API key. Follow the API key guide for details. You’ll also need a video file. You can download an example from here.
Have an existing POST /v1/upload/analyze integration? See Migrate from V1 to V2.

1) Submit a video

Send a local video file to POST /v2/upload/analyze with model=inter-2. The file can be mp4, mov, avi, mkv, webm, or mpeg-ts. It must be at least 3 seconds long, at most 32 MB, and no longer than 30 minutes.

Video and audio content

Include both video and audio. Inter-2 requires sound as well as a picture. A file without a video track is refused with ih5001, and a file without an audio track with ih5008. To analyze a recording with no picture, use Inter-2 Audio instead: see Audio Analysis. The job returns core analysis by default. You can optionally request whole-file sections by passing include[] flags (shown below):
  • signals adds one signal list over the whole file, with one entry per continuous span of each signal type.
  • conversation_quality_overall and conversation_quality_timeline add conversation-quality scores.
The API answers 202 with a job envelope. Its status is queued, and its status_url is the path to poll in the next step.
If you want only core outputs, remove the include[] lines.

2) Poll the job

Read GET /v2/upload/jobs/{job_id} until status is completed or failed. The status moves through queued and running first. status_url is a path relative to https://api.interhuman.ai.
To skip polling for short files, add wait_seconds (up to 120) to the submit. The API then holds the request open and answers 200 with the job if it reaches completed or failed in time, so check status either way. If it doesn’t finish in time, you get the usual 202 with the pending job, so keep the polling loop. A failed job carries an error in the standard error shape instead of a result. A job stays readable for 1 hour after submission; after that, reading it returns 404 (ih4021). Reference: Inter-2 and Inter-2 Audio Upload Analyze

3) Read the result

A completed job’s result divides the file into fixed-length windows and reports each one:
  • windows[]: one entry per window, in file order, with its span (start_seconds, end_seconds).
  • windows[].engagement_status: the attention level over that window: engaged, neutral, or disengaged.
  • windows[].signals[]: social signals detected in that window, each with type, probability, and rationale. A signal’s start and end are its window’s span.
  • signals (optional, with include[]=signals): every signal in the file as one list, in the order they start. A signal of the same type in adjacent windows, or reported more than once in a window, becomes one entry spanning them, with the highest probability and its rationale (on a tie, the earliest one’s). A window without that signal ends the entry. It is an empty list when nothing was detected.
  • conversation_quality (optional): computed once over the whole file. It uses the conversation_quality_values shape in both overall and each timeline entry’s values object.
Time fields are expressed in seconds from the start of the uploaded video. conversation_quality_values shape (used by conversation_quality.overall and conversation_quality.timeline[].values):
Here’s an example of a completed job:

How to interpret it quickly

  • windows[].signals[] gives the signals observed in each window; rationale explains why each one was inferred.
  • signals gives the same signals over the whole file, one entry per continuous span, which is easier to show as a timeline.
  • windows[].engagement_status shows the attention level window by window.
  • conversation_quality.overall is a single interaction summary.
  • conversation_quality.timeline[] shows how quality changes over time.

Next steps