Text to Speech (Lightning)

Sync & Async Synthesis

View as Markdown

Generate speech via the REST API or Python SDK — synchronously (one request, complete audio) or asynchronously (multiple requests in parallel).

Sample output (sync, voice: magnus):

Requirements

  • An API key from the Smallest AI Console
  • For Python: requests (or smallestai for the SDK)
  • For JavaScript: Node.js 18+ (built-in fetch)
$export SMALLEST_API_KEY="your-api-key-here"

Synchronous Text to Speech

Send text, receive complete audio in the response:

$curl -X POST "https://api.smallest.ai/waves/v1/lightning-v3.1/get_speech" \
>  -H "Authorization: Bearer $SMALLEST_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "text": "Hello, this is a test of synchronous speech synthesis.",
>    "voice_id": "magnus",
>    "sample_rate": 24000,
>    "output_format": "wav"
>  }' --output sync_output.wav

Asynchronous Text to Speech

For concurrent requests (e.g., generating multiple audio files in parallel):

1import os
2import asyncio
3import aiohttp
4
5API_KEY = os.environ["SMALLEST_API_KEY"]
6URL = "https://api.smallest.ai/waves/v1/lightning-v3.1/get_speech"
7
8async def synthesize(session, text, filename):
9    async with session.post(URL, headers={
10        "Authorization": f"Bearer {API_KEY}",
11        "Content-Type": "application/json",
12    }, json={
13        "text": text,
14        "voice_id": "magnus",
15        "sample_rate": 24000,
16        "output_format": "wav",
17    }) as resp:
18        audio = await resp.read()
19        with open(filename, "wb") as f:
20            f.write(audio)
21        print(f"Saved {filename}")
22
23async def main():
24    async with aiohttp.ClientSession() as session:
25        await asyncio.gather(
26            synthesize(session, "First sentence.", "async_1.wav"),
27            synthesize(session, "Second sentence.", "async_2.wav"),
28            synthesize(session, "Third sentence.", "async_3.wav"),
29        )
30
31asyncio.run(main())

Parameters

ParameterTypeDefaultDescription
textstringrequiredText to synthesize (max ~250 chars recommended)
voice_idstringrequiredVoice to use (e.g., magnus, olivia, aarush)
sample_rateint441008000, 16000, 24000, or 44100 Hz
speedfloat1.0Speech rate multiplier (0.5 to 2.0)
languagestringautoLanguage code: en, hi, es, ta, or auto
output_formatstringpcmAudio format: pcm, wav, mp3, or mulaw
pronunciation_dictsarray—List of pronunciation dictionary IDs

You can override any parameter per request:

1# Override speed and sample rate for a single call
2response = requests.post(URL, headers=headers, json={
3    "text": "Fast and high quality.",
4    "voice_id": "magnus",
5    "speed": 1.5,
6    "sample_rate": 44100,
7    "output_format": "mp3",
8})

When to Use Each Mode

  • Synchronous: Real-time voice assistants, chatbot responses, single audio generation
  • Asynchronous: Batch processing, generating multiple audio files, audiobook chapters, concurrent API calls

For real-time streaming where audio starts playing before generation completes, see Streaming TTS.

Full runnable source: quickstart-python.py

Need Help?

Check out the API Reference for the full endpoint specification, or ask on Discord.