interhumanai/interhuman-post-processing

Interhuman Post-Processing Analysis

Wrapper for the Interhuman API upload endpoint that analyzes completed video files and returns social-intelligence signals.

When to Use

Use this skill when:

• Analyzing a pre-recorded video file (MP4, AVI, MOV, MKV, MPEG-TS, MPEG-2-TS, WebM)
• The video file is already complete (not a live stream)
• You need to get all detected signals for the entire video at once

Do NOT use this skill for:

• Real-time analysis of ongoing video feeds — use interhuman-stream-analyze (/v1/stream/analyze) instead

Required Inputs

1. API Key: Use your API key as bearer credential in Authorization: Bearer <api_key>

2. Video File: Binary video file to analyze

   • Size: 10 KB minimum, 32 MB maximum
   • Formats: mp4, avi, mov, mkv, mpeg-ts, mpeg-2-ts, webm

   Content requirements (both video and audio must be meaningful):

   • Include real visual content; a valid file with no meaningful video (e.g. a black or blank screen) is discouraged.
   • Include real audio; a valid file with no meaningful audio (e.g. muted or silent track) is discouraged.
   • The API analyzes observable social cues from picture and sound—placeholder or empty media reduces result quality.

Authentication

Direct API key usage in the Authorization header:

• Authorization: Bearer <api_key>

Legacy compatibility: if an existing integration still uses token exchange, please switch the API key directly in every endpoint.

API Call Instructions

Endpoint Details

• Base URL: https://api.interhuman.ai
• Endpoint: /v1/upload/analyze
• Method: POST
• Content-Type: multipart/form-data
• Authentication: Bearer credential in Authorization header.

Request Format

Send the video file as multipart/form-data with a required field named file containing the binary video data.

You can optionally include include[] values to request conversation quality outputs:

• conversation_quality_overall
• conversation_quality_timeline

Example: cURL

curl -X POST https://api.interhuman.ai/v1/upload/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/video.mp4;type=video/mp4" \
  -F "include[]=conversation_quality_overall" \
  -F "include[]=conversation_quality_timeline"

Example: Python

import os
import requests

api_key = "YOUR_API_KEY"
video_path = "/path/to/video.mp4"

with open(video_path, "rb") as f:
    files = {"file": (os.path.basename(video_path), f, "video/mp4")}
    response = requests.post(
        "https://api.interhuman.ai/v1/upload/analyze",
        headers={"Authorization": f"Bearer {api_key}"},
        files=files,
        data=[("include[]", "conversation_quality_overall")],
        timeout=300,
    )

# Return the raw JSON response
print(response.json())

Example: JavaScript/Node.js

import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const formData = new FormData();
formData.append("file", fs.createReadStream("path/to/video.mp4"));

const response = await fetch("https://api.interhuman.ai/v1/upload/analyze", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INTERHUMAN_API_KEY}`
  },
  body: formData
});

const json = await response.json();
console.log(json);

Response Format

The API returns a JSON object where:

• signals is required
• engagement_state may be present
• conversation_quality may be present when requested via include[]

Each signal object in signals contains:

• type (string): The detected social signal type. Possible values: agreement, confidence, confusion, disagreement, disengagement, engagement, frustration, hesitation, interest, skepticism, stress, uncertainty
• start (number): Start time of the signal in seconds relative to video start
• end (number): End time of the signal in seconds relative to video start

Example Response

{
  "signals": [
    {
      "type": "agreement",
      "start": 2.5,
      "end": 8.2
    },
    {
      "type": "uncertainty",
      "start": 12.3,
      "end": 19.1
    }
  ]
}

Error Responses

On error, the API returns JSON with:

• error_id (string): Stable error identifier
• message (string): Error message
• correlation_id (string, optional): Request correlation identifier
• link (string, optional): Link to additional error documentation

Status Codes

• 200: Success
• 400: Bad request (invalid file format or parameters)
• 401: Unauthorized (missing or invalid bearer credential)
• 403: Forbidden (credential lacks required scope)
• 413: Payload too large (file exceeds 32 MB)
• 422: Unprocessable entity (file missing or invalid)
• 429: Too many requests
• 500: Internal server error

Output Rules

CRITICAL: This skill is a strict wrapper. You MUST:

1. Return the exact JSON response from the API without any modification
2. Do NOT summarize, transform, or rename fields
3. Do NOT extract or filter signals
4. Do NOT add commentary or interpretation
5. Preserve all fields exactly as received from the API

The response should be the raw JSON object returned by the API, passed through verbatim.