Text to Speech - WebSocket

The Voicemaker API supports a WebSocket for text to speech. Send text and receive base64 audio in order. Short text returns one audio message. Longer text is split and returned as sequential chunks, with isFinal: true on the last chunk.

WebSocket Endpoint

wss://developer.voicemaker.in/api/v1/voice/convert

Authentication

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

Authorization: Bearer YOUR-API-KEY

After the key is accepted, the server sends a plain text message:

Connected to WebSocket server

If the key is missing, disabled, expired, or not accepted, the server sends the error as plain text and closes the connection.

How It Works

Connect: Open the WebSocket with your API key. Wait for Connected to WebSocket server before sending text.

Send text: Send one JSON message per conversion. Each message is one request.

Short text: Text under 400 characters returns one JSON message. That message includes isFinal: true.

Longer text: Text of 400 characters or more is split and returned in order. Only the last message includes isFinal: true. Concatenate the audio chunks in the order they arrive.

Limit: Text cannot be longer than 3,000 characters.

Empty message: An empty message or {} closes the connection.

Timeout: The connection closes after one minute with no messages. Each message you send resets this timeout. The server then sends { "success": false, "message": "Connection timeout: No message received for one minute" } and closes.

Convert (JSON message)

{
    "VoiceId": "ai3-Jony",
    "LanguageCode": "en-US",
    "Text": "Welcome to Voicemaker API.",
    "OutputFormat": "mp3",
    "SampleRate": "48000",
    "MasterVolume": "0",
    "MasterSpeed": "0",
    "MasterPitch": "0"
}

SampleRate, MasterVolume, MasterSpeed, and MasterPitch are strings.

Request Parameters

Required

Text: Text to speak. Supports SSML on voices that accept it. Maximum 3,000 characters.

VoiceId: Voice id, 2 to 70 characters. Example: ai3-Jony.

LanguageCode: Language code for the voice, such as en-US, en-GB, or multi-lang for Pro voices.

Optional

Engine: standard or neural. Default: neural.

OutputFormat: mp3, wav, ogg, aac, opus, ulaw, or alaw. Default: mp3. Use mp3 when you need the lowest latency.

SampleRate: String. Common values: 8000, 16000, 22050, 24000, 44100, 48000. 48000 is recommended.

Effect: Voice effect, such as default. Availability depends on the voice.

MasterSettings: advanced_v1 or advanced_v2. Default: advanced_v1.

MasterVolume: String from -20 to 20. Default: 0.

MasterSpeed: String from -100 to 100. Default: 0.

MasterPitch: String from -100 to 100. Default: 0. With advanced_v1, pitch is not applied to neural AI1 voices.

AccentCode: Accent or language override. Compatible with AI1, Pro1, Pro2, ProPlus (Turbo, High-Res, and Expressive), and FlashX. Examples: en-US, fr-FR, auto.

Stability: ProPlus and custom Pro voices. 0 to 100. Default: 50. For the Expressive engine, use 0, 50, or 100.

Similarity: ProPlus and custom Pro voices. 0 to 100. Default: 80.

Style: ProPlus voices. Numeric.

SpeakerBoost: ProPlus voices. true or false.

Normalization: true or false.

ProEngine: ProPlus and custom Pro voices. turbo, highres, or expressive. Default: highres.

CustomFileName: 3 to 100 characters. Letters, numbers, dots, underscores, and hyphens only.
VoxFx is not applied on this WebSocket. Use the REST convert endpoint for VoxFx.
advanced_v2 applies MasterVolume, MasterSpeed, and MasterPitch after synthesis. Repeating the same VoiceId and Text while changing only those three fields does not charge characters again, and adds about 200 ms.

Response Format

Audio chunk

{
    "success": true,
    "audio": "base64-encoded-audio"
}

Final chunk

{
    "success": true,
    "audio": "base64-encoded-audio",
    "isFinal": true
}

Decode audio as base64. The bytes are the format requested in OutputFormat. For a single short request, this is the whole file. For a split request, join the chunks in order after isFinal: true.

Validation error

The connection stays open.

{
    "success": false,
    "message": "Validation error",
    "errors": ["Text is required and must be a non-empty string"]
}

Other error

{
    "success": false,
    "message": "Error converting your text, please check the tags or settings in the text."
}

Text to Speech - WebSocket

WebSocket Endpoint#

Authentication#

How It Works#

Convert (JSON message)#

Request Parameters#

Required#

Optional#

Response Format#

Audio chunk#

Final chunk#

Validation error#

Other error#

Example#