TypeScript SDK - Interhuman AI Docs

Classes

AuthClient

Exchanges API-key credentials for a short-lived bearer access token. The token returned by createToken carries only the scopes you request and expires after expires_in seconds (typically 15 minutes). For hands-off token lifecycle management, prefer the top-level InterhumanClient, which uses a TokenManager to fetch and refresh tokens for you.

Constructors

Constructor

new AuthClient(options?): AuthClient;

Parameters

Parameter	Type
`options`	`AuthClientOptions`

Returns

AuthClient

Methods

createToken()

createToken(request): Promise<TokenResponse>;

Mint an access token for the given credentials and scopes.

Parameters

Parameter	Type
`request`	`TokenRequest`

Returns

Promise<TokenResponse>

Throws

when the credentials are invalid (401), lack a requested scope (403), or the request is otherwise rejected.

createClientToken()

createClientToken(request): Promise<ClientTokenResponse>;

Mint a short-lived, capped client token for direct browser use. Call this from your backend with your API key; the returned token is safe to hand to a browser to call the upload, stream, or realtime endpoints directly. It grants the requested scopes (default interhumanai.stream) and carries the caps you set, which the API enforces across upload, stream, and realtime (the video budget spans all three). Omitted fields are left unset (the server applies its defaults, e.g. a single concurrent session and a 300s TTL).

Parameters

Parameter	Type
`request`	`ClientTokenRequest`

Returns

Promise<ClientTokenResponse>

Throws

when the credentials are invalid (401), the key lacks a requested scope (403), or the mint rate limit is exceeded (429).

revokeClientToken()

revokeClientToken(request): Promise<void>;

Revoke a previously minted client token. Call this from your backend with the same API key that minted the token. Once revoked, the token is rejected on new requests and any live streaming session it opened is torn down on its next chunk. Revoking an already-expired token is a harmless no-op.

Parameters

Parameter	Type
`request`	`RevokeClientTokenRequest`

Returns

Promise<void>

Throws

when the credentials or token are invalid (401).

StaticTokenProvider

A TokenProvider that always returns the same pre-issued token.

Implements

TokenProvider

Constructors

Constructor

new StaticTokenProvider(token): StaticTokenProvider;

Parameters

Parameter	Type
`token`	`string`

Returns

StaticTokenProvider

Methods

getToken()

getToken(): Promise<string>;

Return a currently-valid bearer token, minting/refreshing as needed.

Returns

Promise<string>

Implementation of

TokenProvider.getToken

TokenManager

Mints access tokens from API-key credentials via AuthClient and caches them until shortly before they expire, so callers can request a valid bearer token cheaply on every call. Concurrent requests while a token is being minted share a single in-flight request.

Implements

TokenProvider

Constructors

Constructor

new TokenManager(options): TokenManager;

Parameters

Parameter	Type
`options`	`TokenManagerOptions`

Returns

TokenManager

Methods

getToken()

getToken(): Promise<string>;

Return a valid bearer token, minting or refreshing transparently.

Returns

Promise<string>

Implementation of

TokenProvider.getToken

invalidate()

invalidate(): void;

Drop any cached token so the next getToken mints a fresh one.

Returns

void

InterhumanClient

The main entry point. Construct it once with credentials (or a token) and use upload, stream, and realtime to call the API; token lifecycle is handled for you.

Example

const client = new InterhumanClient({
  credentials: { keyId: "...", keySecret: "..." },
});
const report = await client.upload.analyze({ file: bytes, filename: "clip.mp4" });

Constructors

Constructor

new InterhumanClient(options): InterhumanClient;

Parameters

Parameter	Type
`options`	`InterhumanClientOptions`

Returns

InterhumanClient

Properties

Property	Modifier	Type	Description
`auth`	`readonly`	`AuthClient`	Low-level auth client for minting tokens directly via `/v1/auth`.
`upload`	`readonly`	`UploadClient`	Upload-mode analysis client (`POST /v1/upload/analyze`).

Methods

stream()

stream(): StreamClient;

Create a new StreamClient for a live analysis session. Each call returns a fresh client (one per WebSocket session); register handlers and then call connect().

Returns

StreamClient

realtime()

realtime(): RealtimeClient;

Create a new RealtimeClient for a realtime multi-track analysis session (WS /v0/realtime/analyze). Each call returns a fresh client (one per WebSocket session); register handlers and then call connect(). The endpoint requires tokens holding the realtime scope, which is not in the client’s default scopes, so pass it explicitly (e.g. scopes: [Scope.Upload, Scope.Stream, Scope.Realtime]). Request every scope the client needs: the minted token grants exactly what was asked for, so narrowing to [Scope.Realtime] alone closes off upload() and stream().

Returns

RealtimeClient

getToken()

getToken(): Promise<string>;

Return a currently-valid bearer token (minting/refreshing as needed).

Returns

Promise<string>

InterhumanError

Base class for every error the SDK throws.

Extends

Error

Constructors

Constructor

new InterhumanError(message): InterhumanError;

Parameters

Parameter	Type
`message`	`string`

Returns

InterhumanError

Overrides

Error.constructor

InterhumanApiError

An error response from an HTTP endpoint (/v1/auth, /v1/upload/analyze). errorId, correlationId, and link are surfaced from the canonical ApiErrorBody when the server returned one.

Extends

InterhumanError

Constructors

Constructor

new InterhumanApiError(args): InterhumanApiError;

Parameters

Parameter	Type
`args`	{ `status`: `number`; `body?`: `ApiErrorBody`; `message?`: `string`; }
`args.status`	`number`
`args.body?`	`ApiErrorBody`
`args.message?`	`string`

Returns

InterhumanApiError

Overrides

InterhumanError.constructor

Properties

Property	Modifier	Type	Description
`status`	`readonly`	`number`	HTTP status code.
`errorId?`	`readonly`	`string`	Machine-readable error code, when present.
`correlationId?`	`readonly`	`string`	Correlation id for support, when present.
`link?`	`readonly`	`string`	Documentation link for the error, when present.
`body?`	`readonly`	`ApiErrorBody`	The raw parsed error body, when the server returned JSON.

InterhumanConfigError

A configuration/usage error caught before any network call. Stream error envelopes are not thrown — they are delivered as typed StreamErrorEvents through the stream client’s on("error", …) surface, and transport-level socket failures arrive on "socketError" as a base InterhumanError.

Extends

InterhumanError

Constructors

Constructor

new InterhumanConfigError(message): InterhumanConfigError;

Parameters

Parameter	Type
`message`	`string`

Returns

InterhumanConfigError

Inherited from

InterhumanError.constructor

RealtimeClient

A typed client over the realtime WebSocket protocol. The realtime endpoint shares the stream endpoint’s session mechanics (subprotocol bearer auth, binary video frames, JSON envelopes down, and the requestClose() graceful shutdown handshake) and adds multi-track analysis, a caller-supplied transcript (sendTranscript), and a periodic recommendation step (realtime_recommendation.generated) enabled through the session config’s realtime_recommendation_instructions. The endpoint currently ships under the v0 path (/v0/realtime/analyze), which may change when it graduates to v1, and requires credentials holding the interhumanai.realtime scope.

Example

const realtime = client.realtime();
realtime.on("signal.detected", (e) => console.log(e.data.signal_type));
realtime.on("realtime_recommendation.generated", (e) => console.log(e.data.text));
await realtime.connect();
await realtime.waitForSessionReady();
realtime.updateConfig({
  realtime_recommendation_instructions: "Goal: help me close a sales call.",
  realtime_recommendation_frequency: "medium",
});
realtime.sendVideo(chunk);
realtime.requestClose(); // graceful: drains (incl. recommendation), then session.ended + close

