WebSocket

Transcribe audio (WebSocket)

WSSwss://api.inworld.ai/stt/v1/transcribe:streamBidirectional

Bidirectional streaming API for real-time speech-to-text transcription over WebSocket.

This method listens for streaming audio input and returns recognized text chunks one by one as soon as they are ready. Audio chunks are expected to be a part of a single voice input. Suitable for streaming live conversations, microphone input, or other streaming audio sources.

To use the API:

Send a transcribeConfig message first to configure the session (model, language, audio encoding, etc.).
Stream audioChunk messages containing raw audio bytes.
Receive transcription results as they become available, including both interim (partial) and final results.
Listen for speechStarted and speechStopped events to detect voice activity changes.
Optionally send endTurn to signal end of a speaker's turn.
Send closeStream when done.

Client messages

transcribeConfig

Configure the transcription session. Must be the first message sent. On the wire, wrap the fields below in a top-level transcribeConfig key (see the example) — an unwrapped config is rejected and the socket closes without an error frame.

Payload

modelIdstringrequired

The identifier of the model to use for transcription. Format: "{provider}/{model-name}".

Available models:

inworld/inworld-stt-1 — Inworld first-party

See STT Introduction for the full model catalogue.

audioEncodingenum<string>requireddefault: "AUDIO_ENCODING_UNSPECIFIED"

Supported audio encoding formats.

AUDIO_ENCODING_UNSPECIFIED: Not specified. Will return an error.
AUTO_DETECT: Automatically detect audio encoding from the audio header.
LINEAR16: Uncompressed 16-bit signed little-endian samples (Linear PCM).
MP3: MP3 audio. Not supported for streaming transcription.
OGG_OPUS: Opus encoded audio wrapped in an OGG container. Not supported for streaming transcription.
FLAC: FLAC encoded audio. Lossless format. Not supported for streaming transcription.

Available options:AUDIO_ENCODING_UNSPECIFIEDAUTO_DETECTLINEAR16MP3OGG_OPUSFLAC

languagestring

Language hint in ISO 639 format (e.g., "en", "ja"). Biases the model toward the specified language during automatic language detection. BCP-47 codes (e.g., "en-US") are also accepted and converted to the base language code. The hint additionally constrains the output script for English, Chinese, Cantonese, Japanese, Korean, Russian, and Hindi (e.g. selecting en keeps output in Latin script). See Language Support for the full list of supported languages.

sampleRateHertzinteger

Sample rate of the audio data in Hertz. Required when the sample rate cannot be inferred from the audio header (e.g., raw PCM streams). Default: 16000.

numberOfChannelsinteger

Number of channels in the audio data. Required when the number of channels cannot be inferred from the audio header (e.g., raw PCM streams). Default: 1.

inactivityTimeoutSecondsinteger

Inactivity timeout in seconds. If the client is silent for this duration, the transcription will be stopped.

endOfTurnConfidenceThresholdnumber

Confidence threshold for end-of-turn prediction. Higher values reduce false-positives. Range: [0.0, 1.0]. Default: 0.5. See the Turn Detection guide for tuning guidance.

promptsstring[]

Custom vocabulary / key terms. An array of context strings (names, jargon, acronyms) that bias the model toward recognizing these terms. This is a soft bias that helps with ambiguous or uncommon words; it is not a hard keyword lock and does not force exact output. Use letters, digits, spaces, and basic punctuation; other characters (such as #, /, @, or |) are rejected by the gateway with INVALID_ARGUMENT (code 3).

includeWordTimestampsboolean

If true, includes per-word timing information in the response.

enableSpeakerDiarizationboolean

Labels transcribed words with a per-stream speaker identifier. Experimental for inworld/inworld-stt-1 — speaker attribution quality is still improving and speakers may occasionally be misattributed. Set it together with includeWordTimestamps; speaker labels are returned on wordTimestamps[].speaker, and some words may arrive without a label (treat those as unattributed). See the Speaker Diarization guide.

inworldSttV1Configobject

Configuration for Inworld STT 1 models. Set vadThreshold to 0 to disable server-side turn detection and control turn boundaries manually via endTurn — see the Turn Detection guide.

Show child attributes

minEndOfTurnSilenceWhenConfidentinteger

Minimum silence duration when confidence is high (milliseconds).

vadThresholdnumber

Voice activity detection threshold. Range: [0.0, 1.0]. Default: 0.5.

voiceProfileConfigobject

Configuration for voice profile detection.

Show child attributes

enableVoiceProfilebooleanrequired

Enables voice profile feature for this request or stream.

topNinteger

Number of top labels from each class to return. Default: 10.

Example

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

audioChunk

Send a chunk of audio data for transcription. Must be sent after the initial transcribe config message. On the wire, wrap the fields below in a top-level audioChunk key (see the example).

Payload

contentstringrequired

The raw audio bytes in the encoding specified by the transcribe config's audioEncoding.

Example

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

endTurn

Signal the end of a speaker's turn. Send as {"endTurn": {}}. See the Turn Detection guide for automatic vs. manual turn control.

Example

{
  "endTurn": {}
}

closeStream

Signal that the client is done sending audio data. Send as {"closeStream": {}}. Required for HTTP/WebSocket clients since there is no equivalent to gRPC stream close.

Example

{
  "closeStream": {}
}

Server messages

transcription

Transcription result streamed back as audio is processed. May be an interim (partial) result or a final result depending on the isFinal field. Arrives wrapped under a top-level result key as result.transcription (see the example).

Payload

transcriptstring

Full transcribed text for this segment.

isFinalboolean

Indicates whether this is a finalized result or an interim (partial) result that may be updated as more audio is processed.

wordTimestampsobject[]

Per-word timing and confidence data. Only populated when includeWordTimestamps is enabled. Not yet supported for inworld/inworld-stt-1.

Show child attributes

wordstring

The transcribed word.

confidencenumber

Recognition confidence score for this word. Range: [0.0, 1.0].

startTimeMsinteger

Offset from the beginning of the audio to the start of this word, in milliseconds.

endTimeMsinteger

Offset from the beginning of the audio to the end of this word, in milliseconds.

speakerinteger

Speaker identifier for this word when diarization is enabled. Integers are assigned per stream in order of first appearance. May be absent on some words even when diarization is enabled — treat unlabeled words as unattributed. See the Speaker Diarization guide.

voiceProfileobjectnull

Voice Profile classification results. null unless voiceProfileConfig.enableVoiceProfile is set in the transcribe config. See the Voice Profiles guide for the category structure.

silenceDurationMsinteger

Duration of trailing silence detected for this result, in milliseconds.

Example

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

usage

Usage metrics for billing and monitoring purposes. Sent when the stream ends, wrapped under a top-level result key as result.usage.

Payload

transcribedAudioMsinteger

The duration of the transcribed audio in milliseconds.

modelIdstring

The identifier of the model used for transcription.

Example

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

speechStarted

Signal to indicate the start of a speaker's speech. Sent when voice activity is detected in the audio stream, wrapped under a top-level result key as result.speechStarted.

Payload

startTimeMsinteger

The timestamp of the start of the speech in milliseconds.

confidencenumber

The confidence score of the speech detection.

Example

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

speechStopped

Signal raised when STT detects silence after speech has stopped. Useful for tracking pauses and implementing custom turn-taking logic. Arrives wrapped under a top-level result key as result.speechStopped.

Payload

silenceDurationMsinteger

The duration of silence detected after speech stopped, in milliseconds.

Example

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