Speech to Text - WebSocket

The Voicemaker API supports a WebSocket for real-time speech to text. Stream microphone or file audio to the API and receive partial transcripts as the speaker talks, then a committed transcript when a phrase is complete.

WebSocket Endpoint

wss://developer.voicemaker.in/api/v1/speech-to-text/realtime

Session options can also be passed as query parameters on this URL. A later start message overrides the same fields.

wss://developer.voicemaker.in/api/v1/speech-to-text/realtime?audioFormat=pcm_16000&language=en-US&commitStrategy=vad

Authentication

Authentication is required when the WebSocket connection is opened. Send the API key in the Authorization header:

Authorization: Bearer YOUR-API-KEY

Browser clients that cannot set headers may pass the key as a query parameter instead:

wss://developer.voicemaker.in/api/v1/speech-to-text/realtime?apiKey=YOUR-API-KEY

How It Works

Connect: Open the WebSocket with your API key. The server replies with a connected message after the key is accepted.

Configure: Send an optional JSON start message before the first audio chunk. Defaults are 16 kHz PCM, voice-activity commit, and automatic language detection.

Ready: After speech recognition starts, the server sends a ready message. Audio sent before that message is buffered. Wait for ready before streaming a long recording.

Send audio: Send raw binary frames, or JSON messages with base64 audio. Audio must be mono and must match audioFormat.

Partials: While speech is in progress, the server sends partial messages with the current best transcript. These can change as more audio arrives.

Commit: With commitStrategy: "vad" (the default), a phrase is committed automatically after a short silence. With commitStrategy: "manual", send a commit message when the phrase should be finalized.

Committed transcript: A committed message includes isFinal: true and the text for that phrase. Keep the socket open to transcribe the next phrase.

Close: Close the WebSocket when you are finished. Usage is billed when the connection closes.

Timeout: The connection closes after one minute with no messages. Each message you send resets this timeout.

Start session (optional JSON message)

{
    "type": "start",
    "model": "stt-flagship-realtime",
    "audioFormat": "pcm_16000",
    "sampleRate": 16000,
    "language": "en-US",
    "commitStrategy": "vad",
    "includeTimestamps": false,
    "vadSilenceThresholdSecs": 0.6
}

Send audio (JSON message)

{
    "audio": "base64-encoded-pcm-chunk",
    "commit": false
}

Binary WebSocket frames are also accepted. A binary frame is one audio chunk and is not committed by itself.

Commit (manual strategy)

{
    "type": "commit"
}

You can also commit the chunk you are sending:

{
    "audio": "base64-encoded-pcm-chunk",
    "commit": true
}

Request Parameters

Session fields

Send these on the WebSocket URL or in the first JSON message. They cannot be changed after the first audio chunk or commit.

model (optional): stt-flagship-realtime. This is the only model on this endpoint. Default: stt-flagship-realtime.

audioFormat (optional): pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_44100, pcm_48000, or ulaw_8000. Default: pcm_16000.

sampleRate (optional): Must match the format: 8000, 16000, 22050, 24000, 44100, or 48000. ulaw_8000 uses 8000. Default: the rate for audioFormat.

language (optional): BCP-47 code such as en-US, hi-IN, or es-ES, or a short code such as en. Omit this field to detect the language automatically. languageCode is accepted as an alias.

commitStrategy (optional): vad or manual. Default: vad.

includeTimestamps (optional): true or false. When true, each committed message includes word timings. Default: false.

previousText (optional): Up to 50 characters of earlier transcript. This improves recognition of the first phrase. It is applied once, on the first audio chunk.

vadThreshold (optional, vad only): Voice-activity sensitivity from 0 to 1.

vadSilenceThresholdSecs (optional, vad only): Silence, in seconds, before a phrase is committed. 0.1 to 10. Default: 0.6.

minSpeechDurationMs (optional, vad only): Minimum speech length before a phrase can commit, in milliseconds. 0 to 10000.

minSilenceDurationMs (optional, vad only): Minimum silence length before a phrase can commit, in milliseconds. 0 to 10000.

Audio

PCM formats are 16-bit little-endian, mono, at the sample rate in audioFormat.

ulaw_8000 is 8-bit mu-law, mono, at 8000 Hz.

Send audio in short chunks, about 100–200 ms each. Larger chunks are accepted and split by the server.

With commitStrategy: "manual", send a commit when the speaker finishes a phrase. Committing too often returns an error.

Response Format

Connected

Sent once, after the API key is accepted.

{
    "success": true,
    "type": "connected",
    "model": "stt-flagship-realtime"
}

Ready

Sent when speech recognition is ready for audio.

{
    "success": true,
    "type": "ready",
    "model": "stt-flagship-realtime",
    "sessionId": "session-id",
    "audioFormat": "pcm_16000",
    "sampleRate": 16000,
    "commitStrategy": "vad"
}

Partial transcript

{
    "success": true,
    "type": "partial",
    "text": "welcome to"
}

Committed transcript

{
    "success": true,
    "type": "committed",
    "text": "Welcome to Voicemaker.",
    "isFinal": true
}

Committed transcript with timestamps

Returned when includeTimestamps is true.

{
    "success": true,
    "type": "committed",
    "text": "Welcome to Voicemaker.",
    "isFinal": true,
    "language": "eng",
    "words": [
        {
            "word": "Welcome",
            "startTime": 0.12,
            "endTime": 0.48
        },
        {
            "word": "to",
            "startTime": 0.48,
            "endTime": 0.61
        }
    ]
}

startTime and endTime are seconds from the start of the committed phrase. speakerId is included on a word when a speaker label is available.

Error response

{
    "success": false,
    "message": "Invalid audioFormat. Use pcm_16000, pcm_8000, pcm_22050, pcm_24000, pcm_44100, pcm_48000, or ulaw_8000."
}

The connection stays open for a malformed JSON message, an empty audio chunk, or a message that is not a start, audio chunk, or commit. Other errors close the connection.

Speech to Text - WebSocket

WebSocket Endpoint#

Authentication#

How It Works#

Start session (optional JSON message)#

Send audio (JSON message)#

Commit (manual strategy)#

Request Parameters#

Session fields#

Audio#

Response Format#

Connected#

Ready#

Partial transcript#

Committed transcript#

Committed transcript with timestamps#

Error response#

Example#