Skip to main content
In this 2-step quickstart, you’ll learn how to:
  1. Upload a video and analyze it with the Interhuman API
  2. Receive social-intelligence signals in a structured JSON response
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. Upload the video

Use one of the requests below to send a local video file (any ffmpeg-supported format like MP4, AVI, MOV, MKV, WEBM; minimum 10 KB, maximum 20MB) to POST /v0/upload/analyze. The API processes the file in the background and prepares segment-level analysis for the entire video. 
export API_TOKEN="YOUR_API_TOKEN"
export VIDEO_PATH="path_to_your_video.mp4"

curl -X POST https://api.interhuman.ai/v0/upload/analyze \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -F "file=@${VIDEO_PATH};type=video/mp4"

​
2. Read the response

After your upload is processed, the API returns a list of detected signals. Each signal represents a specific behavioral event identified in the video, including its timing and detailed analysis. Each signal object includes:
  • type: The category of the detected behavior. Possible values: Agreement, Confidence, Confusion, Disagreement, Disengagement, Engagement, Frustration, Hesitation, Interest, Skepticism, Stress, Uncertainty.
  • start and end: Timestamps in seconds indicating when the behavior occurred.
  • reasoning: Detailed observations explaining why this behavior was detected.
  • feedback: Actionable insights or interpretation of the behavior.
  • confidence: The model’s confidence in the detection (e.g., High, Medium, Low).
  • intensity: The strength or magnitude of the behavior (e.g., Strong, Moderate).
Here’s an example of what the API returns: 
[
  {
      "type": "Agreement",
      "start": 2.5,
      "end": 8.2,
      "reasoning": "Subject maintained steady eye contact and nodded repeatedly while the interviewer was speaking, accompanied by a slight forward lean.",
      "feedback": "Strong positive engagement signal. The candidate is actively listening and showing agreement with the points being discussed.",
      "confidence": "High",
      "intensity": "Strong"
  },
  {
      "type": "Interest",
      "start": 12.3,
      "end": 19.1,
      "reasoning": "Subject leaned in, maintained eye contact, and asked a probing follow-up question.",
      "feedback": "Curiosity detected; continue providing detailed, informative responses.",
      "confidence": "High",
      "intensity": "Moderate"
  },
  ...
]
You can read more in the Upload & Analyze API Reference.