> ## Documentation Index > Fetch the complete documentation index at: https://docs.voxnexus.ai/llms.txt > Use this file to discover all available pages before exploring further. # TTS Realtime > WebSocket Real-time Text-to-Speech Channel Through this channel, clients can: 1. Send initialization messages to configure voice parameters 2. Send text messages for real-time speech synthesis 3. Receive audio data streams **Connection**: - Authentication via header: `X-Api-Key: YOUR_API_KEY` - Authentication via query: `?token=YOUR_API_KEY` **Message Format**: All messages are in JSON format, containing a `type` field to identify the message type ## AsyncAPI ````yaml api-reference/asyncapi.yaml ttsRealtime id: ttsRealtime title: TTS Realtime description: > WebSocket Real-time Text-to-Speech Channel Through this channel, clients can: 1. Send initialization messages to configure voice parameters 2. Send text messages for real-time speech synthesis 3. Receive audio data streams **Connection**: - Authentication via header: `X-Api-Key: YOUR_API_KEY` - Authentication via query: `?token=YOUR_API_KEY` **Message Format**: All messages are in JSON format, containing a `type` field to identify the message type servers: - id: production protocol: wss host: api.voxnexus.ai bindings: [] variables: [] address: /v1/tts/realtime parameters: [] bindings: [] operations: - &ref_1 id: receiveTTSClientMessages title: Receive t t s client messages type: receive messages: - &ref_3 id: TTSInitMessage payload: - name: TTS Initialization Message type: object properties: - name: type type: string description: Message type enumValues: - init required: true - name: voice_id type: string description: Voice ID (required) required: true - name: model_id type: string description: Model ID (required) required: true - name: language type: string description: Language code (optional) required: false - name: format type: string description: >- Audio format (optional, default: pcm). pcm is supported for every voice; mp3/ogg availability depends on the voice. WAV is not supported on the realtime stream; request pcm and add a container client-side if needed. enumValues: - pcm required: false - name: sample_rate type: integer description: 'Sample rate (optional, default: 16000)' enumValues: - 16000 - 24000 - 48000 required: false - name: bit_rate type: integer description: >- Bit rate (kbps), only valid for compressed formats (NOT SUPPORTED YET) deprecated: true required: false - name: speed type: number description: 'Speech rate multiplier (optional, default: 1.0)' required: false - name: pitch type: integer description: 'Pitch offset (optional, default: 0)' required: false - name: volume type: number description: 'Volume multiplier (optional, default: 1.0)' required: false - name: voice_config type: object description: >- Voice-specific configuration (optional) — a flat key-value map; supported keys are listed in the voice's config_schema (GET /v1/voices/{voice_id}), unknown keys are ignored required: false headers: [] jsonPayloadSchema: type: object description: TTS WebSocket initialization message (sent by client) properties: type: type: string enum: - init description: Message type x-parser-schema-id: voice_id: type: string description: Voice ID (required) example: vn-xiaoxiao x-parser-schema-id: model_id: type: string description: Model ID (required) example: vn-tts-basic x-parser-schema-id: language: type: string description: Language code (optional) example: en-US x-parser-schema-id: format: type: string description: >- Audio format (optional, default: pcm). pcm is supported for every voice; mp3/ogg availability depends on the voice. WAV is not supported on the realtime stream; request pcm and add a container client-side if needed. enum: - pcm default: pcm x-parser-schema-id: sample_rate: type: integer description: 'Sample rate (optional, default: 16000)' enum: - 16000 - 24000 - 48000 default: 16000 x-parser-schema-id: bit_rate: type: integer description: >- Bit rate (kbps), only valid for compressed formats (NOT SUPPORTED YET) deprecated: true default: 128 example: 128 x-parser-schema-id: speed: type: number format: float description: 'Speech rate multiplier (optional, default: 1.0)' minimum: 0.5 maximum: 2 default: 1 x-parser-schema-id: pitch: type: integer description: 'Pitch offset (optional, default: 0)' minimum: -12 maximum: 12 default: 0 x-parser-schema-id: volume: type: number format: float description: 'Volume multiplier (optional, default: 1.0)' minimum: 0 maximum: 1 default: 1 x-parser-schema-id: voice_config: type: object description: >- Voice-specific configuration (optional) — a flat key-value map; supported keys are listed in the voice's config_schema (GET /v1/voices/{voice_id}), unknown keys are ignored additionalProperties: true example: style: cheerful role: Girl style_degree: 0.5 x-parser-schema-id: required: - type - voice_id - model_id x-parser-schema-id: title: TTS Initialization Message example: No examples found bindings: [] extensions: - id: x-parser-unique-object-id value: TTSInitMessage - id: x-parser-message-name value: TTSInitMessage - &ref_4 id: TTSTextMessage payload: - name: TTS Text Message type: object properties: - name: type type: string description: Message type enumValues: - text required: true - name: text type: string description: Text content (required) required: true - name: is_final type: boolean description: >- Whether this is the last text segment (optional, default: false) required: false - name: customer_request_id type: string description: >- Client-defined pass-through request ID (optional). Only honored on the first text message that opens a new session; ignored on subsequent chunks of the same session. Independent of the server-generated request_id. When provided, it is echoed back on every audio message of that session (customer_request_id field) for correlation. required: false headers: [] jsonPayloadSchema: type: object description: TTS WebSocket text data message (sent by client) properties: type: type: string enum: - text description: Message type x-parser-schema-id: text: type: string description: Text content (required) example: Hello, this is a test. x-parser-schema-id: is_final: type: boolean description: 'Whether this is the last text segment (optional, default: false)' default: false x-parser-schema-id: customer_request_id: type: string maxLength: 128 description: >- Client-defined pass-through request ID (optional). Only honored on the first text message that opens a new session; ignored on subsequent chunks of the same session. Independent of the server-generated request_id. When provided, it is echoed back on every audio message of that session (customer_request_id field) for correlation. example: cust-abc-001 x-parser-schema-id: required: - type - text x-parser-schema-id: title: TTS Text Message example: |- { "type": "", "text": "", "is_final": true, "customer_request_id": "" } bindings: [] extensions: - id: x-parser-unique-object-id value: TTSTextMessage - id: x-parser-message-name value: TTSTextMessage - &ref_5 id: TTSCommandMessage payload: - name: TTS Command Message type: object properties: - name: type type: string description: Message type enumValues: - command required: true - name: command type: string description: >- Command type: 'cancel' tells the server to cancel the current in-progress synthesis. enumValues: - cancel required: true headers: [] jsonPayloadSchema: type: object description: TTS WebSocket command message properties: type: type: string enum: - command description: Message type x-parser-schema-id: command: type: string enum: - cancel description: >- Command type: 'cancel' tells the server to cancel the current in-progress synthesis. x-parser-schema-id: required: - type - command x-parser-schema-id: title: TTS Command Message example: |- { "type": "", "command": "" } bindings: [] extensions: - id: x-parser-unique-object-id value: TTSCommandMessage - id: x-parser-message-name value: TTSCommandMessage bindings: [] extensions: &ref_0 - id: x-parser-unique-object-id value: ttsRealtime - &ref_2 id: sendTTSServerMessages title: Send t t s server messages type: send messages: - &ref_6 id: TTSReadyMessage payload: - name: TTS Ready Message type: object properties: - name: type type: string description: Message type enumValues: - ready required: true - name: request_id type: string description: Request ID required: true - name: voice_id type: string description: Voice ID required: true - name: language type: string description: Language code required: false - name: format type: string description: Audio format required: true - name: sample_rate type: integer description: Sample rate required: true - name: bit_rate type: integer description: Bit rate (kbps) required: false - name: speed type: number description: Speech rate multiplier required: false - name: pitch type: integer description: Pitch offset (semitones) required: false - name: volume type: number description: Volume multiplier required: false headers: [] jsonPayloadSchema: type: object description: TTS WebSocket ready message (sent by server) properties: type: type: string enum: - ready description: Message type x-parser-schema-id: request_id: type: string description: Request ID example: req_1234567890 x-parser-schema-id: voice_id: type: string description: Voice ID example: vn-xiaoxiao x-parser-schema-id: language: type: string description: Language code example: en-US x-parser-schema-id: format: type: string description: Audio format example: pcm x-parser-schema-id: sample_rate: type: integer description: Sample rate example: 16000 x-parser-schema-id: bit_rate: type: integer description: Bit rate (kbps) example: 128 x-parser-schema-id: speed: type: number format: float description: Speech rate multiplier example: 1 x-parser-schema-id: pitch: type: integer description: Pitch offset (semitones) example: 0 x-parser-schema-id: volume: type: number format: float description: Volume multiplier example: 1 x-parser-schema-id: required: - type - request_id - voice_id - format - sample_rate x-parser-schema-id: title: TTS Ready Message example: |- { "type": "", "request_id": "", "voice_id": "", "language": "", "format": "", "sample_rate": 123, "bit_rate": 123, "speed": 123, "pitch": 123, "volume": 123 } bindings: [] extensions: - id: x-parser-unique-object-id value: TTSReadyMessage - id: x-parser-message-name value: TTSReadyMessage - &ref_7 id: TTSAudioMessage payload: - name: TTS Audio Message type: object properties: - name: type type: string description: Message type enumValues: - audio required: true - name: request_id type: string description: Request ID (server-generated) required: true - name: customer_request_id type: string description: >- Client-defined pass-through request ID, echoed from the text message that opened this session. Present only when the client supplied it. required: false - name: data type: string description: Base64-encoded audio data required: true - name: is_final type: boolean description: >- Whether this is the last audio data chunk (optional, default: false) required: false headers: [] jsonPayloadSchema: type: object description: TTS WebSocket audio data message (sent by server) properties: type: type: string enum: - audio description: Message type x-parser-schema-id: request_id: type: string description: Request ID (server-generated) example: req_1234567890 x-parser-schema-id: customer_request_id: type: string description: >- Client-defined pass-through request ID, echoed from the text message that opened this session. Present only when the client supplied it. example: cust-abc-001 x-parser-schema-id: data: type: string format: byte description: Base64-encoded audio data x-parser-schema-id: is_final: type: boolean description: >- Whether this is the last audio data chunk (optional, default: false) default: false x-parser-schema-id: required: - type - request_id - data x-parser-schema-id: title: TTS Audio Message example: |- { "type": "", "request_id": "", "customer_request_id": "", "data": "", "is_final": true } bindings: [] extensions: - id: x-parser-unique-object-id value: TTSAudioMessage - id: x-parser-message-name value: TTSAudioMessage - &ref_8 id: TTSErrorMessage payload: - name: TTS Error Message type: object properties: - name: type type: string description: Message type enumValues: - error required: true - name: error type: string description: Error description required: true - name: code type: string description: Error code required: true - name: request_id type: string description: Request ID required: false headers: [] jsonPayloadSchema: type: object description: TTS WebSocket error message (sent by server) properties: type: type: string enum: - error description: Message type x-parser-schema-id: error: type: string description: Error description example: Invalid voice_id x-parser-schema-id: code: type: string description: Error code example: VOICE_NOT_FOUND x-parser-schema-id: request_id: type: string description: Request ID example: req_1234567890 x-parser-schema-id: required: - type - error - code x-parser-schema-id: title: TTS Error Message example: |- { "type": "", "error": "", "code": "", "request_id": "" } bindings: [] extensions: - id: x-parser-unique-object-id value: TTSErrorMessage - id: x-parser-message-name value: TTSErrorMessage bindings: [] extensions: *ref_0 sendOperations: - *ref_1 receiveOperations: - *ref_2 sendMessages: - *ref_3 - *ref_4 - *ref_5 receiveMessages: - *ref_6 - *ref_7 - *ref_8 extensions: - id: x-parser-unique-object-id value: ttsRealtime securitySchemes: - id: apiKeyAuth name: token type: httpApiKey description: API Key passed as query parameter, e.g. ?token=YOUR_API_KEY in: query extensions: [] ````