> ## Documentation Index
> Fetch the complete documentation index at: https://beta.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.8.0
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-audio
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 pace and a firm, even tone throughout.
modality:
- audio
- index: 1
start_seconds: 5
end_seconds: 10
engagement_status: neutral
signals: []
'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-audio
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 (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' is not available on this route yet.
Available models on this route: '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 (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. This
route analyzes 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-audio`: wav, flac, mp3, m4a, ogg,
or a webm or mp4 file with an audio track. 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-audio` is served;
`inter-2` and `inter-2-deep` are reserved and answer ih4020 until
available on this route. The credential must carry the
`interhumanai.upload.` scope for the model it names.
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
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-audio
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.
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.
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 (``["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.
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.
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 '.
````