Skip to main content
POST
Analyze Upload
Moving to Inter-2? See Migrate from V1 to V2 for the changes to requests, the job lifecycle, and results on POST /v2/upload/analyze.

Response Headers

header
Unique identifier for the request. Include this when contacting support.Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

Authorizations

Authorization
string
header
required

Send your API key, or a client token minted by POST /v1/client_tokens, in the Authorization header as Bearer <credential>. This endpoint requires the interhumanai.upload scope: an API key must hold it, and a client token must be minted with it (the minting key must have held it). A credential without it is refused with ih2003.

Headers

X-Client-Request-Id
string

Optional identifier supplied by the client to correlate this request with their own logs. When provided, the value is recorded alongside the server-assigned correlation ID in Interhuman logs to aid lookup and support investigations. This header is not echoed back in the response; the server returns its own correlation ID in the X-Correlation-ID HTTP response header.

Body

multipart/form-data
file
file
required

Video file to analyze. The video must be at least 3 seconds long and the upload must not exceed 32MB. Accepts the following formats: mp4, avi, mov, mkv, mpeg-ts, webm.

include[]
enum<string>[]

Optional flags indicating which sections should be included in the response. When omitted, no optional sections are included.

Use these flags to control which conversation quality sections are included in the response.

conversation_quality_overall: Include overall conversation quality index. conversation_quality_timeline: Include conversation quality timeline.

Available options:
conversation_quality_overall,
conversation_quality_timeline
goal_dimensions[]
enum<string>[]

Optional conversation-quality goal dimensions for this interaction. Supplying at least one goal dimension triggers feedback generation. Ignored when conversation_context is supplied — that field then drives feedback generation on its own.

Conversation quality dimensions a caller can flag as a session goal.

The values map one-to-one onto the five CQI quality dimensions defined in services.cqi.DIMENSION_KEYS:

  • clarity — Clarity / Structure
  • authority — Authority / Credibility
  • energy — Energy / Presence
  • rapport — Rapport / Relational Safety
  • learning — Learning / Exploration
Available options:
clarity,
authority,
energy,
rapport,
learning
conversation_context
string
default:""

Optional free-text description of the interaction scenario, role, or communication goal. Used as the sole source of context for feedback generation; goal dimensions are ignored when this context is supplied.

Response

Successful Response

Contains the result of the video analysis.

signals
Signal · object[]
required

List of all social signals detected in the analyzed video.

Example:
engagement_state
EngagementStateEntry · object[]

Time-varying engagement state derived from the model's engagement status. Each entry covers a contiguous time window with a single state: 'engaged', 'disengaged', or 'neutral'.

Example:
feedback
InteractionFeedback · object | null

Structured interaction feedback returned by the coach model.

Discriminated on type: a feedback result populates message, active_dimensions, and primary_signal; a no_feedback result populates reason instead.

Example:
conversation_quality
ConversationQuality · object | null

Conversation quality Index with optional overall and time-varying scores.

Use the Include flags in the request to control which conversation quality sections are included in the response.

Example: