Transcribe audio (WebSocket)

Connect and authenticate

Connect to wss://api.inworld.ai/stt/v1/transcribe:streamBidirectional. Server-side clients send Authorization: Basic <INWORLD_API_KEY> on the WebSocket upgrade request. Use the Base64 credentials copied from the Portal verbatim; do not Base64-encode them again.

const WebSocket = require('ws');
const ws = new WebSocket(
  'wss://api.inworld.ai/stt/v1/transcribe:streamBidirectional',
  { headers: { Authorization: `Basic ${process.env.INWORLD_API_KEY}` } }
);

This uses the Node.js ws package. For browser or mobile clients, keep the API key on your server. Either relay audio through an authenticated backend connection or connect directly using a one-time token minted by your backend.

The browser's native WebSocket constructor cannot set an Authorization header. For a direct connection, pass the token in the bearer_ WebSocket subprotocol:

// Your authenticated backend endpoint mints the token; never expose the API key.
// See the one-time-token guide for the backend handler and user authorization.
const response = await fetch('/api/inworld-token', {
  method: 'POST',
  credentials: 'same-origin',
  cache: 'no-store',
});
if (!response.ok) throw new Error(`Token request failed (${response.status})`);
const { accessToken } = await response.json();
const ws = new WebSocket(
  'wss://api.inworld.ai/stt/v1/transcribe:streamBidirectional',
  ['bearer_' + accessToken],
);

Mint a fresh token for every connection attempt, including retries and reconnects. Do not put tokens in URL query parameters. Clients that can set headers may send Authorization: Bearer <accessToken> instead. Follow your application's CSRF requirements when calling the backend token endpoint. See the one-time-token guide for the complete backend flow.

Handle connection/upgrade errors as well as JSON error messages after connection. A failed handshake may never produce a transcription or JSON error frame; report it to the caller instead of waiting indefinitely for a transcript.

Streaming message sequence

Send each client message below as a separate JSON text frame. Responses can arrive while you are sending audio; read them concurrently.

1. Configure the stream first:

   {"transcribeConfig":{"modelId":"inworld/inworld-stt-1","audioEncoding":"LINEAR16","sampleRateHertz":16000,"numberOfChannels":1}}

2. Send audio chunks. Replace the placeholder with Base64-encoded raw PCM bytes:

   {"audioChunk":{"content":"<base64-encoded PCM>"}}

3. Receive interim transcripts automatically. Each interim replaces the previous interim for the current turn; it is not a text delta:

   {"result":{"transcription":{"transcript":"Please open","isFinal":false}}}
   {"result":{"transcription":{"transcript":"Please open the door","isFinal":false}}}

4. Commit each final once, then clear the interim. Later audio starts a new turn:

   {"result":{"transcription":{"transcript":"Please open the door.","isFinal":true}}}

5. To finish sending audio, flush your last partial audio chunk and send:

   {"closeStream":{}}

Keep reading until the server closes the stream, including any final transcripts and result.usage. A final transcript ends a turn, not necessarily the stream. Do not close the socket immediately after sending the control message.

Turn boundaries and shutdown

At shutdown, send closeStream once; do not precede it with endTurn for the same audio. Repeated finalization of an empty or silent turn can produce unwanted transcripts. With automatic turn detection, pauses can already produce finals; listen for them without sending an extra endTurn for each pause.

endTurn alone does not finish the session or request final usage. Disconnecting the transport can lose pending results and usage. Set a client-side shutdown timeout and surface a timeout as incomplete transcription, rather than silently treating a trailing interim as final. Result cadence and finalization latency vary with audio and model processing; a short quiet period is not a completion signal.

Voice activity events

Speech events are separate from transcription results and do not themselves finalize a transcript. Example wire messages:

{"result":{"speechStarted":{"startTimeMs":0,"confidence":0}}}
{"result":{"speechStopped":{"silenceDurationMs":150}}}

speechStopped.silenceDurationMs describes silence when that event was emitted; it is not a continuously updated idle timer. Use transcription.isFinal to commit text. For an application idle-stop policy, maintain your own timer and reset it on speech activity and transcription results. See Turn detection.

Audio capture and runnable examples

Use signed 16-bit little-endian PCM (LINEAR16). Streaming does not accept MediaRecorder WebM/Opus or Ogg/Opus chunks. Convert captured Float32 samples to PCM16, and set sampleRateHertz to the actual rate of the samples you send. 16 kHz mono is a convenient starting point; 48 kHz PCM input is also resampled by the service. Changing the declared rate does not resample the audio.

The samples send 100 ms per chunk: 1,600 samples or 3,200 bytes at 16 kHz mono, before Base64 encoding. This is an example chunk size, not a protocol limit. Flush the final shorter chunk before sending closeStream.

For browser capture with an AudioWorklet, keep the processing graph connected to the destination through a zero-gain node, and wait for the worklet to flush its buffered samples before stopping the stream. Release microphone tracks and the audio context on completion or failure.

Start with the Node.js samples or Python samples. Both include file and microphone clients. The sample PCM audio is raw 16 kHz mono PCM16, so you can verify authentication, streaming and shutdown before adding microphone capture.

{
  "transcribeConfig": {
    "modelId": "inworld/inworld-stt-1",
    "audioEncoding": "LINEAR16",
    "sampleRateHertz": 16000,
    "language": "en"
  }
}

{
  "audioChunk": {
    "content": "<BASE64_AUDIO>"
  }
}

{
  "endTurn": {}
}

{
  "closeStream": {}
}

{
  "result": {
    "transcription": {
      "transcript": "Open the door and let me in, please.",
      "isFinal": true,
      "wordTimestamps": [],
      "voiceProfile": null,
      "silenceDurationMs": 0
    }
  }
}

{
  "result": {
    "usage": {
      "transcribedAudioMs": 2400,
      "modelId": "inworld/inworld-stt-1"
    }
  }
}

{
  "result": {
    "speechStarted": {
      "startTimeMs": 0,
      "confidence": 0
    }
  }
}

{
  "result": {
    "speechStopped": {
      "silenceDurationMs": 750
    }
  }
}