Extends

SessionSocketClient<RealtimeEventMap, RealtimeSessionConfig>

Constructors

Constructor

new RealtimeClient(options): RealtimeClient;

Parameters

Parameter	Type
`options`	`SessionSocketClientOptions`

Returns

RealtimeClient

Overrides

SessionSocketClient.constructor

Properties

Property	Modifier	Type	Default value	Description	Overrides
`endpointPath`	`readonly`	`"/v0/realtime/analyze"`	`"/v0/realtime/analyze"`	Endpoint path appended to the WebSocket base URL (e.g. `/v1/stream/analyze`).	`SessionSocketClient`.`endpointPath`
`clientName`	`readonly`	`"RealtimeClient"`	`"RealtimeClient"`	Concrete class name used in configuration error messages.	`SessionSocketClient`.`clientName`
`displayName`	`readonly`	`"Realtime"`	`"Realtime"`	Human-readable surface name used in error messages (e.g. `"Stream"`).	`SessionSocketClient`.`displayName`
`scopeHint`	`readonly`	`"The credentials may be invalid or lack the realtime scope."`	`"The credentials may be invalid or lack the realtime scope."`	Appended to the connect-rejection message to hint at the likely scope issue.	`SessionSocketClient`.`scopeHint`

Accessors

isOpen

Get Signature

get isOpen(): boolean;

Whether the underlying socket is open.

Returns

boolean

Inherited from

SessionSocketClient.isOpen

Methods

sendTranscript()

sendTranscript(transcript): void;

Send (or replace) the caller-supplied transcript as a transcript.updated text frame. The most recent transcript replaces any prior one for the session and is rendered into the recommendation prompt. A transcript that does not match the segment shape is rejected by the server with a non-fatal error envelope; the session stays open.

Parameters

Parameter	Type
`transcript`	`TranscriptSegment`[]

Returns

void

on()

on<K>(event, handler): () => void;

Subscribe to an event. Returns an unsubscribe function. Use a specific envelope type (e.g. "signal.detected"), "message" for every envelope, or a lifecycle event ("open", "close", "socketError").

Type Parameters

Type Parameter
`K` extends keyof `RealtimeEventMap`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`RealtimeEventMap`[`K`]>

Returns

() => void

Inherited from

SessionSocketClient.on

off()

off<K>(event, handler): void;

Unsubscribe a previously registered handler.

Type Parameters

Type Parameter
`K` extends keyof `RealtimeEventMap`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`RealtimeEventMap`[`K`]>

Returns

void

Inherited from

SessionSocketClient.off

once()

once<K>(event, handler): () => void;

Subscribe to the next occurrence of an event, then auto-unsubscribe.

Type Parameters

Type Parameter
`K` extends keyof `RealtimeEventMap`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`RealtimeEventMap`[`K`]>

Returns

() => void

Inherited from

SessionSocketClient.once

connect()

connect(): Promise<void>;

Open the connection and resolve once it is established. Rejects if the connection closes or errors before opening (e.g. invalid credentials).

Returns

Promise<void>

Inherited from

SessionSocketClient.connect

waitForSessionReady()

waitForSessionReady(): Promise<RealtimeSessionReadyEvent>;

Wait for the session.ready envelope. Resolves immediately if it has already arrived (the envelope is retained), otherwise on the next one. Safe to call after connect without racing the frame.

Returns

Promise<RealtimeSessionReadyEvent>

Inherited from

SessionSocketClient.waitForSessionReady

sendVideo()

sendVideo(chunk): void;

Send a chunk of WebM or fragmented-MP4 video as a binary frame.

Parameters

Parameter	Type
`chunk`	`VideoChunk`

Returns

void

Inherited from

SessionSocketClient.sendVideo

updateConfig()

updateConfig(config): void;

Send (or replace) the session config. Each frame fully replaces the active config; the server acknowledges with a session.updated envelope.

Parameters

Parameter	Type
`config`	`RealtimeSessionConfig`

Returns

void

Inherited from

SessionSocketClient.updateConfig

requestClose()

requestClose(): void;

Request a graceful end-of-analysis shutdown (session.close). The server acknowledges with a session.closing envelope whose data.max_drain_seconds is the longest you should wait for the final session.ended envelope. After the acknowledgment the server rejects new video, finishes analyzing the video it already accepted (emitting the normal envelopes in order, plus signal.ended for still-active signals), sends session.ended, and closes the socket with code 1000 — so listen for "session.ended" (or "close") rather than calling close.

Returns

void

Inherited from

SessionSocketClient.requestClose

close()

close(code?, reason?): void;

Close the connection immediately, without the graceful drain handshake.

Parameters

Parameter	Type
`code?`	`number`
`reason?`	`string`

Returns

void

Inherited from

SessionSocketClient.close

sendJson()

protected sendJson(payload): void;

Send an arbitrary JSON payload as a text frame.

Parameters

Parameter	Type
`payload`	`unknown`

Returns

void

Inherited from

SessionSocketClient.sendJson

`abstract` SessionSocketClient

Base class implementing the shared live-session WebSocket protocol. Authentication uses the Sec-WebSocket-Protocol: access_token, <token> subprotocol pair, which is portable across browsers and Node (the standard WebSocket constructor cannot set an Authorization header). Inbound frames are decoded into the protocol’s envelope union and dispatched through the typed on surface; outbound video is sent as binary frames and JSON payloads (session config, and for realtime the transcript) as text frames.

Extended by

StreamClient
RealtimeClient

Type Parameters

Type Parameter	Description
`TEventMap` extends `SessionSocketEventMapBase`<`unknown`, `unknown`>	Event payloads keyed by event name (envelope `type`s plus the lifecycle events of SessionSocketEventMapBase).
`TConfig` extends `object`	The client→server session-config shape.

Constructors

Constructor

new SessionSocketClient<TEventMap, TConfig>(options): SessionSocketClient<TEventMap, TConfig>;

Parameters

Parameter	Type
`options`	`SessionSocketClientOptions`

Returns

SessionSocketClient<TEventMap, TConfig>

Properties

Property	Modifier	Type	Description
`endpointPath`	`abstract`	`string`	Endpoint path appended to the WebSocket base URL (e.g. `/v1/stream/analyze`).
`clientName`	`abstract`	`string`	Concrete class name used in configuration error messages.
`displayName`	`abstract`	`string`	Human-readable surface name used in error messages (e.g. `"Stream"`).
`scopeHint`	`abstract`	`string`	Appended to the connect-rejection message to hint at the likely scope issue.

Accessors

isOpen

Get Signature

get isOpen(): boolean;

Whether the underlying socket is open.

Returns

boolean

Methods

on()

on<K>(event, handler): () => void;

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`TEventMap`[`K`]>

Returns

() => void

off()

off<K>(event, handler): void;

Unsubscribe a previously registered handler.

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`TEventMap`[`K`]>

Returns

void

once()

once<K>(event, handler): () => void;

Subscribe to the next occurrence of an event, then auto-unsubscribe.

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`TEventMap`[`K`]>

Returns

() => void

connect()

connect(): Promise<void>;

Open the connection and resolve once it is established. Rejects if the connection closes or errors before opening (e.g. invalid credentials).

Returns

Promise<void>

waitForSessionReady()

