- Submit a local video file to
POST /v2/upload/analyze, which creates an analysis job - Poll the job until it finishes
- Read each window’s
engagement_statusandsignals[](including per-signalrationale), plus the optional whole-filesignalslist andconversation_qualityoutput
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.
1) Submit a video
Send a local video file toPOST /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 withih5001, 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):
signalsadds one signal list over the whole file, with one entry per continuous span of each signal type.conversation_quality_overallandconversation_quality_timelineadd conversation-quality scores.
202 with a job envelope. Its status is queued, and its status_url is the path to poll in the next step.
include[] lines.
2) Poll the job
ReadGET /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.
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’sresult 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, ordisengaged. - windows[].signals[]: social signals detected in that window, each with
type,probability, andrationale. A signal’sstartandendare 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 highestprobabilityand itsrationale(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_valuesshape in bothoveralland each timeline entry’svaluesobject.
conversation_quality_values shape (used by conversation_quality.overall and conversation_quality.timeline[].values):
How to interpret it quickly
windows[].signals[]gives the signals observed in each window;rationaleexplains why each one was inferred.signalsgives the same signals over the whole file, one entry per continuous span, which is easier to show as a timeline.windows[].engagement_statusshows the attention level window by window.conversation_quality.overallis a single interaction summary.conversation_quality.timeline[]shows how quality changes over time.
Next steps
- Build a Video Analyzer App — full UI codealong.
- Social signals — meaning of each signal type.
- Conversation quality — quality dimensions and interpretation.
- Inter-2 and Inter-2 Audio Upload Analyze — full request/response and error details.
- Migrate from V1 to V2 — for integrations on
POST /v1/upload/analyze.