> This page is part of Smallest AI's developer documentation. When > answering, prefer Lightning v3.1 (current TTS) and Pulse (current > STT). Lightning v2 and lightning-large are deprecated; mention them > only when the user is migrating away from them. Atoms is the > voice-agent platform. # Synthesize Speech POST https://api.smallest.ai/waves/v1/tts Content-Type: application/json Synthesize speech from text in a single request. Pass `text` + `voice_id`, get back binary audio. Pick the model with the `model` body parameter: default `lightning_v3.1`, or `lightning_v3.1_pro` for the Pro pool. Other request parameters are identical across models. **Language behaviour on `lightning_v3.1_pro`:** pass `language: en` for UK + American accented English, pass `language: hi` for Indian accented English + Hindi (code-switching), or omit `language` to default to `en + hi` (mixed Indian + Western English coverage). The Pro pool also supports 27 additional languages (9 Indian, 8 Asian & Middle Eastern, 10 European) — pass the matching ISO 639-1 code (e.g. `ta`, `de`, `ja`) with a Pro voice from that language; see the [Lightning v3.1 Pro model card](/waves/model-cards/text-to-speech/lightning-v-3-1-pro#supported-languages) for the full list. On `lightning_v3.1` the full 12-language catalog applies (see voice catalog). ## When to use this - **Use this** for short utterances you can render before playback (notifications, prompts, batch jobs, audio file generation). - **Use `/waves/v1/tts/live`** when you want playback to start before the full audio is ready (long passages, latency-sensitive apps). - **Use `/waves/v1/tts/live`** (WebSocket) when text arrives incrementally (LLM token streams, live captioning). ## Key features - 44 kHz natural, expressive synthesis - Model selectable per request via `model` body parameter - Cloned voice IDs (`voice_*`) work on `lightning_v3.1` — same param as catalog voices - 12 documented languages on `lightning_v3.1`. On `lightning_v3.1_pro`: `language: en` → UK + American accented English; `language: hi` → Indian accented English + Hindi; omit `language` → defaults to `en + hi`; plus 27 additional languages via dedicated Pro voices (pass the ISO 639-1 code, e.g. `ta`, `de`, `ja`). - Output formats: `pcm`, `mp3`, `wav`, `ulaw`, `alaw` - Sample rates: 8 kHz – 44.1 kHz - Speed: 0.5× – 2× - Per-call pronunciation dictionaries via `pronunciation_dicts` ## Examples **cURL — Lightning v3.1 (default)** ```bash curl -X POST "https://api.smallest.ai/waves/v1/tts" \ -H "Authorization: Bearer $SMALLEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: audio/wav" \ -d '{ "text": "Hello from Waves TTS.", "voice_id": "magnus", "sample_rate": 24000, "output_format": "wav" }' --output speech.wav ``` **cURL — Lightning v3.1 Pro (omit `language` → defaults to `en + hi`)** ```bash curl -X POST "https://api.smallest.ai/waves/v1/tts" \ -H "Authorization: Bearer $SMALLEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: audio/wav" \ -d '{ "text": "Hello from the Lightning v3.1 Pro pool.", "voice_id": "meher", "model": "lightning_v3.1_pro", "sample_rate": 24000, "output_format": "wav" }' --output speech.wav ``` **cURL — Lightning v3.1 Pro with explicit `language: en` (UK + American accented English)** ```bash curl -X POST "https://api.smallest.ai/waves/v1/tts" \ -H "Authorization: Bearer $SMALLEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: audio/wav" \ -d '{ "text": "Good morning, this is a Pro voice speaking.", "voice_id": "meher", "model": "lightning_v3.1_pro", "language": "en", "sample_rate": 24000, "output_format": "wav" }' --output speech.wav ``` **cURL — Lightning v3.1 Pro with explicit `language: hi` (Indian accented English + Hindi)** ```bash curl -X POST "https://api.smallest.ai/waves/v1/tts" \ -H "Authorization: Bearer $SMALLEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: audio/wav" \ -d '{ "text": "Namaste, this is an Indian-accented Pro voice.", "voice_id": "meher", "model": "lightning_v3.1_pro", "language": "hi", "sample_rate": 24000, "output_format": "wav" }' --output speech.wav ``` ## Common gotchas - **Set `Accept: audio/wav`.** Omitting it can return an empty or unplayable response. - **Pair voice IDs with the right model.** Voice catalogs differ between `lightning_v3.1` and `lightning_v3.1_pro`. The API does not reject mismatched pairings, but using a Pro-only `voice_id` with `model=lightning_v3.1` (or omitting `model`) can return wrong or hallucinated audio. Pair Pro voices with `model=lightning_v3.1_pro`; standard catalog voices with `model=lightning_v3.1` (the default). - **Cloned voices** (`voice_*` from `add_voice`) work with `lightning_v3.1` only; voice cloning is not available on `lightning_v3.1_pro`. - **44.1 kHz output** is supported but most playback environments are happy with 24 kHz — drop the sample rate if bandwidth matters. Reference: https://docs.smallest.ai/waves/api-reference/api-reference/text-to-speech/synthesize-speech ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: waves-v4 version: 1.0.0 paths: /waves/v1/tts: post: operationId: synthesize-speech summary: Synthesize speech description: > Synthesize speech from text in a single request. Pass `text` + `voice_id`, get back binary audio. Pick the model with the `model` body parameter: default `lightning_v3.1`, or `lightning_v3.1_pro` for the Pro pool. Other request parameters are identical across models. **Language behaviour on `lightning_v3.1_pro`:** pass `language: en` for UK + American accented English, pass `language: hi` for Indian accented English + Hindi (code-switching), or omit `language` to default to `en + hi` (mixed Indian + Western English coverage). The Pro pool also supports 27 additional languages (9 Indian, 8 Asian & Middle Eastern, 10 European) — pass the matching ISO 639-1 code (e.g. `ta`, `de`, `ja`) with a Pro voice from that language; see the [Lightning v3.1 Pro model card](/waves/model-cards/text-to-speech/lightning-v-3-1-pro#supported-languages) for the full list. On `lightning_v3.1` the full 12-language catalog applies (see voice catalog). ## When to use this - **Use this** for short utterances you can render before playback (notifications, prompts, batch jobs, audio file generation). - **Use `/waves/v1/tts/live`** when you want playback to start before the full audio is ready (long passages, latency-sensitive apps). - **Use `/waves/v1/tts/live`** (WebSocket) when text arrives incrementally (LLM token streams, live captioning). ## Key features - 44 kHz natural, expressive synthesis - Model selectable per request via `model` body parameter - Cloned voice IDs (`voice_*`) work on `lightning_v3.1` — same param as catalog voices - 12 documented languages on `lightning_v3.1`. On `lightning_v3.1_pro`: `language: en` → UK + American accented English; `language: hi` → Indian accented English + Hindi; omit `language` → defaults to `en + hi`; plus 27 additional languages via dedicated Pro voices (pass the ISO 639-1 code, e.g. `ta`, `de`, `ja`). - Output formats: `pcm`, `mp3`, `wav`, `ulaw`, `alaw` - Sample rates: 8 kHz – 44.1 kHz - Speed: 0.5× – 2× - Per-call pronunciation dictionaries via `pronunciation_dicts` ## Examples **cURL — Lightning v3.1 (default)** ```bash curl -X POST "https://api.smallest.ai/waves/v1/tts" \ -H "Authorization: Bearer $SMALLEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: audio/wav" \ -d '{ "text": "Hello from Waves TTS.", "voice_id": "magnus", "sample_rate": 24000, "output_format": "wav" }' --output speech.wav ``` **cURL — Lightning v3.1 Pro (omit `language` → defaults to `en + hi`)** ```bash curl -X POST "https://api.smallest.ai/waves/v1/tts" \ -H "Authorization: Bearer $SMALLEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: audio/wav" \ -d '{ "text": "Hello from the Lightning v3.1 Pro pool.", "voice_id": "meher", "model": "lightning_v3.1_pro", "sample_rate": 24000, "output_format": "wav" }' --output speech.wav ``` **cURL — Lightning v3.1 Pro with explicit `language: en` (UK + American accented English)** ```bash curl -X POST "https://api.smallest.ai/waves/v1/tts" \ -H "Authorization: Bearer $SMALLEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: audio/wav" \ -d '{ "text": "Good morning, this is a Pro voice speaking.", "voice_id": "meher", "model": "lightning_v3.1_pro", "language": "en", "sample_rate": 24000, "output_format": "wav" }' --output speech.wav ``` **cURL — Lightning v3.1 Pro with explicit `language: hi` (Indian accented English + Hindi)** ```bash curl -X POST "https://api.smallest.ai/waves/v1/tts" \ -H "Authorization: Bearer $SMALLEST_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: audio/wav" \ -d '{ "text": "Namaste, this is an Indian-accented Pro voice.", "voice_id": "meher", "model": "lightning_v3.1_pro", "language": "hi", "sample_rate": 24000, "output_format": "wav" }' --output speech.wav ``` ## Common gotchas - **Set `Accept: audio/wav`.** Omitting it can return an empty or unplayable response. - **Pair voice IDs with the right model.** Voice catalogs differ between `lightning_v3.1` and `lightning_v3.1_pro`. The API does not reject mismatched pairings, but using a Pro-only `voice_id` with `model=lightning_v3.1` (or omitting `model`) can return wrong or hallucinated audio. Pair Pro voices with `model=lightning_v3.1_pro`; standard catalog voices with `model=lightning_v3.1` (the default). - **Cloned voices** (`voice_*` from `add_voice`) work with `lightning_v3.1` only; voice cloning is not available on `lightning_v3.1_pro`. - **44.1 kHz output** is supported but most playback environments are happy with 24 kHz — drop the sample rate if bandwidth matters. tags: - textToSpeech parameters: - name: Authorization in: header required: true schema: type: string - name: Accept in: header description: >- Must be `audio/wav` to receive binary audio. Required for proper playback. required: true schema: $ref: '#/components/schemas/WavesV1TtsPostParametersAccept' responses: '200': description: Synthesized speech retrieved successfully. content: application/octet-stream: schema: type: string format: binary '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/TtsError' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/TtsError' '500': description: Server error occurred. content: application/json: schema: $ref: '#/components/schemas/TtsError' requestBody: content: application/json: schema: $ref: '#/components/schemas/TtsRequest' servers: - url: https://api.smallest.ai description: waves components: schemas: WavesV1TtsPostParametersAccept: type: string enum: - audio/wav default: audio/wav title: WavesV1TtsPostParametersAccept TtsRequestModel: type: string enum: - lightning_v3.1 - lightning_v3.1_pro default: lightning_v3.1 description: | TTS model to route the request to. Controls which model pool serves this synthesis. - `lightning_v3.1` (default) — standard Lightning v3.1. - `lightning_v3.1_pro` — Lightning v3.1 Pro pool. Improved audio quality and naturalness, with a curated voice catalog. See the [Lightning v3.1 Pro model card](/waves/model-cards/text-to-speech/lightning-v-3-1-pro) for supported voice IDs. Same concurrency and latency profile across both. Other request parameters behave identically. title: TtsRequestModel TtsRequestSampleRate: type: string enum: - '8000' - '16000' - '24000' - '44100' description: The sample rate for the generated audio. title: TtsRequestSampleRate TtsRequestLanguage: type: string enum: - en - hi - mr - kn - ta - bn - gu - te - ml - pa - or - es - de - fr - it - pt - ru - el - fi - 'no' - pl - ar - zh - id - ja - ko - ms - tr - vi description: > Language code for synthesis. Influences pronunciation, number/date normalization, and phoneme selection. Each voice has its own `tags.language` set in the voice catalog — query `GET /waves/v1/lightning-v3.1/get_voices`. Pass a language the voice was trained on; passing other codes is accepted by the API but produces English-pronounced output. **On `lightning_v3.1`**, the full 12-language catalog applies. **On `lightning_v3.1_pro`**: - Pass `en` → UK + American accented English. - Pass `hi` → Indian accented English + Hindi (code-switching). - Pass the ISO 639-1 code of any other Pro language (e.g. `ta`, `de`, `ja`) with a matching Pro voice — 27 additional languages (9 Indian, 8 Asian & Middle Eastern, 10 European) have dedicated Pro voices. - Omit `language` → defaults to `en + hi` (mixed Indian + Western English coverage). title: TtsRequestLanguage TtsRequestNumberPronunciationLanguage: type: string enum: - en - hi - mr - kn - ta - bn - gu - te - ml - pa - or - es - de - fr - it - pt - ru - el - fi - 'no' - pl - ar - zh - id - ja - ko - ms - tr - vi description: | Optional. Sets the language used to read out numeric content — numbers, currency amounts, times, and the numeric parts of dates and years — independently of the synthesis voice. Ordinary words are not translated. - If you **omit `language`**, this value also becomes the synthesis language: model selection and voice routing follow it. - If you **set `language` explicitly**, `language` always wins for synthesis and `number_pronunciation_language` only changes how numeric content is normalized. It works both ways — read numbers in Hindi under an English voice, or in English under a Hindi voice (tuned for Indian, often mixed-script, use cases). - Omit this field to keep the existing behaviour — normalization follows `language`. Note: only numeric tokens are re-spoken; the words around them stay in the text language. On a cross-language request names may also render in the target script (e.g. "Smith" → "स्मिथ"), which is generally the desired reading for native-language voices. Accepts the same language codes as `language`. title: TtsRequestNumberPronunciationLanguage TtsRequestOutputFormat: type: string enum: - mp3 - pcm - wav - ulaw - alaw default: pcm description: | Format of the returned audio. `pcm` is the lowest-latency option but requires a decoder to play; `mp3` and `wav` are directly playable in browsers and most media players. The server default is `pcm` when the field is omitted — the API playground uses `mp3` so the generated audio is directly playable. title: TtsRequestOutputFormat TtsRequest: type: object properties: text: type: string default: Hello from Waves TTS. description: The text to convert to speech. voice_id: type: string default: magnus description: >- The voice identifier to use for speech generation. See the model card for available voices per model. model: $ref: '#/components/schemas/TtsRequestModel' default: lightning_v3.1 description: | TTS model to route the request to. Controls which model pool serves this synthesis. - `lightning_v3.1` (default) — standard Lightning v3.1. - `lightning_v3.1_pro` — Lightning v3.1 Pro pool. Improved audio quality and naturalness, with a curated voice catalog. See the [Lightning v3.1 Pro model card](/waves/model-cards/text-to-speech/lightning-v-3-1-pro) for supported voice IDs. Same concurrency and latency profile across both. Other request parameters behave identically. sample_rate: $ref: '#/components/schemas/TtsRequestSampleRate' default: 44100 description: The sample rate for the generated audio. speed: type: number format: double default: 1 description: The speed of the generated speech. language: $ref: '#/components/schemas/TtsRequestLanguage' description: > Language code for synthesis. Influences pronunciation, number/date normalization, and phoneme selection. Each voice has its own `tags.language` set in the voice catalog — query `GET /waves/v1/lightning-v3.1/get_voices`. Pass a language the voice was trained on; passing other codes is accepted by the API but produces English-pronounced output. **On `lightning_v3.1`**, the full 12-language catalog applies. **On `lightning_v3.1_pro`**: - Pass `en` → UK + American accented English. - Pass `hi` → Indian accented English + Hindi (code-switching). - Pass the ISO 639-1 code of any other Pro language (e.g. `ta`, `de`, `ja`) with a matching Pro voice — 27 additional languages (9 Indian, 8 Asian & Middle Eastern, 10 European) have dedicated Pro voices. - Omit `language` → defaults to `en + hi` (mixed Indian + Western English coverage). number_pronunciation_language: $ref: '#/components/schemas/TtsRequestNumberPronunciationLanguage' description: | Optional. Sets the language used to read out numeric content — numbers, currency amounts, times, and the numeric parts of dates and years — independently of the synthesis voice. Ordinary words are not translated. - If you **omit `language`**, this value also becomes the synthesis language: model selection and voice routing follow it. - If you **set `language` explicitly**, `language` always wins for synthesis and `number_pronunciation_language` only changes how numeric content is normalized. It works both ways — read numbers in Hindi under an English voice, or in English under a Hindi voice (tuned for Indian, often mixed-script, use cases). - Omit this field to keep the existing behaviour — normalization follows `language`. Note: only numeric tokens are re-spoken; the words around them stay in the text language. On a cross-language request names may also render in the target script (e.g. "Smith" → "स्मिथ"), which is generally the desired reading for native-language voices. Accepts the same language codes as `language`. output_format: $ref: '#/components/schemas/TtsRequestOutputFormat' default: pcm description: | Format of the returned audio. `pcm` is the lowest-latency option but requires a decoder to play; `mp3` and `wav` are directly playable in browsers and most media players. The server default is `pcm` when the field is omitted — the API playground uses `mp3` so the generated audio is directly playable. pronunciation_dicts: type: array items: type: string description: >- The IDs of the pronunciation dictionaries to use for speech generation. Available on both `lightning_v3.1` and `lightning_v3.1_pro`. word_timestamps: type: boolean default: false description: > **WebSocket-only feature.** Accepted on this endpoint but ignored — no per-word timing information is returned in the sync HTTP or SSE response shape. To receive `status: "word_timestamp"` frames with per-word `{ id, word, start, end }` data, use the WebSocket endpoint `wss://api.smallest.ai/waves/v1/tts/live`. See [Word-level timestamps](/waves/documentation/text-to-speech-lightning/word-timestamps). session_id: type: string description: >- Optional client-provided session identifier for correlation. Only alphanumeric characters, hyphens, underscores, and dots are allowed. Max 128 characters. Echoed back in response headers as `X-External-Session-Id`. request_id: type: string description: >- Optional client-provided request identifier for correlation. Only alphanumeric characters, hyphens, underscores, and dots are allowed. Max 128 characters. Echoed back in response headers as `X-External-Request-Id`. required: - text - voice_id title: TtsRequest TtsError: type: object properties: error: type: string description: Error type. message: type: string description: Error message. title: TtsError securitySchemes: BearerAuth: type: apiKey in: header name: Authorization ``` ## Examples **Request** ```json { "text": "Hello from Waves TTS.", "voice_id": "kaitlyn", "model": "lightning_v3.1_pro", "sample_rate": 44100, "speed": 1, "language": "en", "output_format": "mp3" } ``` **SDK Code** ```python Text to Speech_synthesizeSpeech_example import requests url = "https://api.smallest.ai/waves/v1/tts" payload = { "text": "Hello from Waves TTS.", "voice_id": "kaitlyn", "model": "lightning_v3.1_pro", "sample_rate": 44100, "speed": 1, "language": "en", "output_format": "mp3" } headers = { "Accept": "audio/wav", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Text to Speech_synthesizeSpeech_example const url = 'https://api.smallest.ai/waves/v1/tts'; const options = { method: 'POST', headers: { Accept: 'audio/wav', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"text":"Hello from Waves TTS.","voice_id":"kaitlyn","model":"lightning_v3.1_pro","sample_rate":44100,"speed":1,"language":"en","output_format":"mp3"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Text to Speech_synthesizeSpeech_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.smallest.ai/waves/v1/tts" payload := strings.NewReader("{\n \"text\": \"Hello from Waves TTS.\",\n \"voice_id\": \"kaitlyn\",\n \"model\": \"lightning_v3.1_pro\",\n \"sample_rate\": 44100,\n \"speed\": 1,\n \"language\": \"en\",\n \"output_format\": \"mp3\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Accept", "audio/wav") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Text to Speech_synthesizeSpeech_example require 'uri' require 'net/http' url = URI("https://api.smallest.ai/waves/v1/tts") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Accept"] = 'audio/wav' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"text\": \"Hello from Waves TTS.\",\n \"voice_id\": \"kaitlyn\",\n \"model\": \"lightning_v3.1_pro\",\n \"sample_rate\": 44100,\n \"speed\": 1,\n \"language\": \"en\",\n \"output_format\": \"mp3\"\n}" response = http.request(request) puts response.read_body ``` ```java Text to Speech_synthesizeSpeech_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.smallest.ai/waves/v1/tts") .header("Accept", "audio/wav") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"text\": \"Hello from Waves TTS.\",\n \"voice_id\": \"kaitlyn\",\n \"model\": \"lightning_v3.1_pro\",\n \"sample_rate\": 44100,\n \"speed\": 1,\n \"language\": \"en\",\n \"output_format\": \"mp3\"\n}") .asString(); ``` ```php Text to Speech_synthesizeSpeech_example request('POST', 'https://api.smallest.ai/waves/v1/tts', [ 'body' => '{ "text": "Hello from Waves TTS.", "voice_id": "kaitlyn", "model": "lightning_v3.1_pro", "sample_rate": 44100, "speed": 1, "language": "en", "output_format": "mp3" }', 'headers' => [ 'Accept' => 'audio/wav', 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Text to Speech_synthesizeSpeech_example using RestSharp; var client = new RestClient("https://api.smallest.ai/waves/v1/tts"); var request = new RestRequest(Method.POST); request.AddHeader("Accept", "audio/wav"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"text\": \"Hello from Waves TTS.\",\n \"voice_id\": \"kaitlyn\",\n \"model\": \"lightning_v3.1_pro\",\n \"sample_rate\": 44100,\n \"speed\": 1,\n \"language\": \"en\",\n \"output_format\": \"mp3\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Text to Speech_synthesizeSpeech_example import Foundation let headers = [ "Accept": "audio/wav", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "text": "Hello from Waves TTS.", "voice_id": "kaitlyn", "model": "lightning_v3.1_pro", "sample_rate": 44100, "speed": 1, "language": "en", "output_format": "mp3" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.smallest.ai/waves/v1/tts")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```