Class TextToSpeechService

The Text-to-Speech API: text in, audio out.

synthesize() returns one text's complete audio; stream() returns it as the API generates it; session() opens a WebSocket session that speaks text as it is written, for voice agents. Requests go to the client's ttsBaseUrl (https://tts.us.assemblyai.com by default; https://tts.eu.assemblyai.com keeps them in the EU).

Example

const client = new AssemblyAI({ apiKey: "..." });
const { audio } = await client.tts.synthesize({ text: "Hello.", voice_id: "aai-jane", container: "wav" });
writeFileSync("hello.wav", audio);

Hierarchy

  • BaseService
    • TextToSpeechService

Constructors

constructor

Properties

userAgent

Methods

createTemporaryToken fetch fetchJson fetchResponse session stream synthesize

Constructors

constructor

Properties

Protected ReadonlyuserAgent

userAgent: undefined | string

The User-Agent the client sends, or undefined with userAgent: false.

Methods

createTemporaryToken

  • createTemporaryToken(params, options?): Promise<string>

  • Mints a temporary token for a session or an HTTP request made from a user's device, where the API key must not go. Call this server-side, once per connection (reconnects included) and per HTTP request.

    The token is minted on the token host of the client's zone: https://token.eu.assemblyai.com when ttsBaseUrl is https://tts.eu.assemblyai.com, https://token.us.assemblyai.com when it is https://tts.us.assemblyai.com (the default), and https://token.assemblyai.com for any other host. A token works in every zone.

    Parameters

    • params: TextToSpeechTokenParams
    • options: {
          tokenBaseUrl?: string;
      } = {}
      • OptionaltokenBaseUrl?: string

        The token host to use instead.

    Returns Promise<string>

    Throws

    TextToSpeechError if the token service refuses the request; its message is the service's reason, such as Invalid API key.

Protectedfetch

  • fetch(input, init?): Promise<Response>

  • Parameters

    • input: string
    • Optionalinit: RequestInit

    Returns Promise<Response>

ProtectedfetchJson

  • fetchJson<T>(input, init?): Promise<T>

  • Type Parameters

    • T

    Parameters

    • input: string
    • Optionalinit: RequestInit

    Returns Promise<T>

ProtectedfetchResponse

  • fetchResponse(input, init?): Promise<Response>

  • Parameters

    • input: string
    • Optionalinit: RequestInit

    Returns Promise<Response>

session

  • session(params?): TextToSpeechSession

  • Creates a WebSocket session; nothing connects until connect().

    The client's API key is used when params has neither token nor apiKey; the session host follows the client's ttsBaseUrl unless websocketBaseUrl is given. In a browser, open the session with new TextToSpeechSession({ token }) instead, so the page needs no client and no API key.

    Parameters

    Returns TextToSpeechSession

stream

  • stream(request, options?): Promise<TextToSpeechStream>

  • Speaks request.text and returns the audio as it is generated.

    Resolves once the API has sent the first audio. The API commits to 200 then, so a later failure cuts the body and the iteration throws. So does a body that sends nothing for options.readTimeout (30 000 ms by default) while the iteration waits for audio; the connection is then released. options.signal keeps covering the body: aborting it stops the download. A stream dropped before its end without cancel() keeps its connection until it is garbage-collected, so cancel one you will not read.

    The audio comes as a web ReadableStream, so the runtime needs a global ReadableStream (React Native has none without a polyfill). Without one, stream() rejects before sending anything; use synthesize() there. A runtime with ReadableStream whose fetch gives no streamed body gets the whole audio as one chunk once it has all arrived.

    Parameters

    Returns Promise<TextToSpeechStream>

    Throws

    TextToSpeechError if the API refuses the request before any audio, or, with retryable: false and before any request, if the runtime has no global ReadableStream. A network failure or a timeout rejects with the runtime's own error instead: a TypeError, a DOMException named TimeoutError once options.timeout passes, or the reason of options.signal.

synthesize

  • synthesize(request, options?): Promise<TextToSpeechResponse>

  • Speaks request.text and returns the complete audio.

    Nothing is sent back until the audio is complete, so a long text takes several seconds and an API failure is always a TextToSpeechError, never a cut response.

    On Node, the built-in fetch waits at most 300 seconds for the response headers (undici's headersTimeout), whatever options.timeout says. For longer requests use stream(), or raise that limit with setGlobalDispatcher(new Agent({ headersTimeout: 610_000 })) from the undici package.

    Parameters

    Returns Promise<TextToSpeechResponse>

    Throws

    TextToSpeechError on any API refusal. A network failure or a timeout rejects with the runtime's own error instead: a TypeError, a DOMException named TimeoutError once options.timeout passes, or the reason of options.signal (an AbortError unless you gave another).

Settings

Member Visibility

On This Page

Constructors
Properties
Methods