waitForSessionReady(): Promise<TEventMap["session.ready"]>;

Wait for the session.ready envelope. Resolves immediately if it has already arrived (the envelope is retained), otherwise on the next one. Safe to call after connect without racing the frame.

Returns

Promise<TEventMap["session.ready"]>

sendVideo()

sendVideo(chunk): void;

Send a chunk of WebM or fragmented-MP4 video as a binary frame.

Parameters

Parameter	Type
`chunk`	`VideoChunk`

Returns

void

updateConfig()

updateConfig(config): void;

Send (or replace) the session config. Each frame fully replaces the active config; the server acknowledges with a session.updated envelope.

Parameters

Parameter	Type
`config`	`TConfig`

Returns

void

requestClose()

requestClose(): void;

Returns

void

close()

close(code?, reason?): void;

Close the connection immediately, without the graceful drain handshake.

Parameters

Parameter	Type
`code?`	`number`
`reason?`	`string`

Returns

void

sendJson()

protected sendJson(payload): void;

Send an arbitrary JSON payload as a text frame.

Parameters

Parameter	Type
`payload`	`unknown`

Returns

void

StreamClient

A typed client over the stream WebSocket protocol. Authentication uses the Sec-WebSocket-Protocol: access_token, <token> subprotocol pair, which is portable across browsers and Node (the standard WebSocket constructor cannot set an Authorization header). Inbound frames are decoded into the StreamEvent union and dispatched through the typed on surface inherited from SessionSocketClient; outbound video is sent as binary frames and session config as a JSON text frame.

Example

const stream = client.stream();
stream.on("signal.detected", (e) => console.log(e.data.signal_type));
await stream.connect();
await stream.waitForSessionReady();
stream.updateConfig({ include: ["conversation_quality_overall"] });
stream.sendVideo(chunk);
stream.requestClose(); // graceful: drains, then session.ended + close

Extends

SessionSocketClient<StreamEventMap, StreamSessionConfig>

Constructors

Constructor

new StreamClient(options): StreamClient;

Parameters

Parameter	Type
`options`	`SessionSocketClientOptions`

Returns

StreamClient

Overrides

SessionSocketClient.constructor

Properties

Property	Modifier	Type	Default value	Description	Overrides
`endpointPath`	`readonly`	`"/v1/stream/analyze"`	`"/v1/stream/analyze"`	Endpoint path appended to the WebSocket base URL (e.g. `/v1/stream/analyze`).	`SessionSocketClient`.`endpointPath`
`clientName`	`readonly`	`"StreamClient"`	`"StreamClient"`	Concrete class name used in configuration error messages.	`SessionSocketClient`.`clientName`
`displayName`	`readonly`	`"Stream"`	`"Stream"`	Human-readable surface name used in error messages (e.g. `"Stream"`).	`SessionSocketClient`.`displayName`
`scopeHint`	`readonly`	`"The credentials may be invalid or lack the stream scope."`	`"The credentials may be invalid or lack the stream scope."`	Appended to the connect-rejection message to hint at the likely scope issue.	`SessionSocketClient`.`scopeHint`

Accessors

isOpen

Get Signature

get isOpen(): boolean;

Whether the underlying socket is open.

Returns

boolean

Inherited from

SessionSocketClient.isOpen

Methods

on()

on<K>(event, handler): () => void;

Type Parameters

Type Parameter
`K` extends keyof `StreamEventMap`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`StreamEventMap`[`K`]>

Returns

() => void

Inherited from

SessionSocketClient.on

off()

off<K>(event, handler): void;

Unsubscribe a previously registered handler.

Type Parameters

Type Parameter
`K` extends keyof `StreamEventMap`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`StreamEventMap`[`K`]>

Returns

void

Inherited from

SessionSocketClient.off

once()

once<K>(event, handler): () => void;

Subscribe to the next occurrence of an event, then auto-unsubscribe.

Type Parameters

Type Parameter
`K` extends keyof `StreamEventMap`

Parameters

Parameter	Type
`event`	`K`
`handler`	`Listener`<`StreamEventMap`[`K`]>

Returns

() => void

Inherited from

SessionSocketClient.once

connect()

connect(): Promise<void>;

Open the connection and resolve once it is established. Rejects if the connection closes or errors before opening (e.g. invalid credentials).

Returns

Promise<void>

Inherited from

SessionSocketClient.connect

waitForSessionReady()

waitForSessionReady(): Promise<SessionReadyEvent>;

Wait for the session.ready envelope. Resolves immediately if it has already arrived (the envelope is retained), otherwise on the next one. Safe to call after connect without racing the frame.

Returns

Promise<SessionReadyEvent>

Inherited from

SessionSocketClient.waitForSessionReady

sendVideo()

sendVideo(chunk): void;

Send a chunk of WebM or fragmented-MP4 video as a binary frame.

Parameters

Parameter	Type
`chunk`	`VideoChunk`

Returns

void

Inherited from

SessionSocketClient.sendVideo

updateConfig()

updateConfig(config): void;

Send (or replace) the session config. Each frame fully replaces the active config; the server acknowledges with a session.updated envelope.

Parameters

Parameter	Type
`config`	`StreamSessionConfig`

Returns

void

Inherited from

SessionSocketClient.updateConfig

requestClose()

requestClose(): void;

Returns

void

Inherited from

SessionSocketClient.requestClose

close()

close(code?, reason?): void;

Close the connection immediately, without the graceful drain handshake.

Parameters

Parameter	Type
`code?`	`number`
`reason?`	`string`

Returns

void

Inherited from

SessionSocketClient.close

sendJson()

protected sendJson(payload): void;

Send an arbitrary JSON payload as a text frame.

Parameters

Parameter	Type
`payload`	`unknown`

Returns

void

Inherited from

SessionSocketClient.sendJson

UploadClient

Analyzes a complete video file and returns a single report. The request is sent as multipart/form-data with the bearer token attached automatically from the configured TokenProvider.

Constructors

Constructor

new UploadClient(options): UploadClient;

Parameters

Parameter	Type
`options`	`UploadClientOptions`

Returns

UploadClient

Methods

analyze()

analyze(input): Promise<AnalysisResult>;

Analyze a video file in upload mode.

Parameters

Parameter	Type
`input`	`AnalyzeUploadInput`

Returns

Promise<AnalysisResult>

Throws

on a rejected request (auth, validation, too-large/too-short media, quota, unprocessable video, server error).

Interfaces

AuthClientOptions

Options for constructing an AuthClient.

Properties

Property	Type	Description
`baseUrl?`	`string`	Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`.
`environment?`	`Environment`	Named environment to target. Defaults to `"production"`.
`fetch?`	{ (`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation. Defaults to the global `fetch`.

TokenProvider

Anything that can supply a bearer token on demand.

Methods

getToken()

getToken(): Promise<string>;

Return a currently-valid bearer token, minting/refreshing as needed.

Returns

Promise<string>

TokenManagerOptions

Options for a TokenManager.

Properties

Property	Type	Description
`authClient`	`AuthClient`	-
`credentials`	`ApiKeyCredentials`	-
`scopes`	`ScopeValue`[]	Scopes to request when minting tokens.
`refreshSkewSeconds?`	`number`	Refresh a cached token this many seconds before its stated expiry, to absorb clock skew and request latency. Defaults to 30.
`now?`	() => `number`	Injectable clock (milliseconds). Defaults to `Date.now`. Test seam.

ApiKeyCredentials

Credentials issued in the Interhuman customer platform.

