> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interhuman.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Analyze uploaded video
> Analyze a video file in upload mode.
#### Response Headers
Unique identifier for the request. Include this when contacting support.
Example: `f47ac10b-58cc-4372-a567-0e02b2c3d479`
## OpenAPI
````yaml post /v1/upload/analyze
openapi: 3.1.0
info:
title: interhuman-api
version: 1.13.9
servers:
- url: https://api.interhuman.ai
description: Production environment
security: []
paths:
/v1/upload/analyze:
post:
summary: Analyze Upload
description: Analyze a video file in upload mode.
operationId: analyze_upload_v1_upload_analyze_post
parameters:
- name: X-Client-Request-Id
in: header
required: false
description: >-
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.
schema:
type: string
title: X-Client-Request-Id
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_analyze_upload_v1_upload_analyze_post'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AnalysisResult'
example:
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
'400':
description: >-
Bad request. The video file is missing (ih4001), too short (ih4007),
or a request parameter is invalid (ih4005).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error_id: ih4001
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih4001-missing-video-file
message: >-
No video file provided. Include the video as a
multipart/form-data field named 'file'.
'401':
description: >-
Unauthorized. The API key is missing (ih2002) or the credentials are
invalid (ih2001).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error_id: ih2002
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih2002-missing-credentials
message: >-
No authentication credentials were provided. Include your API
key in the 'Authorization: Bearer ' header (or in the
'Sec-WebSocket-Protocol' header for WebSocket connections).
'403':
description: Forbidden. The API key does not include the required scope (ih2003).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error_id: ih2003
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih2003-insufficient-scope
message: >-
Insufficient scope. This endpoint requires the
'interhumanai.upload' scope.
'413':
description: >-
Payload too large. The video file exceeds the maximum upload size
(ih4003).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error_id: ih4003
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih4003-file-too-large
message: Payload too large. The video file must not exceed 32.0 MB.
'422':
description: >-
Unprocessable video. The file is empty (ih5001), corrupted (ih5002),
uses an unsupported codec (ih5003), has a malformed segment
(ih5004), exceeds segment size limits (ih5005), contains a segment
that is too short (ih5006), or was rejected by the model (ih5007).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error_id: ih5001
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih5001-empty-video
message: >-
Unable to process the video: the file appears to be empty or
contains no video content.
'429':
description: >-
Too many requests or quota exceeded. The client has exceeded the
rate limit (ih3001), the account has hit its concurrent-request
limit (ih3002), or the account has reached its usage limit (ih3003).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
rate_limit:
summary: Rate limit exceeded
value:
error_id: ih3001
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih3001-rate-limit-exceeded
message: >-
Rate limit exceeded. You have sent too many requests.
Please wait 60 seconds before retrying.
concurrent_request_limit:
summary: Concurrent request limit exceeded
value:
error_id: ih3002
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih3002-concurrent-request-limit
message: >-
Concurrent request limit exceeded. You have 5 active
requests; the maximum is 5. Wait for an active request to
complete before submitting another.
quota_exceeded:
summary: Quota exceeded
value:
error_id: ih3003
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih3003-quota-exceeded
message: >-
Quota exceeded. Your account has reached its usage limit.
Contact support to upgrade your plan, add credits, or wait
for the quota to reset.
'500':
description: >-
Internal server error (ih1001) or the upstream AI service is
temporarily unavailable (ih1002).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error_id: ih1001
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih1001-internal-server-error
message: >-
Internal server error. Please try again or contact support if
the problem persists.
security:
- bearerAuth: []
components:
schemas:
Body_analyze_upload_v1_upload_analyze_post:
properties:
file:
type: string
format: binary
title: File
description: >-
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[]:
items:
$ref: '#/components/schemas/IncludeFlag'
type: array
title: Include[]
description: >-
Optional flags indicating which sections should be included in the
response. When omitted, no optional sections are included.
default: []
goal_dimensions[]:
items:
$ref: '#/components/schemas/GoalDimension'
type: array
title: Goal Dimensions[]
description: >-
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.
default: []
conversation_context:
type: string
title: Conversation Context
description: >-
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.
default: ''
type: object
required:
- file
title: Body_analyze_upload_v1_upload_analyze_post
AnalysisResult:
properties:
signals:
items:
$ref: '#/components/schemas/Signal'
type: array
title: Signals
description: List of all social signals detected in the analyzed video.
examples:
- - 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:
items:
$ref: '#/components/schemas/EngagementStateEntry'
type: array
title: Engagement State
description: >-
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.
examples:
- - end: 5
start: 0
state: engaged
- end: 15
start: 5
state: neutral
feedback:
anyOf:
- $ref: '#/components/schemas/InteractionFeedback'
- type: 'null'
title: Feedback
description: >-
Structured interaction feedback generated from the detected signals
and conversation quality. Present only when feedback is enabled and
either a `conversation_context` or at least one goal dimension was
supplied. A `feedback` result carries a `message` plus the
`active_dimensions` and `primary_signal` it was grounded in; a
`no_feedback` result carries a `reason` instead.
examples:
- active_dimensions:
- clarity
- energy
message: >-
You restarted several phrases and looked away near the end,
while clarity and energy dropped. Pause, choose one direct
sentence, and lead with the main point before adding nuance.
primary_signal: hesitation
type: feedback
conversation_quality:
anyOf:
- $ref: '#/components/schemas/ConversationQuality'
- type: 'null'
title: Conversation Quality
description: >-
Conversation quality with overall and time-varying scores. Present
whenever it is explicitly requested via the include[] parameter —
including when all signals are neutral or no signals were detected,
in which case scores fall back to the neutral midpoint of 50. When
present, every dimension score and the overall quality index are
guaranteed to be numeric (50 indicates no diagnostic evidence for
that dimension).
examples:
- 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
type: object
required:
- signals
title: AnalysisResult
description: Contains the result of the video analysis.
ErrorResponse:
properties:
error_id:
type: string
title: Error Id
description: Machine-readable error code (e.g. 'ih2001').
correlation_id:
anyOf:
- type: string
- type: 'null'
title: Correlation Id
description: >-
Unique identifier assigned to each API request or WebSocket
connection. It allows both the client and the service to trace a
specific interaction through logs and internal systems. If you
contact support about a particular request or connection, providing
the correlation_id allows the team to locate the relevant records
quickly. Clients who may later request deletion of data for privacy
reasons should store the correlation_id, as it can be used to
identify and remove data associated with that specific interaction.
link:
anyOf:
- type: string
- type: 'null'
title: Link
description: URL to additional information about this error.
message:
anyOf:
- type: string
- type: 'null'
title: Message
description: >-
Error explanation. Contains any additional details about the
specific error that was encountered.
type: object
required:
- error_id
title: ErrorResponse
description: >-
Structured error returned by all HTTP error paths.
Only ``error_id`` is required. The other fields are included when
available.
IncludeFlag:
type: string
enum:
- conversation_quality_overall
- conversation_quality_timeline
title: IncludeFlag
description: >-
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.
GoalDimension:
type: string
enum:
- clarity
- authority
- energy
- rapport
- learning
title: GoalDimension
description: >-
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
Signal:
properties:
type:
$ref: '#/components/schemas/SignalType'
title: Signal Type
description: >-
The name of the detected social signal (e.g., 'agreement',
'confusion').
examples:
- agreement
start:
type: number
title: Start Time
description: Start time of the signal in seconds relative to the video start.
examples:
- 10
end:
type: number
title: End Time
description: End time of the signal in seconds relative to the video start.
examples:
- 15
probability:
anyOf:
- $ref: '#/components/schemas/Probability'
- type: 'null'
title: Probability
description: 'Confidence level of the detected signal: high, medium, or low.'
examples:
- high
rationale:
anyOf:
- type: string
- type: 'null'
title: Rationale
description: >-
A concise, evidence-based explanation of why the signal was
detected. Grounded in observable cues from the video.
examples:
- Subject nodded repeatedly while maintaining eye contact.
modality:
items:
type: string
type: array
title: Modality
description: >-
Analysis modalities used to detect this signal. Can contain 'audio',
'video', or both.
examples:
- - audio
- video
type: object
required:
- type
- start
- end
title: Signal
description: Detected signal.
EngagementStateEntry:
properties:
state:
$ref: '#/components/schemas/EngagementLevel'
title: State
description: The engagement level for this time window.
examples:
- engaged
start:
type: number
title: Start Time
description: Start time in seconds relative to the video start.
examples:
- 0
end:
type: number
title: End Time
description: End time in seconds relative to the video start.
examples:
- 5
type: object
required:
- state
- start
- end
title: EngagementStateEntry
description: A contiguous time window with a single engagement state.
InteractionFeedback:
properties:
type:
$ref: '#/components/schemas/FeedbackType'
title: Type
description: >-
Whether a feedback message was produced or skipped for lack of
evidence.
examples:
- feedback
message:
anyOf:
- type: string
- type: 'null'
title: Message
description: >-
The single concise feedback message with one concrete next step.
Present when `type` is `feedback`.
examples:
- >-
You restarted several phrases and looked away near the end, while
clarity dropped. Pause, choose one direct sentence, and lead with
the main point.
active_dimensions:
items:
$ref: '#/components/schemas/GoalDimension'
type: array
title: Active Dimensions
description: >-
The active goal dimensions the coach used to ground the feedback.
Populated when `type` is `feedback`.
examples:
- - clarity
- energy
primary_signal:
anyOf:
- $ref: '#/components/schemas/SignalType'
- type: 'null'
title: Primary Signal
description: >-
The main social signal the feedback is built around. Present when
`type` is `feedback` and a primary signal was chosen.
examples:
- hesitation
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
description: >-
A brief reason why no feedback was produced. Present when `type` is
`no_feedback`.
examples:
- No signals relevant to the active goal dimensions were detected.
type: object
required:
- type
title: InteractionFeedback
description: |-
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.
ConversationQuality:
properties:
overall:
$ref: '#/components/schemas/ConversationQualityValues'
title: Overall
description: >-
Aggregated conversation quality scores for the entire conversation.
Added when `conversation_quality_overall` is included in the Include
flags.
timeline:
items:
$ref: '#/components/schemas/ConversationQualityTimelineEntry'
type: array
title: Timeline
description: >-
Time-varying conversation quality scores in consecutive,
non-overlapping windows. Added when `conversation_quality_timeline`
is included in the Include flags.
type: object
required:
- overall
- timeline
title: ConversationQuality
description: >-
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.
SignalType:
type: string
enum:
- agreement
- confidence
- confusion
- disagreement
- disengagement
- engagement
- frustration
- hesitation
- interest
- skepticism
- stress
- uncertainty
title: SignalType
description: Enumeration of supported social signals.
Probability:
type: string
enum:
- high
- medium
- low
title: Probability
description: Signal probability levels.
EngagementLevel:
type: string
enum:
- engaged
- neutral
- disengaged
title: EngagementLevel
description: Engagement state levels derived from model signals.
FeedbackType:
type: string
enum:
- feedback
- no_feedback
title: FeedbackType
description: >-
Discriminator for the structured interaction-feedback result.
``feedback`` carries a usable coaching message; ``no_feedback`` is
returned
when there was not enough relevant evidence to coach on.
ConversationQualityValues:
properties:
quality_index:
type: number
title: Quality Index
description: >-
Overall conversation quality index (0-100). Mean of the five
dimension scores.
examples:
- 72
clarity:
type: number
title: Clarity
description: >-
Clarity / Structure dimension score (0-100). Returns 50 when no
diagnostic evidence is available for this dimension.
examples:
- 67
authority:
type: number
title: Authority
description: >-
Authority / Credibility dimension score (0-100). Returns 50 when no
diagnostic evidence is available for this dimension.
examples:
- 68
energy:
type: number
title: Energy
description: >-
Energy / Presence dimension score (0-100). Returns 50 when no
diagnostic evidence is available for this dimension.
examples:
- 80
rapport:
type: number
title: Rapport
description: >-
Rapport / Relational Safety dimension score (0-100). Returns 50 when
no diagnostic evidence is available for this dimension.
examples:
- 75
learning:
type: number
title: Learning
description: >-
Learning / Exploration dimension score (0-100). Returns 50 when no
diagnostic evidence is available for this dimension.
examples:
- 70
type: object
required:
- quality_index
- clarity
- authority
- energy
- rapport
- learning
title: ConversationQualityValues
description: >-
Aggregated conversation quality scores for the entire conversation.
Added when `conversation_quality_overall` is included in the Include
flags.
ConversationQualityTimelineEntry:
properties:
start:
type: number
title: Start Time
description: Window start time in seconds, in absolute session-cumulative time.
examples:
- 0
end:
type: number
title: End Time
description: Window end time in seconds, in absolute session-cumulative time.
examples:
- 10
values:
$ref: '#/components/schemas/ConversationQualityValues'
title: Values
description: Conversation quality dimension scores for this time window.
type: object
required:
- start
- end
- values
title: ConversationQualityTimelineEntry
description: Conversation quality values for a single time window in the timeline.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API key authentication. Include your API key in the Authorization header
as 'Bearer '.
````