Text to Speech (WebSocket)

Overview

The WebSocket endpoint enables real-time audio streaming with low-latency. Unlike the REST API, audio chunks are delivered as they’re generated, making it ideal for:

Live voice assistants
Real-time call center applications
Interactive voice response (IVR) systems
Any application requiring immediate audio feedback

Authentication

Pass your API key in the Authorization header as a Bearer token when establishing the WebSocket connection.

const ws = new WebSocket('wss://api.tts.timepay.ai/api/v1/get_speech', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Always use wss:// (secure WebSocket) in production environments.

Concurrency Model

Users can open multiple connections. The concurrency limit only applies when actively processing speech requests.

For example, if your plan allows 5 concurrent requests:

You can maintain 10 open connections
Only 5 can generate speech simultaneously
Additional requests will throw 429 rate limit error

Request Format

string

required

Must be "speech" for TTS requests.

string

required

The text to convert to speech.

string

required

The specific voice ID to use for synthesis. See available voices below.

string

default:"en"

ISO language code for the speech output.Supported languages: en, hi, mr, ta, te, gu, kn, ml, bn, pa, od, as

boolean

default:true

If true, adds a WAV header to the audio stream for immediate playback.

number

default:24000

Audio sample rate in Hz.Supported values: 8000, 16000, 24000

number

Playback speed multiplier. Range: 0.5 to 2.0, where 1.0 is normal speed.

string

Optional custom identifier for tracking requests. Auto-generated if not provided.

Available Voices

Voice Name	Voice ID
Kartik	`Ogbs15oBevLzXsUuTtA1`
Rahul	`Owbs15oBevLzXsUurdA_`
Nisha	`PAbs15oBevLzXsUu4dCi`
Tulsi	`PQbt15oBevLzXsUuNtD3`
Seema	`Pgbt15oBevLzXsUubdA6`

Example Request

{
  "type": "speech",
  "request_id": "req_12345",
  "text": "Hello, welcome to Vox.",
  "voice_id": "Ogbs15oBevLzXsUuTtA1",
  "language": "en",
  "add_wav_header": true,
  "sample_rate": 24000,
  "speed": 1.0
}

Minimal Request

{
  "type": "speech",
  "text": "Hello, welcome to Vox.",
  "voice_id": "PAbs15oBevLzXsUu4dCi"
}

Response Messages

The server sends multiple message types during a speech generation request:

Connection Established

Sent immediately after successful authentication.

string

Always "connected"

string

Unique identifier for this WebSocket connection.

{
  "type": "connected",
  "connection_id": "conn_abc123",
  "message": "Connected successfully"
}

Audio Chunks

Streamed audio data. Multiple chunks are sent per request.

string

Always "audio_chunk"

string

The request identifier.

integer

Zero-indexed position in the audio stream.

string

Base64-encoded audio data (PCM 16-bit, 24kHz mono by default).

{
  "type": "audio_chunk",
  "request_id": "req_12345",
  "chunk_index": 0,
  "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgA..."
}

Request Complete

Signals all audio has been sent.

string

Always "complete"

string

The request identifier.

integer

Total number of audio chunks sent.

integer

Characters processed (for billing verification).

{
  "type": "complete",
  "request_id": "req_12345",
  "total_chunks": 15,
  "characters": 47
}

Error

Indicates a problem with the request.

string

Always "error"

string

The request identifier (if available).

string

Error code for programmatic handling.

string

Human-readable error description.

{
  "type": "error",
  "request_id": "req_12345",
  "error": "concurrency_limit_exceeded",
  "message": "Maximum concurrent requests (5) exceeded"
}

Error Codes

Code	Description
`invalid_request`	Malformed JSON or missing required fields
`invalid_voice`	Specified voice not found
`invalid_language`	Unsupported language code
`text_too_long`	Text exceeds maximum character limit
`concurrency_limit_exceeded`	Too many simultaneous requests
`insufficient_credits`	Account balance too low
`internal_error`	Server-side processing error

Complete Example

import websockets

async def connect():
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
    async with websockets.connect(
        'wss://api.tts.timepay.ai/api/v1/get_speech',
        extra_headers=headers
    ) as ws:
        # Your code here
        pass

const WebSocket = require('ws');

const ws = new WebSocket('wss://api.tts.timepay.ai/api/v1/get_speech', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Best Practices

Connection Management

Reuse WebSocket connections for multiple requests
Implement automatic reconnection with exponential backoff
Send periodic pings to keep connections alive (every 30 seconds)
Close connections gracefully when no longer needed

Audio Handling

Buffer audio chunks before playback for smoother experience
Default audio format: PCM 16-bit, 24kHz, mono
Use Web Audio API for browser playback
Consider using a streaming audio player for real-time playback

Error Handling

Always handle the error message type
Implement request timeouts (recommended: 30 seconds)
Queue requests when concurrency limit is reached
Log request_id for debugging and support

API documentation

Endpoint examples

Text to Speech (WebSocket)

Overview

Authentication

Concurrency Model

Request Format

Available Voices

Response Messages

Connection Established

Audio Chunks

Request Complete

Error

Error Codes

Complete Example

Best Practices

​Overview

​Authentication

​Concurrency Model

​Request Format

​Available Voices

​Response Messages

​Connection Established

​Audio Chunks

​Request Complete

​Error

​Error Codes

​Complete Example

​Best Practices

Overview

Authentication

Concurrency Model

Request Format

Available Voices

Response Messages

Connection Established

Audio Chunks

Request Complete

Error

Error Codes

Complete Example

Best Practices