Skip to main content
POST
/
v1
/
upload
/
analyze
Analyze Upload
curl --request POST \
  --url https://api.interhuman.ai/v1/upload/analyze \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'
{
  "signals": [
    {
      "type": "agreement",
      "start": 0,
      "end": 10,
      "probability": "high",
      "rationale": "Subject nodded repeatedly while maintaining eye contact."
    },
    {
      "type": "confidence",
      "start": 5,
      "end": 15,
      "probability": "medium",
      "rationale": "Steady voice with minimal hesitation."
    }
  ],
  "engagement_state": [
    {
      "start": 0,
      "end": 5,
      "state": "engaged"
    },
    {
      "start": 5,
      "end": 15,
      "state": "neutral"
    }
  ],
  "conversation_quality": {
    "overall": {
      "quality_index": 72,
      "clarity": 67,
      "authority": 68,
      "energy": 80,
      "rapport": 75,
      "learning": 70
    },
    "timeline": [
      {
        "start": 0,
        "end": 10,
        "values": {
          "quality_index": 70,
          "clarity": 69,
          "authority": 70,
          "energy": 78,
          "rapport": 77,
          "learning": 68
        }
      },
      {
        "start": 10,
        "end": 20,
        "values": {
          "quality_index": 74,
          "clarity": 65,
          "authority": 65,
          "energy": 82,
          "rapport": 73,
          "learning": 72
        }
      }
    ]
  }
}

​
Response Headers

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

Authorizations

​
Authorization
string
header
required

API key authentication. Include your API key in the Authorization header as 'Bearer <api_key>'.

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

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:
[
  {
    "end": 10,
    "probability": "high",
    "rationale": "Subject nodded repeatedly while maintaining eye contact.",
    "start": 0,
    "type": "agreement"
  },
  {
    "end": 15,
    "probability": "medium",
    "rationale": "Steady voice with minimal hesitation.",
    "start": 5,
    "type": "confidence"
  }
]
​
engagement_state
EngagementStateEntry · object[]

Time-varying engagement state derived from detected engagement signals. Each entry covers a contiguous time window with a single state: 'engaged' when engagement is detected, 'disengaged' when disengagement is detected, 'neutral' otherwise.

Example:
[
  { "end": 5, "start": 0, "state": "engaged" },
  { "end": 15, "start": 5, "state": "neutral" }
]
​
conversation_quality
ConversationQuality · object

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:
{
  "overall": {
    "authority": 68,
    "clarity": 67,
    "energy": 80,
    "learning": 70,
    "quality_index": 72,
    "rapport": 75
  },
  "timeline": [
    {
      "end": 10,
      "start": 0,
      "values": {
        "authority": 70,
        "clarity": 69,
        "energy": 78,
        "learning": 68,
        "quality_index": 70,
        "rapport": 77
      }
    },
    {
      "end": 20,
      "start": 10,
      "values": {
        "authority": 65,
        "clarity": 65,
        "energy": 82,
        "learning": 72,
        "quality_index": 74,
        "rapport": 73
      }
    }
  ]
}