Transform Text-to-Speech - Streaming

The TTS Websocket API endpoint allows you to stream text into the websocket and stream audio output. If you are using TTS with LLMs, this is a helpful endpoint that allows you to stream LLM outputs into our TTS directly.

To learn more about working with real-time streaming data and results, see Get Started with Streaming Text to Speech.

Endpoint

Production WebSocket server for Deepgram's streaming text to speech. TLS encryption will protect your connection and data. We support a minimum of TLS 1.2.

Accepts

Headers

Body Params

Query Params

Messages

Text Message

Optional

You can send a Text Input Message to our endpoint to get an audio stream containing the spoken text.

{
  "type": "Speak",
  "text": "<input text>"
}

Flush

Required

🚧

Very frequent flushes can affect audio output quality.

Flush forces the generation of audio from the internal text buffer. Learn More.

{
    "type": "Flush"
}

Clear

Optional

Clear will clear out Deepgram's internal text buffer. Learn More.

{
    "type": "Clear"
}

Close

Optional

Close will close the websocket connection. Learn More.

{
  "type": "Close"
}

Responses

Refer to API Errors for more information.

Metadata Response

The metadata response includes information such as its request ID. Deepgram will send a metadata message immediately after completing the websocket handshake when you establish a websocket connection.

{
    "type": "Metadata",
    "request_id": "<uuid>",
    "model_name": "<string>",
    "model_version": "<string>",
    "model_uuid": "<uuid>",
}

Keeping Connections Open

📘

Our TTS websocket does not support keepAlive messages. Sending a keepAlive message will cause a closure of the websocket.

Ping Pong Messages

Our websocket supports ping/pong messages to keep our connection open. To do so, send a ping message to our websocket.

Use One WebSocket Per Conversation

If you are building for conversational AI use cases where a human is talking to a TTS agent, a single websocket per conversation is required. After you establish a connection, you will not be able to change the voice or media output settings.

Errors and Warnings

If Deepgram encounters an error during streamng text to speech, we will return a WebSocket Close frame. The body of the Close frame will indicate the reason for closing using one of the specification’s pre-defined status codes followed by a UTF-8-encoded payload that represents the reason for the error.

Current codes and payloads in use include:

Warnings

Warnings will not cause a closure of the websocket connection. A warning message looks like this:

{
  "type": "Warning",
  "warn_code": "<CODE>",
  "warn_msg": "<descriptive message>",
}