> ## 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. # Streaming Analyze > Analyze a video stream. ## AsyncAPI ````yaml stream_analyze_v1 id: stream_analyze_v1 title: stream_analyze_v1 description: Analyze a video stream. servers: - id: production protocol: ws host: api.interhuman.ai bindings: [] variables: [] address: /v1/stream/analyze parameters: [] bindings: - protocol: ws version: 0.1.0 value: headers: type: object properties: X-Client-Request-Id: type: string 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. Sec-WebSocket-Protocol: type: string description: >- Authentication credential supplied during the WebSocket handshake. Pass your API key here when your client cannot set an `Authorization` header for WebSocket connections. examples: &ref_0 - schemaProperties: - name: headers type: object required: false properties: - name: X-Client-Request-Id type: string 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. required: false - name: Sec-WebSocket-Protocol type: string description: >- Authentication credential supplied during the WebSocket handshake. Pass your API key here when your client cannot set an `Authorization` header for WebSocket connections. examples: *ref_0 required: false operations: - &ref_40 id: receive_handler title: Receive_handler description: '' type: receive messages: - &ref_51 id: stream_video_message payload: - format: binary x-parser-schema-id: name: Video (bytes) description: >- Binary video segment sent by the client for analysis. Each segment must not exceed 32MB. Accepts the following formats: mp4, avi, mov, mkv, mpeg-ts, mpeg-2-ts, webm. headers: [] jsonPayloadSchema: format: binary x-parser-schema-id: title: Video (bytes) description: >- Binary video segment sent by the client for analysis. Each segment must not exceed 32MB. Accepts the following formats: mp4, avi, mov, mkv, mpeg-ts, mpeg-2-ts, webm. example: '[]' bindings: [] extensions: - id: x-parser-unique-object-id value: stream_video_message - id: x-parser-message-name value: stream_video_message bindings: [] extensions: &ref_2 - id: x-parser-unique-object-id value: stream_analyze_v1 - &ref_41 id: session_config_handler title: Session_config_handler description: '' type: receive messages: - &ref_52 id: stream_session_config_v1_message payload: - name: Session Config description: >- Optional caller-supplied session configuration. This message can be sent at any time to update the configuration. type: object properties: - name: include type: array title: Include description: >- Flags indicating which conversation quality sections to include in result messages. Accepted values: - `conversation_quality_overall`: periodically report the overall conversation quality scores, cumulative across all video processed so far in the session. - `conversation_quality_timeline`: periodically report the per-window conversation quality scores. When omitted, no optional sections are included. Unknown values are ignored. examples: &ref_1 - - conversation_quality_overall required: false properties: - name: item type: string 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. enumValues: - conversation_quality_overall - conversation_quality_timeline required: false headers: [] jsonPayloadSchema: additionalProperties: false description: >- Optional caller-supplied session configuration. This message can be sent at any time to update the configuration. examples: - include: - conversation_quality_overall properties: include: description: >- Flags indicating which conversation quality sections to include in result messages. Accepted values: - `conversation_quality_overall`: periodically report the overall conversation quality scores, cumulative across all video processed so far in the session. - `conversation_quality_timeline`: periodically report the per-window conversation quality scores. When omitted, no optional sections are included. Unknown values are ignored. examples: *ref_1 items: &ref_27 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. enum: - conversation_quality_overall - conversation_quality_timeline title: IncludeFlag type: string x-parser-schema-id: IncludeFlag title: Include type: array x-parser-schema-id: title: Session Config type: object x-parser-schema-id: StreamSessionConfigV1 title: Session Config description: >- Optional caller-supplied session configuration. This message can be sent at any time to update the configuration. example: |- { "include": [ "conversation_quality_overall" ] } bindings: [] extensions: - id: x-parser-unique-object-id value: stream_session_config_v1_message - id: x-parser-message-name value: stream_session_config_v1_message bindings: [] extensions: *ref_2 - &ref_42 id: output_conversation_quality_updated title: Output_conversation_quality_updated description: Conversation Quality Updated type: send messages: - &ref_53 id: conversation_quality_updated_v1_message payload: - name: Conversation Quality Updated description: >- Carries Conversation Quality Index values for the most recently closed cadence period. Emitted at most once per period and only when the caller has set at least one CQI ``include`` flag on the session-config message. ``data.overall`` is cumulative across the whole session up to the end of the just-closed period and is included whenever ``include: ["conversation_quality_overall"]`` was supplied. ``data.timeline`` carries a single entry covering the just-closed period and is included whenever ``include: ["conversation_quality_timeline"]`` was supplied — periods with no analyzer-reported signals still emit the timeline; its scores reflect any engagement contribution and fall back to all-50 defaults when nothing contributes, so the requested section is always present. type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_9 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``conversation_quality.updated``. required: false - name: data type: object title: ConversationQualityUpdatedV1Data description: >- Payload for the ``conversation_quality.updated`` event. ``overall`` is non-null when the session-config message specifies ``include: ["conversation_quality_overall"]``, and ``timeline`` is non-null when it specifies ``include: ["conversation_quality_timeline"]``. Either or both may be ``null`` — the event is still emitted as long as at least one CQI flag was requested and the cadence rules permit it. required: true properties: - name: overall type: object title: ConversationQualityValues description: >- Aggregated conversation quality scores for the entire conversation. Added when `conversation_quality_overall` is included in the Include flags. required: false properties: - name: quality_index type: number title: Quality Index description: >- Overall conversation quality index (0-100). Mean of the five dimension scores. examples: &ref_3 - 72 required: true - name: clarity type: number title: Clarity description: >- Clarity / Structure dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: &ref_4 - 67 required: true - name: authority type: number title: Authority description: >- Authority / Credibility dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: &ref_5 - 68 required: true - name: energy type: number title: Energy description: >- Energy / Presence dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: &ref_6 - 80 required: true - name: 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: &ref_7 - 75 required: true - name: learning type: number title: Learning description: >- Learning / Exploration dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: &ref_8 - 70 required: true - name: timeline type: array title: Timeline description: >- Per-period conversation quality entries. The stream emits a single entry spanning the most recently closed cadence period. Non-null when ``include: ["conversation_quality_timeline"]`` was supplied on the session-config message *and* the period contained at least one analyzer-reported signal; ``null`` otherwise. required: false properties: - name: start type: number title: Start Time description: >- Window start time in seconds, in absolute session-cumulative time. examples: &ref_10 - 0 required: true - name: end type: number title: End Time description: >- Window end time in seconds, in absolute session-cumulative time. examples: &ref_11 - 10 required: true - name: values type: object title: ConversationQualityValues description: >- Aggregated conversation quality scores for the entire conversation. Added when `conversation_quality_overall` is included in the Include flags. required: true properties: - name: quality_index type: number title: Quality Index description: >- Overall conversation quality index (0-100). Mean of the five dimension scores. examples: *ref_3 required: true - name: clarity type: number title: Clarity description: >- Clarity / Structure dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_4 required: true - name: authority type: number title: Authority description: >- Authority / Credibility dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_5 required: true - name: energy type: number title: Energy description: >- Energy / Presence dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_6 required: true - name: 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: *ref_7 required: true - name: learning type: number title: Learning description: >- Learning / Exploration dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_8 required: true headers: [] jsonPayloadSchema: description: >- v1 ``conversation_quality.updated`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_9 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: conversation_quality.updated default: conversation_quality.updated description: >- Discriminator identifying the message kind. For this message it is always ``conversation_quality.updated``. title: Type type: string x-parser-schema-id: data: description: >- Payload for the ``conversation_quality.updated`` event. ``overall`` is non-null when the session-config message specifies ``include: ["conversation_quality_overall"]``, and ``timeline`` is non-null when it specifies ``include: ["conversation_quality_timeline"]``. Either or both may be ``null`` — the event is still emitted as long as at least one CQI flag was requested and the cadence rules permit it. properties: overall: &ref_12 description: >- Aggregated conversation quality scores for the entire conversation. Added when `conversation_quality_overall` is included in the Include flags. properties: quality_index: description: >- Overall conversation quality index (0-100). Mean of the five dimension scores. examples: *ref_3 title: Quality Index type: number x-parser-schema-id: clarity: description: >- Clarity / Structure dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_4 title: Clarity type: number x-parser-schema-id: authority: description: >- Authority / Credibility dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_5 title: Authority type: number x-parser-schema-id: energy: description: >- Energy / Presence dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_6 title: Energy type: number x-parser-schema-id: rapport: description: >- Rapport / Relational Safety dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_7 title: Rapport type: number x-parser-schema-id: learning: description: >- Learning / Exploration dimension score (0-100). Returns 50 when no diagnostic evidence is available for this dimension. examples: *ref_8 title: Learning type: number x-parser-schema-id: required: - quality_index - clarity - authority - energy - rapport - learning title: ConversationQualityValues type: object x-parser-schema-id: ConversationQualityValues timeline: anyOf: - items: description: >- Conversation quality values for a single time window in the timeline. properties: start: description: >- Window start time in seconds, in absolute session-cumulative time. examples: *ref_10 title: Start Time type: number x-parser-schema-id: end: description: >- Window end time in seconds, in absolute session-cumulative time. examples: *ref_11 title: End Time type: number x-parser-schema-id: values: *ref_12 required: - start - end - values title: ConversationQualityTimelineEntry type: object x-parser-schema-id: ConversationQualityTimelineEntry type: array x-parser-schema-id: - type: 'null' x-parser-schema-id: description: >- Per-period conversation quality entries. The stream emits a single entry spanning the most recently closed cadence period. Non-null when ``include: ["conversation_quality_timeline"]`` was supplied on the session-config message *and* the period contained at least one analyzer-reported signal; ``null`` otherwise. title: Timeline x-parser-schema-id: title: ConversationQualityUpdatedV1Data type: object x-parser-schema-id: ConversationQualityUpdatedV1Data required: - timestamp - data title: ConversationQualityUpdatedV1Message type: object x-parser-schema-id: ConversationQualityUpdatedV1Message title: Conversation Quality Updated description: >- Carries Conversation Quality Index values for the most recently closed cadence period. Emitted at most once per period and only when the caller has set at least one CQI ``include`` flag on the session-config message. ``data.overall`` is cumulative across the whole session up to the end of the just-closed period and is included whenever ``include: ["conversation_quality_overall"]`` was supplied. ``data.timeline`` carries a single entry covering the just-closed period and is included whenever ``include: ["conversation_quality_timeline"]`` was supplied — periods with no analyzer-reported signals still emit the timeline; its scores reflect any engagement contribution and fall back to all-50 defaults when nothing contributes, so the requested section is always present. example: |- { "type": "conversation_quality.updated", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "overall": { "quality_index": 72, "clarity": 67, "authority": 68, "energy": 80, "rapport": 75, "learning": 70 }, "timeline": [ { "start": 0, "end": 11, "values": { "quality_index": 70, "clarity": 69, "authority": 70, "energy": 78, "rapport": 77, "learning": 68 } } ] } } bindings: [] extensions: - id: x-parser-unique-object-id value: conversation_quality_updated_v1_message - id: x-parser-message-name value: conversation_quality_updated_v1_message bindings: [] extensions: *ref_2 - &ref_43 id: output_coverage_dropped title: Output_coverage_dropped description: Coverage Dropped type: send messages: - &ref_54 id: coverage_dropped_v1_message payload: - name: Coverage Dropped description: >- Reports that analysis coverage was reduced under backpressure. Emitted when the analysis pipeline saturates and has to skip buffered video that no surviving analysis window covers. This is an informational notice, not an error: the session stays open, subsequent windows continue uninterrupted, and the dropped portions of the video are not billed. ``data.ranges`` lists the skipped time ranges in absolute session-cumulative seconds. type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_13 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``coverage.dropped``. required: false - name: data type: object title: CoverageDroppedV1Data description: >- Payload for the ``coverage.dropped`` event. Lists the time ranges that the analysis pipeline skipped when it saturated and shed buffered video. Dropped portions of the video are expected, recoverable degradation — the session stays open and continues analyzing subsequent windows — and they are **not billed**. required: true properties: - name: ranges type: array title: Ranges description: >- Disjoint, ascending time ranges that were dropped without analysis. These portions of the video are not billed. examples: &ref_14 - - end: 10 start: 8 required: true properties: - name: start type: number title: Start description: >- Start of the dropped range, in seconds, in absolute session-cumulative time. examples: &ref_15 - 8 required: true - name: end type: number title: End description: >- End of the dropped range, in seconds, in absolute session-cumulative time. examples: &ref_16 - 10 required: true headers: [] jsonPayloadSchema: description: v1 ``coverage.dropped`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_13 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: coverage.dropped default: coverage.dropped description: >- Discriminator identifying the message kind. For this message it is always ``coverage.dropped``. title: Type type: string x-parser-schema-id: data: description: >- Payload for the ``coverage.dropped`` event. Lists the time ranges that the analysis pipeline skipped when it saturated and shed buffered video. Dropped portions of the video are expected, recoverable degradation — the session stays open and continues analyzing subsequent windows — and they are **not billed**. properties: ranges: description: >- Disjoint, ascending time ranges that were dropped without analysis. These portions of the video are not billed. examples: *ref_14 items: description: >- A single contiguous time range skipped under analysis backpressure. Times are in seconds, in absolute session-cumulative time, matching the timestamps carried by every other v1 envelope. properties: start: description: >- Start of the dropped range, in seconds, in absolute session-cumulative time. examples: *ref_15 title: Start type: number x-parser-schema-id: end: description: >- End of the dropped range, in seconds, in absolute session-cumulative time. examples: *ref_16 title: End type: number x-parser-schema-id: required: - start - end title: CoverageDroppedRangeV1 type: object x-parser-schema-id: CoverageDroppedRangeV1 title: Ranges type: array x-parser-schema-id: required: - ranges title: CoverageDroppedV1Data type: object x-parser-schema-id: CoverageDroppedV1Data required: - timestamp - data title: CoverageDroppedV1Message type: object x-parser-schema-id: CoverageDroppedV1Message title: Coverage Dropped description: >- Reports that analysis coverage was reduced under backpressure. Emitted when the analysis pipeline saturates and has to skip buffered video that no surviving analysis window covers. This is an informational notice, not an error: the session stays open, subsequent windows continue uninterrupted, and the dropped portions of the video are not billed. ``data.ranges`` lists the skipped time ranges in absolute session-cumulative seconds. example: |- { "type": "coverage.dropped", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "ranges": [ { "start": 8, "end": 10 } ] } } bindings: [] extensions: - id: x-parser-unique-object-id value: coverage_dropped_v1_message - id: x-parser-message-name value: coverage_dropped_v1_message bindings: [] extensions: *ref_2 - &ref_44 id: output_engagement_updated title: Output_engagement_updated description: Engagement Updated type: send messages: - &ref_55 id: engagement_updated_v1_message payload: - name: Engagement Updated description: >- Reports a change in engagement state. Emitted once when engagement is first established for the session, and again only when the detected engagement level differs from the most recently emitted level. ``data.start`` uses absolute session-cumulative time. type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_17 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``engagement.updated``. required: false - name: data type: object title: EngagementUpdatedV1Data description: Payload for the ``engagement.updated`` event. required: true properties: - name: state type: string title: EngagementLevel description: Engagement state levels derived from model signals. enumValues: - engaged - neutral - disengaged required: true - name: start type: number title: Start description: >- Time at which ``state`` is first observed, in seconds, in absolute session-cumulative time. examples: &ref_18 - 42 required: true headers: [] jsonPayloadSchema: description: v1 ``engagement.updated`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_17 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: engagement.updated default: engagement.updated description: >- Discriminator identifying the message kind. For this message it is always ``engagement.updated``. title: Type type: string x-parser-schema-id: data: description: Payload for the ``engagement.updated`` event. properties: state: description: Engagement state levels derived from model signals. enum: - engaged - neutral - disengaged title: EngagementLevel type: string x-parser-schema-id: EngagementLevel start: description: >- Time at which ``state`` is first observed, in seconds, in absolute session-cumulative time. examples: *ref_18 title: Start type: number x-parser-schema-id: required: - state - start title: EngagementUpdatedV1Data type: object x-parser-schema-id: EngagementUpdatedV1Data required: - timestamp - data title: EngagementUpdatedV1Message type: object x-parser-schema-id: EngagementUpdatedV1Message title: Engagement Updated description: >- Reports a change in engagement state. Emitted once when engagement is first established for the session, and again only when the detected engagement level differs from the most recently emitted level. ``data.start`` uses absolute session-cumulative time. example: |- { "type": "engagement.updated", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "state": "engaged", "start": 42 } } bindings: [] extensions: - id: x-parser-unique-object-id value: engagement_updated_v1_message - id: x-parser-message-name value: engagement_updated_v1_message bindings: [] extensions: *ref_2 - &ref_45 id: output_error title: Output_error description: Error type: send messages: - &ref_56 id: stream_error_v1_message payload: - name: Error description: >- Reports an error encountered while processing the stream. ``data.code`` carries the machine-readable error id (sub-type), and ``data.segment`` identifies the incoming caller segment when the failure maps to a specific chunk (size validation, quota); analysis-time failures that do not map to one chunk carry ``data.segment: null``. type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_19 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``error``. required: false - name: data type: object title: StreamErrorV1Data description: Payload for the ``error`` event. required: true properties: - name: code type: string title: Code description: Machine-readable error code (e.g. 'ih2001'). examples: &ref_20 - ih6002 required: true - name: message type: string title: Message description: >- Error explanation. Contains any additional details about the specific error that was encountered. required: true - name: link type: string title: Link description: URL to additional information about this error. required: false - name: segment type: integer title: Segment description: >- The incoming caller segment associated with this error, when applicable. ``null`` for errors that are not tied to one specific caller segment. required: false headers: [] jsonPayloadSchema: description: v1 ``error`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_19 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: error default: error description: >- Discriminator identifying the message kind. For this message it is always ``error``. title: Type type: string x-parser-schema-id: data: description: Payload for the ``error`` event. properties: code: description: Machine-readable error code (e.g. 'ih2001'). examples: *ref_20 title: Code type: string x-parser-schema-id: message: description: >- Error explanation. Contains any additional details about the specific error that was encountered. title: Message type: string x-parser-schema-id: link: anyOf: - type: string x-parser-schema-id: - type: 'null' x-parser-schema-id: description: URL to additional information about this error. title: Link x-parser-schema-id: segment: anyOf: - type: integer x-parser-schema-id: - type: 'null' x-parser-schema-id: description: >- The incoming caller segment associated with this error, when applicable. ``null`` for errors that are not tied to one specific caller segment. title: Segment x-parser-schema-id: required: - code - message title: StreamErrorV1Data type: object x-parser-schema-id: StreamErrorV1Data required: - timestamp - data title: StreamErrorV1Message type: object x-parser-schema-id: StreamErrorV1Message title: Error description: >- Reports an error encountered while processing the stream. ``data.code`` carries the machine-readable error id (sub-type), and ``data.segment`` identifies the incoming caller segment when the failure maps to a specific chunk (size validation, quota); analysis-time failures that do not map to one chunk carry ``data.segment: null``. example: |- { "type": "error", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "code": "ih6002", "message": "WebSocket message too large. Individual video chunks must not exceed 32 MB.", "link": "https://docs.interhuman.ai/api-reference/error-handling#ih6002-message-too-large", "segment": 2 } } bindings: [] extensions: - id: x-parser-unique-object-id value: stream_error_v1_message - id: x-parser-message-name value: stream_error_v1_message bindings: [] extensions: *ref_2 - &ref_46 id: output_session_ready title: Output_session_ready description: Session Ready type: send messages: - &ref_57 id: session_ready_v1_message payload: - name: Session Ready description: >- Acknowledges that the v1 stream session is established. Emitted exactly once per session, immediately after the server accepts the WebSocket handshake. Carries the session-level contract (idle / max-duration timeouts, segment size and duration constraints, supported session-config options) so the caller can adapt its producer side without round-tripping rejections. Sessions that fail to fully establish close without this envelope; a client that has not seen ``session.ready`` must assume the session is not ready to receive video. type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_21 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``session.ready``. required: false - name: data type: object title: SessionReadyV1Data description: >- Payload for the ``session.ready`` event. Carries connection-level metadata describing the limits and supported configuration of the just-established session. Field values reflect the active server-side configuration at connect time; a session that spans a configuration change continues to be governed by the values reported here. required: true properties: - name: session_idle_timeout_seconds type: integer title: Session Idle Timeout Seconds description: >- Number of seconds the server allows the session to stay idle (no inbound frames) before it closes the connection with ``ih6003``. A value of ``0`` indicates the idle timeout is disabled for this session. examples: &ref_22 - 300 required: true - name: session_max_duration_seconds type: integer title: Session Max Duration Seconds description: >- Maximum total duration in seconds the server allows the session to remain open before closing the connection with ``ih6004``. A value of ``0`` indicates the maximum duration is disabled for this session. examples: &ref_23 - 3600 required: true - name: max_segment_duration_seconds type: number title: Max Segment Duration Seconds description: >- Maximum probed duration in seconds of a single inbound video chunk, or ``null`` when no fixed duration cap applies (the size cap in ``max_segment_size_bytes`` is the binding limit for long chunks). required: false - name: min_segment_size_bytes type: integer title: Min Segment Size Bytes description: >- Minimum size in bytes of a single inbound video chunk. Zero-byte frames are rejected and never reach analysis. examples: &ref_24 - 1 required: true - name: max_segment_size_bytes type: integer title: Max Segment Size Bytes description: >- Maximum size in bytes of a single inbound video chunk. Chunks larger than this are rejected with ``ih6002``. examples: &ref_25 - 33554432 required: true - name: supported_session_config_options type: object title: SessionReadyConfigOptionsV1 description: >- Supported session-config options advertised on ``session.ready``. Mirrors the field names of :class:`StreamSessionConfigV1`. Each list enumerates the values the server will accept on an inbound ``stream_session_config_v1`` text frame so a client can render UI or validate config locally without round-tripping rejections. required: true properties: - name: include type: array title: Include description: >- Supported values for the ``include`` field of :class:`StreamSessionConfigV1`. examples: &ref_26 - - conversation_quality_overall - conversation_quality_timeline required: true properties: - name: item type: string 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. enumValues: - conversation_quality_overall - conversation_quality_timeline required: false headers: [] jsonPayloadSchema: description: v1 ``session.ready`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_21 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: session.ready default: session.ready description: >- Discriminator identifying the message kind. For this message it is always ``session.ready``. title: Type type: string x-parser-schema-id: data: description: >- Payload for the ``session.ready`` event. Carries connection-level metadata describing the limits and supported configuration of the just-established session. Field values reflect the active server-side configuration at connect time; a session that spans a configuration change continues to be governed by the values reported here. properties: session_idle_timeout_seconds: description: >- Number of seconds the server allows the session to stay idle (no inbound frames) before it closes the connection with ``ih6003``. A value of ``0`` indicates the idle timeout is disabled for this session. examples: *ref_22 minimum: 0 title: Session Idle Timeout Seconds type: integer x-parser-schema-id: session_max_duration_seconds: description: >- Maximum total duration in seconds the server allows the session to remain open before closing the connection with ``ih6004``. A value of ``0`` indicates the maximum duration is disabled for this session. examples: *ref_23 minimum: 0 title: Session Max Duration Seconds type: integer x-parser-schema-id: max_segment_duration_seconds: anyOf: - type: number x-parser-schema-id: - type: 'null' x-parser-schema-id: description: >- Maximum probed duration in seconds of a single inbound video chunk, or ``null`` when no fixed duration cap applies (the size cap in ``max_segment_size_bytes`` is the binding limit for long chunks). title: Max Segment Duration Seconds x-parser-schema-id: min_segment_size_bytes: description: >- Minimum size in bytes of a single inbound video chunk. Zero-byte frames are rejected and never reach analysis. examples: *ref_24 minimum: 1 title: Min Segment Size Bytes type: integer x-parser-schema-id: max_segment_size_bytes: description: >- Maximum size in bytes of a single inbound video chunk. Chunks larger than this are rejected with ``ih6002``. examples: *ref_25 minimum: 1 title: Max Segment Size Bytes type: integer x-parser-schema-id: supported_session_config_options: description: >- Supported session-config options advertised on ``session.ready``. Mirrors the field names of :class:`StreamSessionConfigV1`. Each list enumerates the values the server will accept on an inbound ``stream_session_config_v1`` text frame so a client can render UI or validate config locally without round-tripping rejections. properties: include: description: >- Supported values for the ``include`` field of :class:`StreamSessionConfigV1`. examples: *ref_26 items: *ref_27 title: Include type: array x-parser-schema-id: required: - include title: SessionReadyConfigOptionsV1 type: object x-parser-schema-id: SessionReadyConfigOptionsV1 required: - session_idle_timeout_seconds - session_max_duration_seconds - min_segment_size_bytes - max_segment_size_bytes - supported_session_config_options title: SessionReadyV1Data type: object x-parser-schema-id: SessionReadyV1Data required: - timestamp - data title: SessionReadyV1Message type: object x-parser-schema-id: SessionReadyV1Message title: Session Ready description: >- Acknowledges that the v1 stream session is established. Emitted exactly once per session, immediately after the server accepts the WebSocket handshake. Carries the session-level contract (idle / max-duration timeouts, segment size and duration constraints, supported session-config options) so the caller can adapt its producer side without round-tripping rejections. Sessions that fail to fully establish close without this envelope; a client that has not seen ``session.ready`` must assume the session is not ready to receive video. example: |- { "type": "session.ready", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "session_idle_timeout_seconds": 300, "session_max_duration_seconds": 3600, "min_segment_size_bytes": 1, "max_segment_size_bytes": 33554432, "supported_session_config_options": { "include": [ "conversation_quality_overall", "conversation_quality_timeline" ] } } } bindings: [] extensions: - id: x-parser-unique-object-id value: session_ready_v1_message - id: x-parser-message-name value: session_ready_v1_message bindings: [] extensions: *ref_2 - &ref_47 id: output_session_updated title: Output_session_updated description: Session Updated type: send messages: - &ref_58 id: session_updated_v1_message payload: - name: Session Updated description: >- Acknowledges that an inbound ``stream_session_config_v1`` text frame was accepted. Carries the consolidated post-apply config (``include``). type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_28 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``session.updated``. required: false - name: data type: object title: SessionUpdatedV1Data description: >- Payload for the ``session.updated`` event. Carries the consolidated session config that was just accepted, so the caller has a single source of truth for what the server will apply to subsequent analysis windows. Each successful inbound :class:`StreamSessionConfigV1` frame fully replaces the active config — ``include`` here reflects the post-apply state of the session, not a delta against the previous config. required: true properties: - name: include type: array title: Include description: >- Active opt-in conversation quality sub-sections after the config was applied. Empty when no CQI sections are requested. examples: &ref_29 - - conversation_quality_overall required: true properties: - name: item type: string 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. enumValues: - conversation_quality_overall - conversation_quality_timeline required: false headers: [] jsonPayloadSchema: description: v1 ``session.updated`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_28 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: session.updated default: session.updated description: >- Discriminator identifying the message kind. For this message it is always ``session.updated``. title: Type type: string x-parser-schema-id: data: description: >- Payload for the ``session.updated`` event. Carries the consolidated session config that was just accepted, so the caller has a single source of truth for what the server will apply to subsequent analysis windows. Each successful inbound :class:`StreamSessionConfigV1` frame fully replaces the active config — ``include`` here reflects the post-apply state of the session, not a delta against the previous config. properties: include: description: >- Active opt-in conversation quality sub-sections after the config was applied. Empty when no CQI sections are requested. examples: *ref_29 items: *ref_27 title: Include type: array x-parser-schema-id: required: - include title: SessionUpdatedV1Data type: object x-parser-schema-id: SessionUpdatedV1Data required: - timestamp - data title: SessionUpdatedV1Message type: object x-parser-schema-id: SessionUpdatedV1Message title: Session Updated description: >- Acknowledges that an inbound ``stream_session_config_v1`` text frame was accepted. Carries the consolidated post-apply config (``include``). example: |- { "type": "session.updated", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "include": [ "conversation_quality_overall" ] } } bindings: [] extensions: - id: x-parser-unique-object-id value: session_updated_v1_message - id: x-parser-message-name value: session_updated_v1_message bindings: [] extensions: *ref_2 - &ref_48 id: output_signal_detected title: Output_signal_detected description: Signal Detected type: send messages: - &ref_59 id: signal_detected_v1_message payload: - name: Signal Detected description: >- Reports that a social signal has transitioned from inactive to active. Emitted once when the signal type is first detected for the session, and again only when the signal becomes active after a prior ``signal.ended``. ``data.start`` uses absolute session-cumulative time. type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_30 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``signal.detected``. required: false - name: data type: object title: SignalDetectedV1Data description: >- Payload for the ``signal.detected`` event. Carries only a start time — no window end — because the envelope marks the moment the signal transitions from inactive to active. The matching ``signal.ended`` envelope reports the end-time when the signal stops being detected. required: true properties: - name: signal_type type: string title: SignalType description: Enumeration of supported social signals. enumValues: - agreement - confidence - confusion - disagreement - disengagement - engagement - frustration - hesitation - interest - skepticism - stress - uncertainty required: true - name: start type: number title: Start description: >- Time at which the signal first becomes active, in seconds, in absolute session-cumulative time. examples: &ref_31 - 3 required: true - name: probability type: string title: Probability description: Signal probability levels. enumValues: - high - medium - low required: false - name: rationale type: string title: Rationale description: >- A concise, evidence-based explanation of why the signal was detected. Grounded in observable cues from the video. examples: &ref_32 - Subject nodded repeatedly while maintaining eye contact. required: false headers: [] jsonPayloadSchema: description: v1 ``signal.detected`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_30 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: signal.detected default: signal.detected description: >- Discriminator identifying the message kind. For this message it is always ``signal.detected``. title: Type type: string x-parser-schema-id: data: description: >- Payload for the ``signal.detected`` event. Carries only a start time — no window end — because the envelope marks the moment the signal transitions from inactive to active. The matching ``signal.ended`` envelope reports the end-time when the signal stops being detected. properties: signal_type: &ref_34 description: Enumeration of supported social signals. enum: - agreement - confidence - confusion - disagreement - disengagement - engagement - frustration - hesitation - interest - skepticism - stress - uncertainty title: SignalType type: string x-parser-schema-id: SignalType start: description: >- Time at which the signal first becomes active, in seconds, in absolute session-cumulative time. examples: *ref_31 title: Start type: number x-parser-schema-id: probability: &ref_38 description: Signal probability levels. enum: - high - medium - low title: Probability type: string x-parser-schema-id: Probability rationale: anyOf: - type: string x-parser-schema-id: - type: 'null' x-parser-schema-id: description: >- A concise, evidence-based explanation of why the signal was detected. Grounded in observable cues from the video. examples: *ref_32 title: Rationale x-parser-schema-id: required: - signal_type - start title: SignalDetectedV1Data type: object x-parser-schema-id: SignalDetectedV1Data required: - timestamp - data title: SignalDetectedV1Message type: object x-parser-schema-id: SignalDetectedV1Message title: Signal Detected description: >- Reports that a social signal has transitioned from inactive to active. Emitted once when the signal type is first detected for the session, and again only when the signal becomes active after a prior ``signal.ended``. ``data.start`` uses absolute session-cumulative time. example: |- { "type": "signal.detected", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "signal_type": "agreement", "start": 3, "probability": "high", "rationale": "Subject nodded repeatedly while maintaining eye contact." } } bindings: [] extensions: - id: x-parser-unique-object-id value: signal_detected_v1_message - id: x-parser-message-name value: signal_detected_v1_message bindings: [] extensions: *ref_2 - &ref_49 id: output_signal_ended title: Output_signal_ended description: Signal Ended type: send messages: - &ref_60 id: signal_ended_v1_message payload: - name: Signal Ended description: >- Reports that a previously active social signal is no longer active. Emitted when a signal type that was active in the previous analyzed window is not present in the current window. ``data.end`` uses absolute session-cumulative time. type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_33 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``signal.ended``. required: false - name: data type: object title: SignalEndedV1Data description: >- Payload for the ``signal.ended`` event. Carries only an end time — no start or window — because the envelope marks the moment the signal transitions from active to inactive. The matching ``signal.detected`` envelope reported the start-time when the signal became active. required: true properties: - name: signal_type type: string title: SignalType description: Enumeration of supported social signals. enumValues: - agreement - confidence - confusion - disagreement - disengagement - engagement - frustration - hesitation - interest - skepticism - stress - uncertainty required: true - name: end type: number title: End description: >- Time at which the signal stopped being active, in seconds, in absolute session-cumulative time. examples: &ref_35 - 14 required: true headers: [] jsonPayloadSchema: description: v1 ``signal.ended`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_33 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: signal.ended default: signal.ended description: >- Discriminator identifying the message kind. For this message it is always ``signal.ended``. title: Type type: string x-parser-schema-id: data: description: >- Payload for the ``signal.ended`` event. Carries only an end time — no start or window — because the envelope marks the moment the signal transitions from active to inactive. The matching ``signal.detected`` envelope reported the start-time when the signal became active. properties: signal_type: *ref_34 end: description: >- Time at which the signal stopped being active, in seconds, in absolute session-cumulative time. examples: *ref_35 title: End type: number x-parser-schema-id: required: - signal_type - end title: SignalEndedV1Data type: object x-parser-schema-id: SignalEndedV1Data required: - timestamp - data title: SignalEndedV1Message type: object x-parser-schema-id: SignalEndedV1Message title: Signal Ended description: >- Reports that a previously active social signal is no longer active. Emitted when a signal type that was active in the previous analyzed window is not present in the current window. ``data.end`` uses absolute session-cumulative time. example: |- { "type": "signal.ended", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "signal_type": "agreement", "end": 14 } } bindings: [] extensions: - id: x-parser-unique-object-id value: signal_ended_v1_message - id: x-parser-message-name value: signal_ended_v1_message bindings: [] extensions: *ref_2 - &ref_50 id: output_signal_updated title: Output_signal_updated description: Signal Updated type: send messages: - &ref_61 id: signal_updated_v1_message payload: - name: Signal Updated description: >- Reports that an already-active social signal experienced a change in probability. Emitted when an active signal type's ``probability`` has changed from the previous value reported for that signal type (either ``signal.detected`` or a prior ``signal.updated``). ``data.start`` uses absolute session-cumulative time. type: object properties: - name: timestamp type: string title: Timestamp description: ISO 8601 timestamp identifying when the event occurred. examples: &ref_36 - '2025-01-01T00:00:00.000000Z' required: true - name: correlation_id type: string title: Correlation Id description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. required: false - name: type type: string title: Type description: >- Discriminator identifying the message kind. For this message it is always ``signal.updated``. required: false - name: data type: object title: SignalUpdatedV1Data description: >- Payload for the ``signal.updated`` event. Emitted while the signal remains active and its ``probability`` has changed since the most recently emitted envelope for the same ``signal_type``. Carries the same fields as ``signal.detected``: ``start`` is the moment from which the new probability applies. required: true properties: - name: signal_type type: string title: SignalType description: Enumeration of supported social signals. enumValues: - agreement - confidence - confusion - disagreement - disengagement - engagement - frustration - hesitation - interest - skepticism - stress - uncertainty required: true - name: start type: number title: Start description: >- Time at which the new probability begins to apply, in seconds, in absolute session-cumulative time. examples: &ref_37 - 6 required: true - name: probability type: string title: Probability description: Signal probability levels. enumValues: - high - medium - low required: false - name: rationale type: string title: Rationale description: >- A concise, evidence-based explanation of why the signal was detected at its new probability. Grounded in observable cues from the video. examples: &ref_39 - Subject nodded once but then looked away. required: false headers: [] jsonPayloadSchema: description: v1 ``signal.updated`` envelope (chanx routing wrapper). properties: timestamp: description: ISO 8601 timestamp identifying when the event occurred. examples: *ref_36 title: Timestamp type: string x-parser-schema-id: correlation_id: default: '' description: >- Unique identifier assigned to this WebSocket connection. Use it when contacting support to locate the relevant records. title: Correlation Id type: string x-parser-schema-id: type: const: signal.updated default: signal.updated description: >- Discriminator identifying the message kind. For this message it is always ``signal.updated``. title: Type type: string x-parser-schema-id: data: description: >- Payload for the ``signal.updated`` event. Emitted while the signal remains active and its ``probability`` has changed since the most recently emitted envelope for the same ``signal_type``. Carries the same fields as ``signal.detected``: ``start`` is the moment from which the new probability applies. properties: signal_type: *ref_34 start: description: >- Time at which the new probability begins to apply, in seconds, in absolute session-cumulative time. examples: *ref_37 title: Start type: number x-parser-schema-id: probability: *ref_38 rationale: anyOf: - type: string x-parser-schema-id: - type: 'null' x-parser-schema-id: description: >- A concise, evidence-based explanation of why the signal was detected at its new probability. Grounded in observable cues from the video. examples: *ref_39 title: Rationale x-parser-schema-id: required: - signal_type - start title: SignalUpdatedV1Data type: object x-parser-schema-id: SignalUpdatedV1Data required: - timestamp - data title: SignalUpdatedV1Message type: object x-parser-schema-id: SignalUpdatedV1Message title: Signal Updated description: >- Reports that an already-active social signal experienced a change in probability. Emitted when an active signal type's ``probability`` has changed from the previous value reported for that signal type (either ``signal.detected`` or a prior ``signal.updated``). ``data.start`` uses absolute session-cumulative time. example: |- { "type": "signal.updated", "timestamp": "2025-01-01T00:00:00.000000Z", "correlation_id": "550e8400-e29b-41d4-a716-446655440000", "data": { "signal_type": "agreement", "start": 6, "probability": "medium", "rationale": "Subject nodded once but then looked away." } } bindings: [] extensions: - id: x-parser-unique-object-id value: signal_updated_v1_message - id: x-parser-message-name value: signal_updated_v1_message bindings: [] extensions: *ref_2 sendOperations: - *ref_40 - *ref_41 receiveOperations: - *ref_42 - *ref_43 - *ref_44 - *ref_45 - *ref_46 - *ref_47 - *ref_48 - *ref_49 - *ref_50 sendMessages: - *ref_51 - *ref_52 receiveMessages: - *ref_53 - *ref_54 - *ref_55 - *ref_56 - *ref_57 - *ref_58 - *ref_59 - *ref_60 - *ref_61 extensions: - id: x-parser-unique-object-id value: stream_analyze_v1 securitySchemes: - id: bearerAuth name: bearerAuth type: http description: >- API key authentication. Include your API key in the Authorization header as 'Bearer '. scheme: bearer extensions: [] ````