Skip to main content
​
Whole-File Signals on Upload Jobs

​
One signal list for the whole file

An upload job’s result can now carry every detected signal in one list over the whole file, beside the per-window results. Add include[]=signals to POST /v2/upload/analyze, and the completed job’s result.signals lists each signal once with its type, start, end, probability, and rationale, in chronological order. A signal the model reports in several consecutive windows appears as one entry spanning all of them, with the highest probability it was reported at and the rationale that went with it.
The list is present whether you wait on the submit or read the job later, and it is an empty list when nothing was detected. It combines freely with the Conversation Quality Index flags and works with every model the route serves. Without the flag, the result is unchanged.
​
Inter-2: A New Model on the v2 Routes

​
Analyze with Inter-2

Inter-2 is our second-generation model, served on two new endpoints beside the existing Inter-1 ones. Inter-2 watches the picture and listens to the sound of each analysis window together, and reports an engagement reading and the social signals it observed, each with a short rationale. Inter-2 signals carry no modality field, since Inter-2 reads picture and sound together.
  • WS /v2/stream/analyze analyzes a live feed. It works exactly like WS /v1/stream/analyze: the same handshake, session settings, video clips in, and signal.*, engagement.updated, conversation_quality.updated, coverage.* and error messages out, including the graceful session.close handshake. Only the model differs, so an application built for the v1 stream switches by changing the path.
  • POST /v2/upload/analyze analyzes a finished file as a job. Send the file and model=inter-2 as a multipart request: an mp4, mov, avi, mkv, webm, or mpeg-ts video carrying both a video and an audio track, at least 3 seconds long, at most 32 MB, and no longer than 30 minutes by default.

​
Upload jobs

The upload route answers 202 at once with a job envelope: a job_id, a status of queued, the model, and a status_url. Read GET /v2/upload/jobs/{job_id} until status is completed, when result lists one entry per fixed-length window with its span, an engagement_status, and the signals observed over it — or failed, when error says why in the API’s standard error shape. Results stay readable until the envelope’s expires_at. Add wait_seconds to have the API hold the request open and answer 200 with the finished job when it completes in time.

​
Conversation Quality Index on upload jobs

An upload job takes the same optional include[] flags as POST /v1/upload/analyze. Send conversation_quality_overall, conversation_quality_timeline, or both with the file, and once the job is completed its result carries a conversation_quality block scored over the whole file from every window’s signals and engagement: overall holds the five 0–100 dimension scores and their mean, and timeline holds the same scores per consecutive period of the file. You get exactly the sections you asked for, on the wait_seconds response and on GET /v2/upload/jobs/{job_id} alike. A file in which nothing was detected still answers a requested block, with every dimension at the neutral 50.

​
Choose the model

An upload job names its model in the required model form field. A stream session names it with the optional model query parameter on the connection URL, and defaults to inter-2; the model is fixed for the session once media is sent. session.ready lists the model under supported_session_config_options.model, and session.updated echoes the one in force.

​
Permissions

Upload jobs, including reading them back, need interhumanai.upload, and the v2 stream needs interhumanai.stream.

​
Errors

A credential without the needed permission is refused with ih2003, naming the permission — on the stream right after the handshake with close code 4003. An upload file with no picture is refused with ih5001, a silent one with ih5008, and a longer-than-allowed one with ih4004; an expired or unknown job id answers ih4021. Where the model is not available, the API answers ih1003 (close code 1013 on the stream) and nothing is analyzed or billed.

​
Streams that never decode

On every stream endpoint, a session whose clips never complete a media unit (a WebM cluster or an MP4 fragment) now ends with one ih6010 error instead of staying open and producing nothing. If you see it, send MediaRecorder’s dataavailable blobs as they come rather than re-splitting them, and send any initialization segment before the media that depends on it.Both first-party SDKs support all of the above: client.stream({ apiVersion: "v2" }) in TypeScript and client.stream(api_version="v2") in Python open the v2 stream, and the upload client adds submit (with include), get_job / getJob and wait_for_job / waitForJob.
​
Clear Errors for Streams Without Video

​
A stream with no video now tells you

WS /v1/stream/analyze analyzes the picture in your stream. When a session’s recording carries no video track, the session now sends one error message with the code ih5001 and stops analyzing, rather than returning results with nothing in them.The usual cause is a recorder started from an audio-only source — a getUserMedia({ audio: true }) call with no video constraint, or a camera whose permission was never granted. The message says what is missing and what to do about it, and analysis resumes on its own once a recording with video arrives. Nothing the session skipped is billed.This is a requirement on the recording, not on each clip: a continuation clip carrying raw media with no header of its own is still fine.
​
SDK Attribution in API Telemetry

