> ## 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.
# Inter-2 Upload Analyze
> Submit an audio or video file for analysis by an Inter-2 model as an asynchronous job. Answers 202 with the queued job envelope, or 200 with the finished job when `wait_seconds` is set and the job finishes in time.
#### Response Headers
Unique identifier for the request. Include this when contacting support.
Example: `f47ac10b-58cc-4372-a567-0e02b2c3d479`
## OpenAPI
````yaml post /v2/upload/analyze
openapi: 3.1.0
info:
title: interhuman-api
version: 2.10.1
servers:
- url: https://api.interhuman.ai
description: Production environment
security: []
paths:
/v2/upload/analyze:
post:
summary: Submit Upload Job
description: >-
Submit an audio or video file for analysis by an Inter-2 model as an
asynchronous job. Answers 202 with the queued job envelope, or 200 with
the finished job when `wait_seconds` is set and the job finishes in
time.
operationId: submit_upload_job_v2_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
- name: X-Interhuman-SDK
in: header
required: false
description: >-
Optional client SDK identity as `/` (e.g.
`typescript/0.13.0`), sent automatically by the first-party
Interhuman SDKs. It is recorded in Interhuman telemetry so SDK
adoption and version distribution are visible. The value is
self-declared and not authenticated: it never affects
authentication, authorization, scopes, quotas, or billing, and a
missing, malformed, or unrecognized value is ignored rather than
rejected.
schema:
type: string
title: X-Interhuman-SDK
requestBody:
content:
multipart/form-data:
schema:
$ref: >-
#/components/schemas/Body_submit_upload_job_v2_upload_analyze_post
required: true
responses:
'200':
description: >-
The job reached a terminal state within `wait_seconds`: `completed`
with `result`, or `failed` with `error`.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadJobResponse'
example:
job_id: 3f1c2b7a9d4e4c8fa1b2c3d4e5f60718
status: completed
model: inter-2
created_at: '2026-09-11T10:00:00Z'
expires_at: '2026-09-11T11:00:00Z'
status_url: /v2/upload/jobs/3f1c2b7a9d4e4c8fa1b2c3d4e5f60718
result:
duration_seconds: 10
window_seconds: 5
windows:
- index: 0
start_seconds: 0
end_seconds: 5
engagement_status: engaged
signals:
- type: confidence
start: 0
end: 5
probability: high
rationale: >-
Steady eye contact, upright posture and a firm, even
tone throughout.
modality:
- video
- index: 1
start_seconds: 5
end_seconds: 10
engagement_status: neutral
signals: []
conversation_quality:
overall:
quality_index: 65.5
clarity: 50
authority: 85.7
energy: 91.7
rapport: 50
learning: 50
timeline:
- start: 0
end: 10
values:
quality_index: 65.5
clarity: 50
authority: 85.7
energy: 91.7
rapport: 50
learning: 50
'202':
description: >-
The job was accepted and queued. Poll `status_url` until `status` is
`completed` or `failed`.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadJobResponse'
example:
job_id: 3f1c2b7a9d4e4c8fa1b2c3d4e5f60718
status: queued
model: inter-2
created_at: '2026-09-11T10:00:00Z'
expires_at: '2026-09-11T11:00:00Z'
status_url: /v2/upload/jobs/3f1c2b7a9d4e4c8fa1b2c3d4e5f60718
'400':
description: >-
Bad request. The file is missing (ih4001), the container is not
supported for the model (ih4002), the media is shorter than 3
seconds (ih4007) or longer than the deployment's maximum (ih4004),
`wait_seconds` is out of range or `model` is not a known value
(ih4005), or the model is a reserved value not served on this route
yet (ih4020).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_file:
value:
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'.
model_not_available:
value:
error_id: ih4020
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih4020-model-not-available-on-route
message: >-
The model 'inter-2-deep' is not available on this route
yet. Available models on this route: 'inter-2',
'inter-2-audio'.
unsupported_format:
value:
error_id: ih4002
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih4002-unsupported-file-type
message: >-
Unsupported file type 'image2'. Supported formats are:
wav, flac, mp3, m4a, ogg, webm, mp4.
'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, for
WebSocket connections, as the 'Sec-WebSocket-Protocol:
access_token, ' subprotocol pair).
'403':
description: >-
Forbidden. The credential does not include the scope for the
requested model, `interhumanai.upload.` (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.inter-2-audio' scope.
'413':
description: >-
Payload too large. The 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 media. The file is empty or, for `inter-2`, carries no
video stream (ih5001), cannot be read as a media container (ih5002),
or carries no audio stream (ih5008).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error_id: ih5008
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih5008-no-audio-stream
message: >-
Unable to process the file: it contains no audio stream. The
requested model listens to the audio, so the file must carry
at least one audio track.
'429':
description: >-
Too many requests or quota exceeded: the concurrent-request limit
(ih3002), the account's usage limit (ih3003), or the client token's
video budget (ih3006).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
concurrent_request_limit:
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:
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.
token_video_budget:
value:
error_id: ih3006
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih3006-token-video-budget-exhausted
message: >-
This access token has reached its video processing budget.
Mint a new client token to continue.
'503':
description: >-
Service unavailable. The job store cannot be reached (ih1003), no
backend serves the requested model on this deployment (ih1003), or
this instance holds as many jobs as it may (ih1002); retry after a
short delay.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error_id: ih1003
correlation_id: 550e8400-e29b-41d4-a716-446655440000
link: >-
https://docs.interhuman.ai/api-reference/error-handling#ih1003-dependency-unavailable
message: >-
A required dependency is temporarily unavailable. Please try
again later.
security:
- bearerAuth: []
components:
schemas:
Body_submit_upload_job_v2_upload_analyze_post:
properties:
file:
type: string
contentMediaType: application/octet-stream
title: File
description: >-
The file to analyze. For `inter-2`: an mp4, mov, avi, mkv, webm or
mpeg-ts video carrying both a video and an audio track. For
`inter-2-audio`: wav, flac, mp3, m4a, ogg, or a webm or mp4 file
with an audio track (Inter-2 Audio is available to select
customers). At least 3 seconds of media, at most 32 MB, and no
longer than the deployment's maximum duration (30 minutes by
default).
model:
$ref: '#/components/schemas/UploadModel'
description: >-
The Inter-2 model to analyze with. `inter-2` and `inter-2-audio` are
served; `inter-2-deep` is reserved and answers ih4020 until
available on this route. The credential must carry the
`interhumanai.upload.` scope for the model it names. Inter-2
Audio is available to select customers; to request access, contact
Interhuman support.
wait_seconds:
type: integer
minimum: 0
title: Wait Seconds
description: >-
Hold the request open for up to this many seconds waiting for the
job to finish. `0` (the default) answers 202 at once. Values above
the deployment's bound are rejected with ih4005.
default: 0
include[]:
items:
$ref: '#/components/schemas/IncludeFlag'
type: array
title: Include[]
description: >-
Optional flags naming the Conversation Quality Index sections the
job's result should carry: `conversation_quality_overall` and/or
`conversation_quality_timeline`, the same values as `POST
/v1/upload/analyze`. The index is computed over the whole file once
the job completes. When omitted, the result carries no
`conversation_quality` block.
default: []
type: object
required:
- file
- model
title: Body_submit_upload_job_v2_upload_analyze_post
UploadJobResponse:
properties:
job_id:
type: string
title: Job ID
description: Identifier of the job. Use it with ``GET /v2/upload/jobs/{job_id}``.
examples:
- 3f1c2b7a9d4e4c8fa1b2c3d4e5f60718
status:
$ref: '#/components/schemas/UploadJobStatus'
title: Status
description: >-
Where the job is: ``queued`` (accepted, not started), ``running``,
``completed`` (``result`` is set) or ``failed`` (``error`` is set).
examples:
- queued
model:
$ref: '#/components/schemas/UploadModel'
title: Model
description: The model the job was submitted for.
examples:
- inter-2
created_at:
type: string
format: date-time
title: Created At
description: When the job was accepted (UTC).
examples:
- '2026-09-11T10:00:00Z'
expires_at:
type: string
format: date-time
title: Expires At
description: >-
When the job record, and its result, stop being readable (UTC). A
read after this time answers ``ih4021``.
examples:
- '2026-09-11T11:00:00Z'
status_url:
type: string
title: Status URL
description: >-
Path of the job's status resource, relative to the API base URL:
``/v2/upload/jobs/{job_id}``.
examples:
- /v2/upload/jobs/3f1c2b7a9d4e4c8fa1b2c3d4e5f60718
result:
anyOf:
- $ref: '#/components/schemas/UploadJobResult'
- type: 'null'
title: Result
description: The analysis. Present only when ``status`` is ``completed``.
error:
anyOf:
- $ref: '#/components/schemas/ErrorResponse'
- type: 'null'
title: Error
description: >-
Why the job failed, as the API's standard error body. Present only
when ``status`` is ``failed``.
type: object
required:
- job_id
- status
- model
- created_at
- expires_at
- status_url
title: UploadJobResponse
description: The job envelope, returned by both v2 upload routes.
ErrorResponse:
properties:
error_id:
type: string
title: Error Id
description: Machine-readable error code.
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.
UploadModel:
type: string
enum:
- inter-2
- inter-2-audio
- inter-2-deep
title: UploadModel
description: >-
Inter-2 models a ``POST /v2/upload/analyze`` request can name.
The path version names the contract (engagement plus signals with a
rationale, per window); ``model`` names the engine that reads the file.
Inter-2 Audio is available to select customers; to request access,
contact
Interhuman support.
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.
UploadJobStatus:
type: string
enum:
- queued
- running
- completed
- failed
title: UploadJobStatus
description: >-
Lifecycle of an upload job.
``queued`` and ``running`` are transient; ``completed`` and ``failed``
are
terminal, and the record stays readable until ``expires_at``.
UploadJobResult:
properties:
duration_seconds:
type: number
title: Duration
description: Length of the analyzed media, in seconds.
examples:
- 60
window_seconds:
type: number
title: Window Length
description: Length of each analysis window, in seconds.
examples:
- 5
windows:
items:
$ref: '#/components/schemas/UploadJobWindow'
type: array
title: Windows
description: Per-window analyses, in file order.
conversation_quality:
anyOf:
- $ref: '#/components/schemas/UploadJobConversationQuality'
- type: 'null'
title: Conversation Quality
description: >-
The Conversation Quality Index over the whole file, in the sections
the submit's ``include[]`` flags asked for. Absent when no flag was
sent. When requested it is present even for a file with no detected
signals: every dimension then reads the neutral 50.
type: object
required:
- duration_seconds
- window_seconds
title: UploadJobResult
description: 'The result of a completed upload job: one entry per analyzed window.'
UploadJobWindow:
properties:
index:
type: integer
title: Index
description: Zero-based position of this window in the file.
examples:
- 0
start_seconds:
type: number
title: Start
description: Where the window starts, in seconds from the start of the file.
examples:
- 0
end_seconds:
type: number
title: End
description: Where the window ends, in seconds from the start of the file.
examples:
- 5
engagement_status:
$ref: '#/components/schemas/EngagementLevel'
title: Engagement Status
description: The engagement level the model read over this window.
examples:
- engaged
signals:
items:
$ref: '#/components/schemas/Signal'
type: array
title: Signals
description: >-
Social signals detected in this window. Each carries the window's
span as its start and end, and ``modality`` names the evidence the
model read (``["video"]`` for ``inter-2``, ``["audio"]`` for
``inter-2-audio``).
type: object
required:
- index
- start_seconds
- end_seconds
- engagement_status
title: UploadJobWindow
description: The analysis of one fixed-length window of the file.
UploadJobConversationQuality:
properties:
overall:
anyOf:
- $ref: '#/components/schemas/ConversationQualityValues'
- type: 'null'
title: Overall
description: >-
Aggregated conversation quality scores for the whole file. Present
when ``include[]`` named ``conversation_quality_overall``.
timeline:
anyOf:
- items:
$ref: '#/components/schemas/ConversationQualityTimelineEntry'
type: array
- type: 'null'
title: Timeline
description: >-
Time-varying conversation quality scores in consecutive,
non-overlapping periods across the file. Present when ``include[]``
named ``conversation_quality_timeline``.
type: object
title: UploadJobConversationQuality
description: >-
The Conversation Quality Index of a completed job, in the sections
requested.
Computed once, when the job completes, from every window's signals and
engagement status over the whole file. Each section is present only when
the submit asked for it with the matching ``include[]`` flag, so a
caller
reads exactly what it requested; when neither flag was sent the block is
absent from the result altogether.
EngagementLevel:
type: string
enum:
- engaged
- neutral
- disengaged
title: EngagementLevel
description: Engagement state levels derived from model signals.
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 that detected this signal, naming the source of
the evidence. When several tracks detect the same signal, every
contributing modality is included.
examples:
- - video
type: object
required:
- type
- start
- end
title: Signal
description: Detected signal.
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.
SignalType:
type: string
enum:
- agreement
- confidence
- confusion
- disagreement
- disengagement
- engagement
- frustration
- hesitation
- interest
- skepticism
- stress
- tension
- uncertainty
title: SignalType
description: Enumeration of supported social signals.
Probability:
type: string
enum:
- high
- medium
- low
title: Probability
description: Signal probability levels.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API key authentication. Include your API key in the Authorization header
as 'Bearer '.
````