Extended by

TokenRequest

Properties

Property	Type	Description
`keyId`	`string`	API key ID from the dashboard.
`keySecret`	`string`	API key secret from the dashboard.

ApiKeyCredential

A full API key string used to mint and revoke client tokens.

Extended by

ClientTokenRequest
RevokeClientTokenRequest

Properties

Property	Type	Description
`apiKey`	`string`	Your full API key from the dashboard (`ih_<env>_<publicId>_<entropy>`).

TokenRequest

Request body for POST /v1/auth.

Extends

ApiKeyCredentials

Properties

Property	Type	Description	Inherited from
`keyId`	`string`	API key ID from the dashboard.	`ApiKeyCredentials`.`keyId`
`keySecret`	`string`	API key secret from the dashboard.	`ApiKeyCredentials`.`keySecret`
`scopes`	`ScopeValue`[]	Requested scopes; at least one is required.	-

TokenResponse

Response body from POST /v1/auth.

Properties

Property	Type	Description
`access_token`	`string`	The minted bearer access token (a JWT).
`token_type`	`string`	Token type; always `"Bearer"`.
`expires_in`	`number`	Seconds until the token expires (typically 900).
`scope`	`string`	Space-separated list of granted scopes.

ClientTokenRequest

Request for minting an ephemeral, capped client token (POST /v1/client_tokens). Call this server-side with your API key; the returned token is safe to hand to a browser to call the upload, stream, or realtime endpoints directly. Every cap is optional. The token grants only the requested scopes (default interhumanai.stream); the caps are enforced on streaming sessions (stream / realtime) and the video budget additionally spans upload.

Extends

ApiKeyCredential

Properties

Property	Type	Description	Inherited from
`apiKey`	`string`	Your full API key from the dashboard (`ih_<env>_<publicId>_<entropy>`).	`ApiKeyCredential`.`apiKey`
`scopes?`	`ScopeValue`[]	Scopes to grant the token. Defaults to `["interhumanai.stream"]`.	-
`expiresIn?`	`number`	Requested lifetime in seconds. Clamped to 60–3600; defaults to 300.	-
`maxDurationSeconds?`	`number`	Max wall-clock duration, in seconds, of a session opened with this token.	-
`maxBytes?`	`number`	Max cumulative video bytes a session opened with this token may send.	-
`maxConcurrent?`	`number`	Max number of concurrent sessions opened with this token. Defaults to 1 (one session at a time) when omitted server-side.	-
`maxVideoSeconds?`	`number`	Max total seconds of video the token may process across upload/stream/realtime.	-
`allowedOrigins?`	`string`[]	Allow-list of browser `Origin` values permitted to use this token.	-

ClientTokenResponse

Response body from POST /v1/client_tokens.

Properties

Property	Type	Description
`access_token`	`string`	The minted client token (a JWT).
`token_type`	`string`	Token type; always `"Bearer"`.
`expires_in`	`number`	Seconds until the token expires.
`scope`	`string`	Space-separated list of granted scopes.
`max_duration_seconds?`	`number` \| `null`	Per-token max session duration that will be enforced, if any.
`max_bytes?`	`number` \| `null`	Per-token max cumulative session bytes that will be enforced, if any.
`max_concurrent?`	`number` \| `null`	Per-token max concurrent sessions that will be enforced, if any.
`max_video_seconds?`	`number` \| `null`	Per-token total video-seconds budget that will be enforced, if any.
`allowed_origins?`	`string`[] \| `null`	Per-token allow-list of browser origins that will be enforced, if any.

RevokeClientTokenRequest

Request for revoking a client token (POST /v1/client_tokens/revoke).

Extends

ApiKeyCredential

Properties

Property	Type	Description	Inherited from
`apiKey`	`string`	Your full API key from the dashboard (`ih_<env>_<publicId>_<entropy>`).	`ApiKeyCredential`.`apiKey`
`token`	`string`	The client token to revoke (as returned in `access_token`).	-

InterhumanClientOptions

Options for constructing an InterhumanClient.

Properties

Property	Type	Description
`credentials?`	`ApiKeyCredentials`	API-key credentials. The client exchanges these at `/v1/auth` and refreshes the resulting token automatically. Provide either `credentials` or `accessToken`.
`accessToken?`	`string`	A pre-issued bearer access token, used as-is. Provide either `accessToken` or `credentials`.
`scopes?`	`ScopeValue`[]	Scopes requested when minting tokens from `credentials`. Defaults to upload + stream. Ignored when `accessToken` is supplied.
`environment?`	`Environment`	Named environment to target. Defaults to `"production"`.
`baseUrl?`	`string`	Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`.
`fetch?`	{ (`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation. Defaults to the global `fetch`.
`webSocket?`	`WebSocketFactory`	Custom WebSocket factory for the stream and realtime clients. Defaults to the global `WebSocket` (browsers, Node 22+).
`refreshSkewSeconds?`	`number`	Seconds before stated expiry to refresh a minted token. Defaults to 30.

ApiErrorBody

The canonical error body returned by every HTTP error path.

Properties

Property	Type	Description
`error_id`	`string`	Machine-readable error code.
`correlation_id?`	`string` \| `null`	Connection/request correlation id; quote it when contacting support.
`link?`	`string` \| `null`	URL with more information about this error, when available.
`message?`	`string` \| `null`	Human-readable explanation, when available.

TranscriptSegment

One diarized utterance of a realtime transcript, as sent with sendTranscript.

Properties

Property	Type	Description
`start`	`number`	Start time of the utterance, in seconds.
`end`	`number`	End time of the utterance, in seconds.
`text`	`string`	The spoken text of this segment.
`speaker`	`number`	Zero-based index identifying the speaker of this segment.

RealtimeSessionConfig

Client-to-server realtime session config (sent as a JSON text frame). The last config sent fully replaces the active one; the server acknowledges with a session.updated envelope. The stream include flags are not accepted — the realtime endpoint never emits the conversation-quality or engagement updates those flags control.

Properties

Property	Type	Description
`analysis_groups?`	`AnalysisGroup`[]	Analysis surfaces to run for this session, any subset of what the server advertises on `session.ready` under `supported_session_config_options.analysis_groups`. Must be non-empty when present: an empty array — like selecting a group the server has not enabled — is rejected with an `error` envelope. When omitted, the server default is `audio` + `visual`.
`realtime_recommendation_frequency?`	`RealtimeRecommendationFrequency`	How often recommendation runs once enabled. Has no effect until a non-empty `realtime_recommendation_instructions` enables recommendations.
`realtime_recommendation_instructions?`	`string` \| `null`	Configuration block for the periodic recommendation step, and the switch that enables it: the recommendation step runs only when this is a non-empty string (there is no default prompt). It sets the goal, domain/context, and the focus, tone, or output style of the guidance. It is treated as untrusted configuration data — it shapes the guidance but cannot override the recommendation task or output contract set by the active system prompt.

TranscriptUpdatedFrame

The inbound transcript.updated text frame carrying a caller-supplied transcript. Sent by RealtimeClient.sendTranscript; the most recent transcript replaces any prior one and is rendered into the recommendation prompt.

Properties

Property	Type	Description
`type`	`"transcript.updated"`	-
`transcript`	`TranscriptSegment`[]	The full transcript as `{start, end, text, speaker}` segments, in spoken order.

RealtimeSessionReadyConfigOptions

Supported realtime session-config options advertised on session.ready. Unlike the stream options, only the realtime controls appear here — never the stream include / goal_dimensions options.

