Build with the stream endpoint

1. Never ship your API key to the browser. Mint a short-lived, capped client token server-side and hand that to the client instead.
2. Let the browser stream directly to Interhuman with the client token. The token is designed for exactly this, and the API enforces its caps.
3. Send media segments exactly as the recorder produces them. Never re-slice, reassemble, or reinterpret the media container in between.

​

Why you can’t ship the API key

​

The architecture

• A token route on your backend calls POST /v1/client_tokens with your API key and returns the minted token to the browser. This is stateless, single-request work — a serverless function is fine here.
• The browser connects directly to wss://api.interhuman.ai/v1/stream/analyze with the client token, streams recorded segments up as binary frames, and receives analysis events back. The caps embedded in the token (duration, bytes, concurrency, video budget, allowed origins) are enforced by the API itself.

​

Mint a client token

import { AuthClient } from "@interhumanai/sdk";

const auth = new AuthClient();

export async function mintStreamToken() {
  const token = await auth.createClientToken({
    apiKey: process.env.INTERHUMAN_API_KEY,   // never leaves the server
    scopes: ["interhumanai.stream"],           // default
    expiresIn: 300,                            // seconds; clamped to 60–3600
    maxDurationSeconds: 600,                   // max wall-clock session length
    maxVideoSeconds: 600,                      // total video budget for this token
    allowedOrigins: ["https://app.example.com"],
  });
  return token.access_token;                   // safe to hand to the browser
}

curl -X POST https://api.interhuman.ai/v1/client_tokens \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ih_live_...",
    "scopes": ["interhumanai.stream"],
    "expires_in": 300,
    "max_duration_seconds": 600,
    "max_video_seconds": 600,
    "allowed_origins": ["https://app.example.com"]
  }'

​

Connect from the browser

import { StreamClient, StaticTokenProvider } from "@interhumanai/sdk";

const clientToken = await fetch("/api/stream/session").then((r) => r.text());

const stream = new StreamClient({
  tokenProvider: new StaticTokenProvider(clientToken),
});

stream.on("signal.detected", (e) => console.log(e.data.signal_type));
stream.on("engagement.updated", (e) => console.log(e.data));

await stream.connect();
await stream.waitForSessionReady();
stream.updateConfig({ include: ["conversation_quality_overall"] });
// now start recording and call stream.sendVideo(chunk) per segment

const ws = new WebSocket("wss://api.interhuman.ai/v1/stream/analyze", [
  "access_token",
  clientToken,
]);

​

Send media the way the recorder produces it

const recorder = new MediaRecorder(mediaStream, {
  mimeType: "video/webm;codecs=vp8,opus",
  videoBitsPerSecond: 1_000_000, // 1 Mbps is plenty for analysis
});

recorder.addEventListener("dataavailable", async (event) => {
  if (!event.data || event.data.size === 0) return;
  stream.sendVideo(await event.data.arrayBuffer()); // one segment = one binary frame
});

recorder.start(3000); // emit a self-contained segment every 3 seconds

• One recording, one giant frame. The endpoint enforces a 32 MB maximum WebSocket message size; a 3-minute recording at typical bitrates exceeds it, and you get an ih6002 (“message too large”) error or the upstream resets the socket mid-send (close code 1006, no close frame). Worse, large single messages fail unreliably even under the cap. Small and many beats big and one.
• Re-slicing the media in transit. Parsing the WebM/EBML structure yourself and cutting your own chunk boundaries is fragile: dropped trailing metadata or a mis-cut boundary produces a truncated container and an ih5004 (“malformed segment”) error. Container parsers that pass tests against synthetic ffmpeg files still mis-cut real live-muxed browser output.
• Concatenating timesliced segments later. MediaRecorder only writes the duration into the header on stop(), so stitching timeslice segments into one blob yields a broken file. Streaming each segment live and independently is fine; concatenation is not.

​

End the session cleanly

recorder.stop();
stream.requestClose(); // sends session.close
stream.on("session.ended", () => {
  mediaStream.getTracks().forEach((t) => t.stop());
});

​

Debugging: symptom → cause

​

Next steps

• Client tokens API — full request/response schema, scopes, and caps.
• TypeScript SDK reference — AuthClient, StreamClient, typed events, and upload support.
• Stream analysis quickstart — the endpoint call itself: session config, media frames, and event envelopes.
• Stream & analyze API reference — full AsyncAPI channel, headers, and message schemas.
• Error handling — structured error codes, including ih5004 and ih6002.