> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sully.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming

This API provides streaming speech-to-text transcriptions using WebSockets.

<Note>
  Endpoint:<br />`wss://api.sully.ai/v1/audio/transcriptions/stream?account_id=1234567890&api_token=1234567890&sample_rate=16000&language=en`
</Note>

## Headers

<ParamField query="X-API-KEY" type="string">
  The API key to use for authentication. Required if `X-API-TOKEN` is not provided.
</ParamField>

<ParamField query="X-API-TOKEN" type="string">
  The API token to use for authentication. Required if `X-API-KEY` is not provided.
</ParamField>

<ParamField query="X-ACCOUNT-ID" type="string">
  The account ID to use for authentication.
</ParamField>

## Query parameters

<ParamField query="language" type="string" default="en">
  The language of your submitted audio. See our [Supported Languages](/api-reference/audio-transcriptions/languages) documentation for a complete list of language options.
</ParamField>

<ParamField query="sample_rate" type="string" default="16000">
  The sample rate of your submitted audio. If omitted, the streaming service currently defaults to `16000`.
  For raw, headerless audio, send the actual sample rate of your stream explicitly.
</ParamField>

<ParamField query="encoding" type="string">
  Specifies the encoding format of the audio being sent.

  <b>Important:</b> This parameter is <b>required</b> when transmitting raw, unstructured audio packets without headers.
  If the audio data is encapsulated within a container format, this parameter should be omitted. When <code>sample\_rate</code> is omitted, the streaming service currently still defaults it to <code>16000</code>.

  <b>Supported formats:</b>

  <ul>
    <li><code>linear16</code>: 16-bit, little-endian, signed PCM WAV data</li>
    <li><code>linear32</code>: 32-bit, little-endian, floating-point PCM WAV data</li>
    <li><code>flac</code>: Free Lossless Audio Codec (FLAC) encoded data</li>
    <li><code>alaw</code>: A-law encoded WAV data</li>
    <li><code>mulaw</code>: Mu-law encoded WAV data</li>
    <li><code>amr-nb</code>: Adaptive Multi-Rate (AMR) narrowband codec</li>
    <li><code>amr-wb</code>: Adaptive Multi-Rate (AMR) wideband codec</li>
    <li><code>opus</code>: The Opus audio codec</li>
    <li><code>ogg-opus</code>: The Opus audio codec encapsulated in the Ogg container format</li>
    <li><code>speex</code>: An open-source, speech-specific audio codec</li>
    <li><code>g729</code>: G729 low-bandwidth codec (usable with raw or containerized audio)</li>
  </ul>
</ParamField>

<ParamField query="dictation" type="boolean" default="false">
  Requests dictation-oriented transcript formatting for the stream.
</ParamField>

<ParamField query="account_id" type="string">
  The account ID to use for authentication. Required if `X-ACCOUNT-ID` is not provided.
</ParamField>

<ParamField query="api_token" type="string">
  A temporary authentication token. Required if `X-API-KEY` is not provided.
</ParamField>

# When to use

The Speech-to-Text Websockets API is designed to generate text from partial audio input. It's well-suited for scenarios where the input audio is being streamed or generated in chunks.

# Protocol

The WebSocket API uses a bidirectional protocol that encodes all messages as JSON objects.

## Connection Status Messages

Upon successful connection, the server sends a status message:

```json theme={null}
{
  "type": "status",
  "status": "connected",
  "timestamp": "2026-04-22T14:32:07.123Z"
}
```

When the connection closes:

```json theme={null}
{
  "type": "status",
  "status": "disconnected",
  "timestamp": "2026-04-22T14:32:17.123Z"
}
```

<Note>
  **Important:** Wait for the `type: "status"` / `status: "connected"` message before sending audio data. This ensures the server is ready to process your stream.
</Note>

## Error Messages

During a live stream, the server may also send an error message:

```json theme={null}
{
  "type": "error",
  "error": "An error occurred during transcription",
  "timestamp": "2026-04-22T14:32:12.123Z"
}
```

<Note>
  An error message signals a transcription problem, but it does not always mean
  the session is over. Some runtime error frames are non-terminal and may be
  followed by later transcript or status messages, while other failures are
  followed by socket closure. Surface the error immediately, then keep
  listening for follow-up messages and reconnect when the socket actually
  closes.
</Note>

# Streaming input audio

The client can send messages with audio input to the server. The messages can contain the following fields:

```json theme={null}
{
  "audio": "Y3VyaW91cyBtaW5kcyB0aGluayBhbGlrZSA6KQ=="
}
```

<ParamField body="audio" type="string" required>
  A generated partial audio chunk encoded as a base64 string.
</ParamField>

<Note>
  **Browser MediaRecorder Notice:** When using Chrome's MediaRecorder API, the first audio chunk contains critical header information. Always send this first chunk for proper audio processing. Failing to include header information may result in transcription errors or complete failure.
</Note>

## Streaming output audio

Transcript messages contain the following fields:

```json Response message theme={null}
{
  "type": "transcript",
  "audio_start": 0,
  "audio_end": 3.2,
  "duration": 3.2,
  "text": "Hello, world",
  "isFinal": false, 
  "is_final": false,
  "words": [
    {
      "word": "Hello",
      "start": 0.2,
      "end": 0.7,
      "confidence": 0.9856743,
      "punctuated_word": "Hello,"
    },
    {
      "word": "world",
      "start": 0.9,
      "end": 1.2,
      "confidence": 0.9978341,
      "punctuated_word": "world"
    }
  ],
  "timestamp": "2023-08-15T14:32:07.123Z"
}
```

<ResponseField name="type" type="string">
  The type of response, will be "transcript" for transcription results.
</ResponseField>

<ResponseField name="audio_start" type="number">
  Start time of the audio segment in seconds.
</ResponseField>

<ResponseField name="audio_end" type="number">
  End time of the audio segment in seconds.
</ResponseField>

<ResponseField name="duration" type="number">
  Duration of the audio segment in seconds.
</ResponseField>

<ResponseField name="text" type="string">
  The processed text sequence.
</ResponseField>

<ResponseField name="isFinal" type="boolean" deprecated>
  Indicates if the generation is complete. <b>Deprecated:</b> Use <code>is\_final</code> instead.
</ResponseField>

<ResponseField name="is_final" type="boolean">
  Indicates if the generation is complete.
</ResponseField>

<ResponseField name="words" type="array">
  Array of word objects with text content and timing information:

  <ul>
    <li><code>word</code>: The raw word as recognized</li>
    <li><code>start</code>: Start time of the word in seconds</li>
    <li><code>end</code>: End time of the word in seconds</li>
    <li><code>confidence</code>: Confidence score between 0-1 for the word recognition</li>
    <li><code>punctuated\_word</code>: The word with proper capitalization and punctuation</li>
  </ul>
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO-formatted timestamp when the response was generated.
</ResponseField>