Voicely Public API
WebSocket text-to-speech API
Send text as it arrives and receive speech as audio frames. Build server-side narration and voice pipelines with a connection that stays open for incremental input.
Choose streaming for the way your text arrives
HTTP audio streaming
Send a complete text request and receive its audio while it is generated. A good fit when the script is already available.
HTTP streaming referenceWebSocket text and audio streaming
Send more text messages as your application produces them and receive audio frames on the same connection. Use contexts to organize separate text streams.
Text streams and independent contexts
WebSocket base URL wss://api.tryvoicely.com. Choose a Voicely voice ID in the endpoint path.
Text stream
/v1/text-to-speech/{voice_id}/stream-inputOne text stream per connection: send text as it arrives, receive audio frames, end with an empty text message.
Multiple contexts
/v1/text-to-speech/{voice_id}/multi-stream-inputKeep independent text streams on a shared connection, using context_id to identify each context.
From incremental text to spoken audio
- Open the connection from your backend and authenticate. Send the required first message with text set to a space.
- Send text as it becomes available. Use flush to request buffered text without waiting for more input.
- Decode the base64 audio frames in the selected output format. A final frame marks completion for the stream or context.
- For a text stream, send empty text to finish. For contexts, use close_context; use close_socket to finish the connection.
Audio formats: mp3_44100_128, pcm_16000, pcm_24000, ulaw_8000, mp3_22050_32, pcm_8000. The default is mp3_44100_128. Raw audio formats have no header; your application must decode the chosen format.
Only fatal errors cancel speech; close_context and close_socket always finish what was already sent. Playback interruption belongs to your application; closing a context finishes its buffered speech.
Languages for your audience
Use language_code to lock the language; otherwise the first spoken text determines it. Choose voices and languages from discovery, including the catalog's preview designations.
Server-side access and billing
WebSocket access requires a funded API wallet and a completed paid credit conversion. Free-trial-only accounts do not unlock it.
- Send your key in the xi-api-key header of the upgrade request.
- Server runtimes whose standard WebSocket constructor cannot set headers may instead send the key as xi_api_key in the required first JSON message (see the first-message shapes and the standard WebSocket example below).
- Never put a key in a URL, browser, mobile app, public repository or log.
Usage accumulates across the session. A segment is charged only after its audio was fully generated and every frame of it was sent. If a segment fails, it and every later segment are not charged; segments already charged stay charged, and the session ends with an error. HTTP Idempotency-Key replay does not replay WebSocket sessions.
For billing units, session limits and error handling, use the billing reference and WebSocket reference.
WebSocket API questions
What does the WebSocket text-to-speech API do?
It accepts text as it arrives and returns generated audio frames over the same connection. Use it in a backend that receives incremental text, rather than waiting to submit a complete script.
How is WebSocket streaming different from HTTP audio streaming?
HTTP audio streaming sends a complete text request and receives streamed audio. WebSocket streaming accepts more text messages while the connection stays open. Choose the transport that matches how your application receives text.
Which endpoint should I use?
Use /v1/text-to-speech/{voice_id}/stream-input for a text stream, or /v1/text-to-speech/{voice_id}/multi-stream-input to manage independent contexts identified by context_id.
What is required for WebSocket access?
Use a server-side API key, a completed paid credit conversion and a funded API wallet. Free-trial-only accounts do not unlock WebSocket access. Never expose the key in a browser, mobile app, URL, public code or logs.
How do I choose a language and voice?
Choose a Voicely voice_id and send language_code to lock the language. Without it, the first spoken text determines the language. The API reference lists the language catalog, locale codes and preview designations.
Does closing a context cancel its speech?
No. close_context finishes the buffered text and sends a final frame for that context. Other contexts can continue. Your application manages playback interruption; closing a context is not a hard cancellation of generated speech.
How is streamed usage billed?
Usage accumulates across the session. A segment is charged after its audio is fully generated and all its frames are sent. Failed and later segments are not charged; earlier completed segments stay charged. HTTP Idempotency-Key replay does not replay WebSocket sessions. The API reference explains billing units and limits.