# AssemblyAI Documentation: Text to Speech (part 1 of 4) Get an API key: https://www.assemblyai.com/dashboard/signup?utm_source=llms_full_txt&utm_medium=ai_agent&utm_campaign=agent_docs Full Markdown for the Text to Speech section. Index of all sections: https://www.assemblyai.com/docs/llms.txt --- # Quickstart URL: https://www.assemblyai.com/docs/tts/getting-started/quickstart Source: docs/tts/getting-started/quickstart.mdx Navigation: Text to Speech > Getting started Description: Turn a line of text into a WAV file with one SDK call or one HTTP request, then speak a whole reply over a single WebSocket session. The Streaming TTS API turns text into speech and sends the audio back as it is synthesized, so playback can start long before the sentence ends. This page gets you from an empty file to playable audio twice: first as a WAV file from one request, then as a conversation spoken over one WebSocket session, the way a voice agent uses it. ## Before you begin - **An API key.** Copy it from API Keys (`https://www.assemblyai.com/dashboard/signup?utm_source=docs_md&utm_medium=ai_agent&utm_campaign=agent_docs`) and set it once: ```bash export ASSEMBLYAI_API_KEY= ``` - **The SDK.** Skip this if you only want the `curl` command. Text to speech is in the Python SDK from release 1.8.2 and in the JavaScript SDK from 4.42.0. ```bash pip install -U assemblyai ``` ```bash npm install assemblyai ``` ## Generate your first audio One request, one text, the whole audio back as a WAV file. The SDKs call the [HTTP API](/tts/api-reference/http-api/overview), and the cURL tab shows the same request without an SDK. Save the program as `hello.py` or `hello.mjs`; the `.mjs` extension makes it an ES module, which the `import` and the top-level `await` need. ```python import os import assemblyai as aai tts = aai.TextToSpeech(api_key=os.environ["ASSEMBLYAI_API_KEY"]) response = tts.synthesize( "Hi, thanks for calling. How can I help you today?", aai.TTSConfig(voice_id="aai-kyla", container=aai.TTSContainer.wav), ) with open("hello.wav", "wb") as f: f.write(response.audio) print(f"voice {response.voice_id}, model {response.model}, " f"{response.sample_rate} Hz {response.encoding}") print(f"wrote hello.wav: {response.audio_duration_ms} ms of audio, " f"{response.billed_characters} characters billed") ``` ```javascript import { writeFileSync } from "node:fs"; import { AssemblyAI } from "assemblyai"; const client = new AssemblyAI({ apiKey: process.env.ASSEMBLYAI_API_KEY }); const response = await client.tts.synthesize({ text: "Hi, thanks for calling. How can I help you today?", voice_id: "aai-kyla", container: "wav", }); writeFileSync("hello.wav", response.audio); console.log(`voice ${response.voiceId}, model ${response.model}, ${response.sampleRate} Hz ${response.encoding}`); console.log(`wrote hello.wav: ${response.audioDurationMs} ms of audio, ${response.billedCharacters} characters billed`); ``` ```bash curl -sS --fail-with-body -D headers.txt https://tts.us.assemblyai.com/v1/speech \ -H "Authorization: $ASSEMBLYAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "Hi, thanks for calling. How can I help you today?", "voice_id": "aai-kyla", "container": "wav", "stream": false}' \ -o hello.wav ``` `"stream": false` asks for the whole file at once, which is what the SDKs' `synthesize()` sends; leave it out and the audio streams as it is made. The response headers, saved in `headers.txt`, carry what the SDKs print, among others: ```text HTTP/2 200 content-type: audio/wav x-request-id: 83c9fae1-e0b0-433a-b97e-26f372778f2a x-tts-model: assemblyai-tts-1 x-tts-voice-id: aai-kyla x-tts-language: english x-tts-encoding: pcm_s16le x-tts-sample-rate: 24000 x-tts-container: wav x-tts-billed-characters: 49 x-tts-audio-duration-ms: 3200 ``` A refused request, a wrong key for example, exits with a non-zero code and writes the JSON error into `hello.wav` in place of the audio. If the file will not play, read it. Run it with `python hello.py` or `node hello.mjs`, and `hello.wav` plays in any audio player. The SDKs print this: ```text voice aai-kyla, model assemblyai-tts-1, 24000 Hz pcm_s16le wrote hello.wav: 3200 ms of audio, 49 characters billed ``` Four things about this run: - **Only the text is required.** `voice_id` names Kyla here by her library slug. Leave it out and you get the [default voice](/tts/voices#the-default-voice), Kyla in English, at 24 kHz 16-bit PCM. A voice speaks the language it was recorded in unless you set `language` to another one, though results are usually [worse than in the voice's own language](/tts/voices#voice-and-language). [Voices](/tts/voices) explains how to name a voice and set the language, and the same `voice_id` takes a voice you [cloned](/tts/cloned-voices) in the dashboard. - **The response says what it ran with.** The voice, model, language, encoding and sample rate come back as response headers, which the SDKs expose on the result. Read the sample rate from there rather than from your own request when you write a header or set up a player. - **The duration varies between runs.** Synthesis is not deterministic, so the same sentence can come back a few hundred milliseconds longer or shorter. Billing counts characters, not seconds. - **The JavaScript SDK uses two spellings.** `synthesize()` and `stream()` take the API's own field names, `voice_id` and `sample_rate`, while `session()` takes camelCase options, `voiceId` and `sampleRate`. Results are camelCase, and the `Begin` and `Termination` frames keep their wire names. The requests above go to the US endpoint, which processes your text and audio in the US. To keep processing in the EU, point the SDK or the URL at `tts.eu.assemblyai.com` instead. See [Cloud endpoints and data residency](/tts/endpoints-and-data-zones). ## Speak a conversation over one session A voice agent speaks many short texts, one per turn, and needs the first audio of each as fast as possible. The WebSocket API is built for that: one connection stays open for the whole conversation, each sentence is a request on it, and the audio of a request streams back while the request is still being spoken. Opening a connection per sentence pays the handshake every time and quickly hits the per-account limit on new sessions per minute. The programs below open a session, speak a four-sentence reply through it and write the raw audio to a file. Save them as `reply.py` or `reply.mjs`. ```python import os import assemblyai as aai config = aai.TTSConfig(voice_id="aai-kyla", language="english") reply = [ "Hi, thanks for calling.", "You have reached the accounts team.", "There is one open invoice from last month.", "Would you like to pay it today?", ] with aai.TTSSession(config, api_key=os.environ["ASSEMBLYAI_API_KEY"]) as session: print(f"session {session.begin.id}") with open("reply.pcm", "wb") as out: for sentence in reply: n = 0 for chunk in session.speak(sentence): # raw 24 kHz 16-bit mono PCM out.write(chunk) n += len(chunk) print(f"{sentence!r}: {n} bytes") summary = session.termination # None if the summary did not arrive in time if summary: print(f"{summary.audio_duration_seconds} s of audio " f"for {summary.total_input_char_length} characters") ``` ```javascript import { createWriteStream } from "node:fs"; import { AssemblyAI } from "assemblyai"; const client = new AssemblyAI({ apiKey: process.env.ASSEMBLYAI_API_KEY }); const reply = [ "Hi, thanks for calling.", "You have reached the accounts team.", "There is one open invoice from last month.", "Would you like to pay it today?", ]; const session = client.tts.session({ voiceId: "aai-kyla", language: "english" }); const begin = await session.connect(); console.log(`session ${begin.id}`); const out = createWriteStream("reply.pcm"); for (const sentence of reply) { let bytes = 0; for await (const chunk of session.speak(sentence)) { // raw 24 kHz 16-bit mono PCM out.write(chunk); bytes += chunk.byteLength; } console.log(`'${sentence}': ${bytes} bytes`); } out.end(); const summary = await session.close(); // undefined if the summary did not arrive in time if (summary) { console.log(`${summary.audio_duration_seconds} s of audio for ${summary.total_input_char_length} characters`); } ``` Run it with `python reply.py` or `node reply.mjs`, then play the file. It is raw PCM with no header, so tell the player its format: with [SoX](https://sourceforge.net/projects/sox/), with [ffmpeg](https://ffmpeg.org/), or by converting it to a WAV file any player opens. ```bash play -t raw -r 24000 -e signed -b 16 -c 1 reply.pcm # SoX ffplay -f s16le -ar 24000 -ac 1 reply.pcm # ffmpeg sox -t raw -r 24000 -e signed -b 16 -c 1 reply.pcm reply.wav # SoX, to a WAV file ``` The output looks like this, with byte counts that differ a little from run to run: ```text session 285ab483-997d-439d-a207-411b373a4ae1 'Hi, thanks for calling.': 88320 bytes 'You have reached the accounts team.': 99840 bytes 'There is one open invoice from last month.': 134400 bytes 'Would you like to pay it today?': 84480 bytes 8.48 s of audio for 131 characters ``` What the session did for you: - **The server speaks first.** Connecting waits for the `Begin` frame, which echoes the configuration the session actually got, with the session `id` to quote in support requests. A rejected key or parameter, an unknown `voice_id` included, arrives as an `Error` frame in its place: the Python `with` and the JavaScript `connect()` raise it. See [Error handling](/tts/error-handling). - **Each sentence is one request.** `speak()` sends the text in `Generate` frames, concludes the request with a `Flush` and yields the audio frames until the request's `FlushDone`. The iterator ends with the request, which is what lets the loop count bytes per sentence. See [Message frames](/tts/message-frames). - **The audio has no header.** A session streams raw codec bytes, 16-bit PCM here, so the file will not play if you hand it to an `