Properties

Property	Type	Description
`realtime_recommendation_instructions`	`"string"`	Always the literal `"string"`: `realtime_recommendation_instructions` takes free-form text, so its accepted JSON type is advertised instead of a value list.
`realtime_recommendation_frequency`	`RealtimeRecommendationFrequency`[]	Accepted `realtime_recommendation_frequency` values.
`analysis_groups`	`AnalysisGroup`[]	Analysis groups this deployment allows — the valid values for the config’s `analysis_groups` field, so you can pick a subset without round-tripping a rejection.

RealtimeSessionReadyData

session.ready payload — the same connection-level limits as the stream session.ready, with the realtime supported-config options.

Properties

Property	Type	Description
`session_idle_timeout_seconds`	`number`	Idle seconds tolerated before the server closes the session (`0` = disabled).
`session_max_duration_seconds`	`number`	Maximum total session duration in seconds (`0` = disabled).
`max_segment_duration_seconds`	`number` \| `null`	Max probed duration of one inbound chunk, or `null` when only the size cap binds.
`min_segment_size_bytes`	`number`	Minimum size in bytes of one inbound chunk.
`max_segment_size_bytes`	`number`	Maximum size in bytes of one inbound chunk.
`supported_session_config_options`	`RealtimeSessionReadyConfigOptions`	-

RealtimeSessionReadyEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`type`	`"session.ready"`	-	-
`data`	`RealtimeSessionReadyData`	-	-
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`

RealtimeSessionUpdatedData

session.updated payload — the consolidated realtime config after a config frame applied. Reports only the realtime options, never the stream-only include / goal_dimensions fields.

Properties

Property	Type	Description
`realtime_recommendation_instructions`	`string` \| `null`	The applied `realtime_recommendation_instructions`, echoed back verbatim; `null` when unset.
`realtime_recommendation_frequency`	\| `RealtimeRecommendationFrequency` \| `null`	The active recommendation frequency; `null` when unset.
`analysis_groups`	`AnalysisGroup`[]	The effective analysis-group selection in force (the server default when you have not chosen one).

RealtimeSessionUpdatedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`type`	`"session.updated"`	-	-
`data`	`RealtimeSessionUpdatedData`	-	-
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`

RealtimeRecommendationGeneratedData

realtime_recommendation.generated payload — one recommendation run’s guidance text.

Properties

Property	Type	Description
`text`	`string`	The guidance text returned by the recommendation model — one short recommendation for the responding speaker, or the literal `NO_GUIDANCE` when the signals warrant no adjustment.
`start`	`number`	Start of the analyzed interval this recommendation covers (seconds, session time).
`end`	`number`	End of the analyzed interval this recommendation covers (seconds, session time).

RealtimeRecommendationGeneratedEvent

realtime_recommendation.generated — the periodic recommendation result. Emitted only when realtime_recommendation_instructions has enabled recommendation, paced by realtime_recommendation_frequency.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`type`	`"realtime_recommendation.generated"`	-	-
`data`	`RealtimeRecommendationGeneratedData`	-	-
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`

RealtimeSignalDetectedData

Properties

Property	Type	Description
`signal_type`	`SignalType`	-
`start`	`number`	Seconds, absolute session-cumulative time.
`probability`	`Probability` \| `null`	-
`modality`	`string`[]	Analysis modalities that detected this signal, naming the source of the evidence: one or both of `audio` and `visual`. When both detect the same signal, both are included.

RealtimeSignalDetectedEvent

A social signal was detected. The realtime payload carries no rationale.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`type`	`"signal.detected"`	-	-
`data`	`RealtimeSignalDetectedData`	-	-
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`

RealtimeSignalUpdatedData

Properties

Property	Type	Description
`signal_type`	`SignalType`	-
`start`	`number`	Seconds, absolute session-cumulative time.
`probability`	`Probability` \| `null`	-
`modality`	`string`[]	Analyses whose evidence produced this signal. A change to this set is one of the things that emits `signal.updated`.

RealtimeSignalUpdatedEvent

An active signal’s details changed. The realtime payload carries no rationale.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`type`	`"signal.updated"`	-	-
`data`	`RealtimeSignalUpdatedData`	-	-
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`

RealtimeEventMap

Event payloads keyed by event name, for the typed on/off surface of the realtime client. The envelope types map to their envelope objects; the remaining keys are client-level lifecycle events.

Properties

Property	Type	Description
`session.ready`	`RealtimeSessionReadyEvent`	-
`session.updated`	`RealtimeSessionUpdatedEvent`	-
`session.closing`	`SessionClosingEvent`	-
`session.ended`	`SessionEndedEvent`	-
`signal.detected`	`RealtimeSignalDetectedEvent`	-
`signal.updated`	`RealtimeSignalUpdatedEvent`	-
`signal.ended`	`SignalEndedEvent`	-
`realtime_recommendation.generated`	`RealtimeRecommendationGeneratedEvent`	-
`coverage.dropped`	`CoverageDroppedEvent`	-
`coverage.degraded`	`CoverageDegradedEvent`	-
`error`	`StreamErrorEvent`	-
`message`	`RealtimeEvent`	Fires for every server→client envelope, regardless of type.
`open`	`void`	Fires once when the WebSocket connection opens.
`close`	`StreamCloseInfo`	Fires once when the connection closes.
`socketError`	`Error`	Transport-level socket error (distinct from the `error` envelope).

SessionSocketClientOptions

Options shared by every WebSocket session client.

Properties

Property	Type	Description
`tokenProvider`	`TokenProvider`	Supplies the bearer token used to authenticate the connection.
`baseUrl?`	`string`	Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`.
`environment?`	`Environment`	Named environment to target. Defaults to `"production"`.
`webSocket?`	`WebSocketFactory`	Custom WebSocket factory. Defaults to the global `WebSocket` (browsers, Node 22+). Supply one backed by the `ws` package on older Node.

SessionSocketEventMapBase

The lifecycle and wildcard events every session event map carries, alongside its protocol-specific envelope type keys. TEvent is the protocol’s envelope union and TReady its session.ready envelope.

Type Parameters

Type Parameter
`TEvent`
`TReady`

Properties

Property	Type	Description
`session.ready`	`TReady`	The `session.ready` envelope — first frame after the handshake.
`message`	`TEvent`	Fires for every server→client envelope, regardless of type.
`open`	`void`	Fires once when the WebSocket connection opens.
`close`	`StreamCloseInfo`	Fires once when the connection closes.
`socketError`	`Error`	Transport-level socket error (distinct from the `error` envelope).

StreamEnvelopeBase

Fields shared by every server→client envelope.

Extended by

ConversationQualityUpdatedEvent
CoverageDegradedEvent
CoverageDroppedEvent
EngagementUpdatedEvent
FeedbackGeneratedEvent
SessionClosingEvent
SessionEndedEvent
SessionReadyEvent
SessionUpdatedEvent
SignalDetectedEvent
SignalEndedEvent
SignalUpdatedEvent
StreamErrorEvent
RealtimeSessionReadyEvent
RealtimeSessionUpdatedEvent
RealtimeSignalDetectedEvent
RealtimeSignalUpdatedEvent
RealtimeRecommendationGeneratedEvent

Properties

Property	Type	Description
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.

SessionReadyConfigOptions

Supported session-config options advertised on session.ready.

Properties

Property	Type	Description
`include`	`IncludeFlag`[]	-
`goal_dimensions`	`GoalDimension`[] \| `null`	`null` when the feedback feature is disabled.

