🐍 Python Developer Guide

Python Text to Speech API Quickstart

Learn how to make HTTP requests to our Python text-to-speech API endpoints using Aura and Rapid models. Convert any text into high-fidelity AI audio in synchronous scripts or asynchronous microservices.

1. Prerequisites & API Key Setup

All API requests require your X-API-Key header. We recommend storing your credential in an environment variable (YOURVOIC_API_KEY):

2. Synchronous Speech Generation (`requests`)

The following Python code uses the requests library to send a POST payload to the REST endpoint and writes the binary MP3 stream directly to disk.

sync_tts.py
# Step 1: Install required packages
# pip install requests

import os
import requests

# 🔒 Security Best Practice: Retrieve API Key safely from environment variables
API_KEY = os.getenv("YOURVOIC_API_KEY", "YOUR_API_KEY")
URL = "https://yourvoic.com/api/v1/tts/generate"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

payload = {
    "text": "Hello! This is a test request using the Python Text to Speech API.",
    "model": "aura-lite",  # Models: aura-lite, aura-prime, aura-max, rapid-flash, rapid-max
    "voice": "Peter",      # Aura voices: Peter, Kylie, Rahul, Deepika
    "language": "en-US",
    "format": "mp3"
}

try:
    response = requests.post(URL, json=payload, headers=headers)
    response.raise_for_status()

    # Save binary audio stream to MP3 file
    with open("speech.mp3", "wb") as f:
        f.write(response.content)
    
    print("Successfully saved speech.mp3!")

except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err} - {response.text}")
except Exception as e:
    print(f"Error: {e}")

3. Asynchronous Speech Synthesis (`aiohttp`)

For high-concurrency Python applications (such as FastAPI, Sanic, or Discord bots), use aiohttp to avoid blocking the main event loop.

async_tts.py
# Step 1: Install async dependencies
# pip install aiohttp

import os
import aiohttp
import asyncio

# 🔒 Retrieve API key securely from server environment
API_KEY = os.getenv("YOURVOIC_API_KEY", "YOUR_API_KEY")
URL = "https://yourvoic.com/api/v1/tts/generate"

async def synthesize_speech_async():
    headers = {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    }
    
    payload = {
        "text": "Stream high-performance AI speech asynchronously in Python.",
        "model": "aura-lite",
        "voice": "Peter",
        "language": "en-US",
        "format": "mp3"
    }

    async with aiohttp.ClientSession() as session:
        async with session.post(URL, json=payload, headers=headers) as resp:
            if resp.status == 200:
                content = await resp.read()
                with open("async_speech.mp3", "wb") as f:
                    f.write(content)
                print("Saved async_speech.mp3!")
            else:
                error_text = await resp.text()
                print(f"API Error {resp.status}: {error_text}")

# Run async loop
asyncio.run(synthesize_speech_async())

4. Python API Parameters Reference

ParameterTypeDescription
textstringThe input text to convert into speech.
modelstringModel: rapid-flash, aura-lite, rapid-max, aura-prime, aura-max.
voicestringTarget voice name (e.g. Peter, Kylie, Rahul, Deepika).
languagestringLanguage code (e.g. en-US, hi-IN, es-ES).
formatstringAudio format: mp3 or wav.

Explore Other Integrations & Documentation

Compare Python with JavaScript or read full REST API technical specs.