​
The API now records which SDK a request came from

Requests and live sessions can identify the client SDK that made them, so we can report SDK adoption, see which versions are in use, and give better support when a problem turns out to be version-specific.
  • HTTP requests may send X-Interhuman-SDK: <sdk-name>/<semver>, e.g. typescript/0.13.0.
  • WebSocket handshakes (WS /v1/stream/analyze) may carry sdk=<sdk-name>&sdk_version=<semver> on the URL, because a browser WebSocket cannot set custom handshake headers. The Sec-WebSocket-Protocol: access_token, <credential> authentication contract is unchanged.
If you use the first-party SDKs, @interhumanai/sdk and interhumanai 0.13.0 send this for you — upgrade and there is nothing else to do. If you call the API directly, nothing changes: the metadata is optional, and requests without it are supported exactly as before.The metadata is SDK identity and version only. It carries no device, OS, runtime, hostname, application, or end-user information, and because any caller can send any value, we treat it as a self-declared hint: it never affects authentication, authorization, scopes, quotas, or billing, and a missing, malformed, or unrecognized value is ignored rather than rejected.
​
Visual-Coverage Notices on the Stream API

​
Know when a window’s video coverage was partial

The informational coverage.degraded message reports analysis windows that decoded materially less video than the window span while the audio ran to the end — the shape a static screen share or a long-GOP encoder produces when its keyframe interval exceeds the analysis window.Those windows are still analyzed, using the audio plus whatever video decoded, and are billed normally. The notice lists the affected time ranges so your application knows the visual signals over that stretch drew on partial video.This applies to WS /v1/stream/analyze.
​
Signal Modality

​
Every signal names where its evidence came from

Signals carry a modality list naming the analysis modalities that detected them:
Signals from the Upload and Stream APIs carry video. Use it to tell your users which evidence a signal rests on.
​
Stream Shutdown Grace Period

​
Close a stream session without losing the last windows

The stream WebSocket endpoint supports a caller-initiated graceful shutdown handshake. Send session.close when you have finished sending video and the API acknowledges with session.closing, including a maximum drain timeout. It then finishes analyzing the video it already accepted, ends still-active signals, sends session.ended, and closes the connection cleanly.
​
Inter-1 Streaming

​
Inter-1 goes streaming

The Inter-1 Streaming API is now available. The same behavioral analysis Inter-1 already delivers on upload — social signals with rationales, engagement, and the conversation quality — now runs on live video over WebSocket while the conversation is still happening.

​
Highlights

  • Live behavioral analysis: stream video chunks to wss://api.interhuman.ai/v1/stream/analyze and receive typed events (signal.detected, signal.ended, engagement.updated, and more) as state changes unfold.
  • Full Inter-1 capability on live video: the same social signals Inter-1 reports on upload, with structured rationales, engagement tracking, and optional five-dimension Conversation Quality Index scores — not a reduced streaming subset.
  • Predictable session contract: session.ready declares server limits up front; an optional session config message opts into additional analyses before you send the first frame.
  • Low-latency sliding windows: stream chunks at whatever size fits your pipeline; analysis runs on overlapping sliding windows with ordered, concurrent processing — when the queue backs up, dropped windows are reported so clients never miss silent gaps.
  • Production-minded billing and lifecycle: you are billed only for seconds actually analyzed and delivered; on disconnect, in-flight work is cancelled and active signals receive an implicit signal.ended.

​
Explore streaming

​
Authentication Simplification

​
Direct API key authentication for requests

Interhuman supports a simple authentication path for API integrations. You can send your API key directly in the Authorization header on requests, including POST /v1/upload/analyze.

​
Highlights

  • One-step auth for integrations: call API endpoints directly with Authorization: Bearer <api_key>.
  • Lower setup overhead: no required key exchange step before your first upload request.
​
General Availability

​
Interhuman V1 is live

Interhuman V1 is now generally available. This release stabilizes the core integration path: authenticate, upload a video, and receive structured analysis with predictable error handling.

​
Highlights

  • Self-serve onboarding: create an account and generate API keys directly at platform.interhuman.ai.
  • Stable API contract: V1 authentication and upload-analysis flows are stable for production use.
  • Reliable processing: consistent analysis completion across real-world video uploads.
  • Production-ready errors: standardized error payloads (error_id, correlation_id, link, message) for faster debugging and stronger recovery logic.
  • Faster setup path: quickstart and codealong docs that get you from API key to first successful analysis quickly.

​
Explore V1