SessionReadyData

session.ready payload — session limits and supported config.

Properties

Property	Type	Description
`session_idle_timeout_seconds`	`number`	Idle seconds tolerated before the server closes the session (`0` = disabled).
`session_max_duration_seconds`	`number`	Maximum total session duration in seconds (`0` = disabled).
`max_segment_duration_seconds`	`number` \| `null`	Max probed duration of one inbound chunk, or `null` when only the size cap binds.
`min_segment_size_bytes`	`number`	Minimum size in bytes of one inbound chunk.
`max_segment_size_bytes`	`number`	Maximum size in bytes of one inbound chunk.
`supported_session_config_options`	`SessionReadyConfigOptions`	-

SessionReadyEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"session.ready"`	-	-
`data`	`SessionReadyData`	-	-

SessionUpdatedData

session.updated payload — consolidated config after a config frame applied.

Properties

Property	Type
`include`	`IncludeFlag`[]
`goal_dimensions`	`GoalDimension`[] \| `null`

SessionUpdatedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"session.updated"`	-	-
`data`	`SessionUpdatedData`	-	-

SessionClosingData

session.closing payload — the graceful-close drain contract.

Properties

Property	Type	Description
`max_drain_seconds`	`number`	Maximum seconds the server will spend draining accepted work before it closes the session; `session.ended` arrives no later than this. The session closes earlier when the accepted work finishes sooner.

SessionClosingEvent

Acknowledges a caller-initiated session.close request. From this point the server rejects new video, finishes analyzing the video it already accepted, emits final lifecycle envelopes (signal.ended for still-active signals), sends session.ended, and closes the socket.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"session.closing"`	-	-
`data`	`SessionClosingData`	-	-

SessionEndedData

session.ended payload — why the session ended.

Properties

Property	Type	Description
`reason`	`"client_shutdown"`	`client_shutdown` = the caller requested a graceful close.

SessionEndedEvent

The final message of a gracefully closed session: all analysis is closed and the server closes the WebSocket (code 1000) immediately after sending it. No further analysis messages follow.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"session.ended"`	-	-
`data`	`SessionEndedData`	-	-

SignalDetectedData

Properties

Property	Type	Description
`signal_type`	`SignalType`	-
`start`	`number`	Seconds, absolute session-cumulative time.
`probability`	`Probability` \| `null`	-
`rationale`	`string` \| `null`	-
`modality`	`string`[]	Analysis modalities that detected this signal, naming the source of the evidence. For stream sessions this is `["video"]`.

SignalDetectedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"signal.detected"`	-	-
`data`	`SignalDetectedData`	-	-

SignalUpdatedData

Properties

Property	Type	Description
`signal_type`	`SignalType`	-
`start`	`number`	-
`probability`	`Probability` \| `null`	-
`rationale`	`string` \| `null`	-
`modality`	`string`[]	Analyses whose evidence produced this signal. A change to this set is one of the things that emits `signal.updated`.

SignalUpdatedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"signal.updated"`	-	-
`data`	`SignalUpdatedData`	-	-

SignalEndedData

Properties

Property	Type	Description
`signal_type`	`SignalType`	-
`end`	`number`	Seconds, absolute session-cumulative time.

SignalEndedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"signal.ended"`	-	-
`data`	`SignalEndedData`	-	-

EngagementUpdatedData

Properties

Property	Type
`state`	`EngagementLevel`
`start`	`number`

EngagementUpdatedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"engagement.updated"`	-	-
`data`	`EngagementUpdatedData`	-	-

ConversationQualityUpdatedData

Properties

Property	Type	Description
`overall`	`ConversationQualityValues` \| `null`	Non-null when `conversation_quality_overall` was requested.
`timeline`	\| `ConversationQualityTimelineEntry`[] \| `null`	Non-null when `conversation_quality_timeline` was requested and the period had signals.

ConversationQualityUpdatedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"conversation_quality.updated"`	-	-
`data`	`ConversationQualityUpdatedData`	-	-

FeedbackGeneratedData

Properties

Property	Type	Description
`feedback`	`string`	Comma-separated relevant signal types observed since the previous emission.

FeedbackGeneratedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"feedback.generated"`	-	-
`data`	`FeedbackGeneratedData`	-	-

CoverageDroppedRange

A contiguous range of media skipped under backpressure (not billed).

Properties

Property	Type
`start`	`number`
`end`	`number`

CoverageDroppedData

Properties

Property	Type
`ranges`	`CoverageDroppedRange`[]

CoverageDroppedEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"coverage.dropped"`	-	-
`data`	`CoverageDroppedData`	-	-

CoverageDegradedRange

One time range whose visual coverage was partial, in session seconds.

Properties

Property	Type
`start`	`number`
`end`	`number`

CoverageDegradedData

Payload of CoverageDegradedEvent: the affected time ranges plus the reason. Unlike coverage.dropped, these windows were analyzed (audio plus whatever video decoded) and are billed normally — only the visual coverage was partial.

Properties

Property	Type	Description
`ranges`	`CoverageDegradedRange`[]	-
`reason`	`"video_gap"`	Why the visual coverage was partial. Currently always `"video_gap"`: the windows’ video packets covered materially less than the window span (e.g. a keyframe interval longer than the analysis window, as a static screen share produces).

CoverageDegradedEvent

Informational notice that one or more analysis windows were analyzed with partial visual coverage. The session stays open and the windows are billed normally; the ranges tell your application that visual signals over that stretch drew on partial video.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"coverage.degraded"`	-	-
`data`	`CoverageDegradedData`	-	-

StreamErrorData

Properties

Property	Type	Description
`code`	`string`	Machine-readable error code (e.g. `"ih6002"`).
`message`	`string`	-
`link`	`string` \| `null`	-
`segment`	`number` \| `null`	Inbound caller-chunk index when applicable, else `null`.

StreamErrorEvent

Fields shared by every server→client envelope.

Extends

StreamEnvelopeBase

Properties

Property	Type	Description	Inherited from
`timestamp`	`string`	ISO 8601 timestamp identifying when the event occurred.	`StreamEnvelopeBase`.`timestamp`
`correlation_id`	`string`	Connection correlation id; quote it when contacting support.	`StreamEnvelopeBase`.`correlation_id`
`type`	`"error"`	-	-
`data`	`StreamErrorData`	-	-

StreamSessionConfig

Client-to-server session config (sent as a JSON text frame).

Properties

Property	Type	Description
`include?`	`IncludeFlag`[]	Conversation-quality sections to include in result messages.
`goal_dimensions?`	`GoalDimension`[]	Goal dimensions for this session (drive periodic feedback).

SessionCloseRequest

Client-to-server graceful close request (sent as a JSON text frame). Tells the server the caller is done sending video; the server acknowledges with session.closing and ends the session with session.ended.

Properties

Property	Type
`type`	`"session.close"`

StreamCloseInfo

Information about a closed stream connection.

Properties

Property	Type
`code`	`number`
`reason`	`string`

StreamEventMap

Event payloads keyed by event name, for the typed on/off surface. The twelve envelope types map to their envelope objects; the remaining keys are client-level lifecycle events.

Properties

Property	Type	Description
`session.ready`	`SessionReadyEvent`	-
`session.updated`	`SessionUpdatedEvent`	-
`session.closing`	`SessionClosingEvent`	-
`session.ended`	`SessionEndedEvent`	-
`signal.detected`	`SignalDetectedEvent`	-
`signal.updated`	`SignalUpdatedEvent`	-
`signal.ended`	`SignalEndedEvent`	-
`engagement.updated`	`EngagementUpdatedEvent`	-
`conversation_quality.updated`	`ConversationQualityUpdatedEvent`	-
`feedback.generated`	`FeedbackGeneratedEvent`	-
`coverage.dropped`	`CoverageDroppedEvent`	-
`coverage.degraded`	`CoverageDegradedEvent`	-
`error`	`StreamErrorEvent`	-
`message`	`StreamEvent`	Fires for every server→client envelope, regardless of type.
`open`	`void`	Fires once when the WebSocket connection opens.
`close`	`StreamCloseInfo`	Fires once when the connection closes.
`socketError`	`Error`	Transport-level socket error (distinct from the `error` envelope).

WebSocketLike

The subset of the WHATWG WebSocket interface the SDK relies on. Both the browser WebSocket and Node 22+‘s global WebSocket satisfy this.

Properties

Property	Modifier	Type
`readyState`	`readonly`	`number`
`binaryType`	`public`	`string`

Methods

send()

send(data): void;

Parameters

Parameter	Type
`data`	`string` \| `Blob` \| `ArrayBufferLike` \| `ArrayBufferView`<`ArrayBufferLike`>

Returns

void

close()

close(code?, reason?): void;

Parameters

Parameter	Type
`code?`	`number`
`reason?`	`string`

Returns

void

addEventListener()

addEventListener(type, listener): void;

Parameters

Parameter	Type
`type`	`string`
`listener`	(`event`) => `void`

Returns

void

removeEventListener()

removeEventListener(type, listener): void;

Parameters

Parameter	Type
`type`	`string`
`listener`	(`event`) => `void`

Returns

void

Signal

A single social signal detected over a span of the analyzed media.

Properties

Property	Type	Description
`type`	`SignalType`	-
`start`	`number`	Start time in seconds.
`end`	`number`	End time in seconds.
`probability`	`Probability` \| `null`	-
`rationale`	`string` \| `null`	-
`modality`	`string`[]	Analysis modalities that detected this signal, naming the source of the evidence. When several tracks detect the same signal, every contributing modality is included.

EngagementStateEntry

A contiguous stretch of media labeled with a single engagement state.

Properties

Property	Type
`state`	`EngagementLevel`
`start`	`number`
`end`	`number`

ConversationQualityValues

The five conversation-quality dimension scores plus their mean (0–100).

Properties

Property	Type
`quality_index`	`number`
`clarity`	`number`
`authority`	`number`
`energy`	`number`
`rapport`	`number`
`learning`	`number`

ConversationQualityTimelineEntry

Conversation-quality scores for one window of the timeline.

Properties

Property	Type
`start`	`number`
`end`	`number`
`values`	`ConversationQualityValues`

ConversationQuality

Overall and time-varying conversation-quality scores.

Properties

Property	Type
`overall`	`ConversationQualityValues`
`timeline`	`ConversationQualityTimelineEntry`[]

InteractionFeedback

Structured interaction feedback returned by the coach model.

Properties

Property	Type
`type`	`FeedbackType`
`message?`	`string` \| `null`
`active_dimensions?`	`GoalDimension`[]
`primary_signal?`	`SignalType` \| `null`
`reason?`	`string` \| `null`

AnalysisResult

The full report returned by POST /v1/upload/analyze.

Properties

Property	Type
`signals`	`Signal`[]
`engagement_state`	`EngagementStateEntry`[]
`feedback?`	`InteractionFeedback` \| `null`
`conversation_quality?`	`ConversationQuality` \| `null`

AnalyzeUploadInput

Arguments for UploadClient.analyze.

Properties

Property	Type	Description
`file`	`VideoInput`	The video file to analyze (mp4/avi/mov/mkv/mpeg-ts/webm, ≥3s, ≤32MB).
`filename?`	`string`	Filename used when `file` is a `Blob` without a name. Defaults to `"video"`.
`include?`	`IncludeFlag`[]	Optional response sections to include. When omitted, conversation-quality scores are not returned.
`goalDimensions?`	`GoalDimension`[]	Optional goal dimensions for this interaction. Supplying at least one triggers interaction feedback. Ignored when `conversationContext` is set.
`conversationContext?`	`string`	Optional free-text scenario description. When set, it is the sole source of context for feedback generation and `goalDimensions` is ignored.
`signal?`	`AbortSignal`	Optional `AbortSignal` to cancel the request.

UploadClientOptions

Options for constructing an UploadClient.

Properties

Property	Type	Description
`tokenProvider`	`TokenProvider`	Supplies the bearer token attached to each request.
`baseUrl?`	`string`	Explicit base URL (e.g. `http://localhost:8080`). Overrides `environment`.
`environment?`	`Environment`	Named environment to target. Defaults to `"production"`.
`fetch?`	{ (`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; }	Custom `fetch` implementation. Defaults to the global `fetch`.

Type Aliases

Environment

type Environment = "production" | "staging";

A named Interhuman API environment.

RealtimeClientOptions

type RealtimeClientOptions = SessionSocketClientOptions;

Options for constructing a RealtimeClient.

AnalysisGroup

type AnalysisGroup = "visual" | "audio";

Top-level analysis surfaces a realtime session can run. Each group maps to one or more server-side analysis tracks: visual is the visual-signals track and audio the audio tracks.

RealtimeRecommendationFrequency

type RealtimeRecommendationFrequency = "high" | "medium" | "low";

How often the recommendation step runs, measured in analyzed video: high = every 10 seconds, medium = every 20 seconds, low = every 30 seconds. Only takes effect once realtime_recommendation_instructions has enabled recommendation.

RealtimeEvent

type RealtimeEvent = 
  | RealtimeSessionReadyEvent
  | RealtimeSessionUpdatedEvent
  | SessionClosingEvent
  | SessionEndedEvent
  | RealtimeSignalDetectedEvent
  | RealtimeSignalUpdatedEvent
  | SignalEndedEvent
  | TranscriptGeneratedEvent
  | RealtimeRecommendationGeneratedEvent
  | CoverageDroppedEvent
  | CoverageDegradedEvent
  | StreamErrorEvent;

Discriminated union of every realtime server→client envelope.

VideoChunk

type VideoChunk = Uint8Array | ArrayBuffer | ArrayBufferView | Blob;

A chunk of WebM or fragmented-MP4 video to stream to the server.

Listener

type Listener<T> = (payload) => void;

An event handler registered via on/once.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`payload`	`T`

Returns

void

StreamClientOptions

type StreamClientOptions = SessionSocketClientOptions;

Options for constructing a StreamClient.

StreamEvent

type StreamEvent = 
  | SessionReadyEvent
  | SessionUpdatedEvent
  | SessionClosingEvent
  | SessionEndedEvent
  | SignalDetectedEvent
  | SignalUpdatedEvent
  | SignalEndedEvent
  | EngagementUpdatedEvent
  | ConversationQualityUpdatedEvent
  | FeedbackGeneratedEvent
  | CoverageDroppedEvent
  | CoverageDegradedEvent
  | StreamErrorEvent;

Discriminated union of every server→client envelope.

WebSocketFactory

type WebSocketFactory = (url, protocols?) => WebSocketLike;

Constructs a WebSocketLike from a URL and optional subprotocols.

Parameters

Parameter	Type
`url`	`string`
`protocols?`	`string` \| `string`[]

Returns

WebSocketLike

ScopeValue

type ScopeValue = 
  | "interhumanai.upload"
  | "interhumanai.stream"
  | "interhumanai.realtime";

OAuth-style scopes an API key can carry.

SignalType

type SignalType = 
  | "agreement"
  | "confidence"
  | "confusion"
  | "disagreement"
  | "disengagement"
  | "engagement"
  | "frustration"
  | "hesitation"
  | "interest"
  | "skepticism"
  | "stress"
  | "tension"
  | "uncertainty";

Social signal types the model can detect. tension and frustration name the same underlying negative state but keep the detecting source legible: tension comes only from the Realtime API’s visual track, while frustration comes from every other source (Inter-1, the realtime audio track, and the upload and stream endpoints).

Probability

type Probability = "high" | "medium" | "low";

Confidence level attached to a detected signal.

EngagementLevel

type EngagementLevel = "engaged" | "neutral" | "disengaged";

Engagement state of the analyzed subject.

GoalDimension

type GoalDimension = "clarity" | "authority" | "energy" | "rapport" | "learning";

Conversation-quality dimensions a caller can flag as a session goal.

IncludeFlag

type IncludeFlag = "conversation_quality_overall" | "conversation_quality_timeline";

Optional response sections the caller may request.

FeedbackType

type FeedbackType = "feedback" | "no_feedback";

Discriminator for the structured interaction-feedback result.

VideoInput

type VideoInput = 
  | Blob
  | {
  data: Uint8Array | ArrayBuffer | Blob;
  filename?: string;
  contentType?: string;
};

The video to analyze. Either a Blob/File (browsers, or Node 18+ where Blob is global) or raw bytes plus a filename.

Union Members

Blob

Type Literal

{
  data: Uint8Array | ArrayBuffer | Blob;
  filename?: string;
  contentType?: string;
}

data

data: Uint8Array | ArrayBuffer | Blob;

Raw video bytes.

filename?

optional filename?: string;

Filename to report in the multipart part, e.g. "clip.mp4".

contentType?

optional contentType?: string;

MIME type, e.g. "video/mp4".

Variables

HTTP_BASE_URLS

const HTTP_BASE_URLS: Record<Environment, string>;

HTTP base URLs per named environment.

AnalysisGroup

AnalysisGroup: {
  Visual: "visual";
  Audio: "audio";
};

Named analysis-group constants.

Type Declaration

Visual

readonly Visual: "visual" = "visual";

The visual-signals track.

Audio

readonly Audio: "audio" = "audio";

The audio tracks.

RealtimeRecommendationFrequency

RealtimeRecommendationFrequency: {
  High: "high";
  Medium: "medium";
  Low: "low";
};

Named recommendation-frequency constants.

Type Declaration

High

readonly High: "high" = "high";

A recommendation runs every 10 seconds of analyzed video.

Medium

readonly Medium: "medium" = "medium";

A recommendation runs every 20 seconds of analyzed video.

Low

readonly Low: "low" = "low";

A recommendation runs every 30 seconds of analyzed video.

WS_READY_STATE

const WS_READY_STATE: {
  CONNECTING: 0;
  OPEN: 1;
  CLOSING: 2;
  CLOSED: 3;
};

readyState constants, mirrored from the WHATWG WebSocket spec.

Type Declaration

CONNECTING

readonly CONNECTING: 0 = 0;

OPEN

readonly OPEN: 1 = 1;

CLOSING

readonly CLOSING: 2 = 2;

CLOSED

readonly CLOSED: 3 = 3;

Scope

const Scope: {
  Upload: "interhumanai.upload";
  Stream: "interhumanai.stream";
  Realtime: "interhumanai.realtime";
};

Named scope constants.

Type Declaration

Upload

readonly Upload: "interhumanai.upload" = "interhumanai.upload";

Grants access to POST /v1/upload/analyze.

Stream

readonly Stream: "interhumanai.stream" = "interhumanai.stream";

Grants access to WS /v1/stream/analyze.

Realtime

readonly Realtime: "interhumanai.realtime" = "interhumanai.realtime";

Grants access to WS /v0/realtime/analyze.

GoalDimension

GoalDimension: {
  Clarity: "clarity";
  Authority: "authority";
  Energy: "energy";
  Rapport: "rapport";
  Learning: "learning";
};

Named goal-dimension constants.

Type Declaration

Clarity

readonly Clarity: "clarity" = "clarity";

Authority

readonly Authority: "authority" = "authority";

Energy

readonly Energy: "energy" = "energy";

Rapport

readonly Rapport: "rapport" = "rapport";

Learning

readonly Learning: "learning" = "learning";

IncludeFlag

IncludeFlag: {
  ConversationQualityOverall: "conversation_quality_overall";
  ConversationQualityTimeline: "conversation_quality_timeline";
};

Named include-flag constants.

Type Declaration

ConversationQualityOverall

readonly ConversationQualityOverall: "conversation_quality_overall" = "conversation_quality_overall";

ConversationQualityTimeline

readonly ConversationQualityTimeline: "conversation_quality_timeline" = "conversation_quality_timeline";

Functions

resolveHttpBaseUrl()

function resolveHttpBaseUrl(options): string;

Resolve the HTTP base URL for a client. baseUrl takes precedence (use it to point at a local server, e.g. http://localhost:8080); otherwise the named environment is used, defaulting to production. The returned URL never has a trailing slash.

Parameters

Parameter	Type
`options`	{ `baseUrl?`: `string`; `environment?`: `Environment`; }
`options.baseUrl?`	`string`
`options.environment?`	`Environment`

Returns

string

httpToWsBaseUrl()

function httpToWsBaseUrl(httpBaseUrl): string;

Derive the WebSocket origin from an HTTP base URL: https→wss, http→ws. Any path on the base URL is preserved (so a proxy mount point survives), with the trailing slash trimmed.

Parameters

Parameter	Type
`httpBaseUrl`	`string`

Returns

string

​Classes

​AuthClient

​Constructors

Constructor

Parameters

Returns

​Methods

createToken()

Parameters

Returns

Throws

createClientToken()

Parameters

Returns

Throws

revokeClientToken()

Parameters

Returns

Throws

​StaticTokenProvider

​Implements

​Constructors

Constructor

Parameters

Returns

​Methods

getToken()

Returns

Implementation of

​TokenManager

​Implements

​Constructors

Constructor

Parameters

Returns

​Methods

getToken()

Returns

Implementation of

invalidate()

Returns

​InterhumanClient

​Example

​Constructors

Constructor

Parameters

Returns

​Properties

​Methods

stream()

Returns

realtime()

Returns

getToken()

Returns

​InterhumanError

​Extends

​Extended by

​Constructors

Constructor

Parameters

Returns

Overrides

​InterhumanApiError

​Extends

​Constructors

Constructor

Parameters

Returns

Overrides

​Properties

​InterhumanConfigError

​Extends

​Constructors

Constructor

Parameters

Returns

Inherited from

​RealtimeClient

​Example

Classes

AuthClient

Constructors

Methods

StaticTokenProvider

Implements

Constructors

Methods

TokenManager

Implements

Constructors

Methods

InterhumanClient

Example

Constructors

Properties

Methods

InterhumanError

Extends

Extended by

Constructors

InterhumanApiError

Extends

Constructors

Properties

InterhumanConfigError

Extends

Constructors

RealtimeClient

Example

Extends

Constructors

Properties

Accessors

Methods

`abstract` SessionSocketClient

Extended by

Type Parameters

Constructors

Properties

Accessors