Code Examples

Ready-to-use examples in multiple languages

Examples below use a mix of currently supported providers. Check Provider Capabilities and GET /api/v1/voices before choosing a voice or modifier combination.

Python

Basic Generation

import requests
import time

API_KEY = "tts_YOUR_KEY"
BASE_URL = "https://aitts.theproductivepixel.com/api/v1"

def generate_speech(text: str, voice_id: str = "polly:en-GB-Generative-Brian") -> str:
    """Generate speech using a public voice_id."""
    response = requests.post(
        f"{BASE_URL}/tts",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"text": text, "voice_id": voice_id}
    )
    response.raise_for_status()
    job_id = response.json()["data"]["job_id"]
    
    # Poll for completion
    while True:
        status = requests.get(
            f"{BASE_URL}/tts/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"}
        ).json()["data"]
        
        if status["status"] == "completed":
            return status["audio_endpoint"]
        if status["status"] == "failed":
            raise Exception(status.get("error", {}).get("message"))
        time.sleep(1)

audio_endpoint = generate_speech("Hello from Joanna!")

# Download the audio file
download_url = f"{BASE_URL}{audio_endpoint}"
audio = requests.get(download_url,
    headers={"Authorization": f"Bearer {API_KEY}"},
    allow_redirects=True)
audio.raise_for_status()
with open("output.wav", "wb") as f:
    f.write(audio.content)
print("Saved to output.wav")

With Idempotency Key

import uuid

def generate_safe(text: str, idempotency_key: str = None):
    """Safe retries with idempotency key."""
    response = requests.post(
        f"{BASE_URL}/tts",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Idempotency-Key": idempotency_key or str(uuid.uuid4())
        },
        json={"text": text, "voice_id": "kokoro:en-US-Kokoro-Bella"}
    )
    return response.json()["data"]

Node.js / TypeScript

Basic Generation

const API_KEY = "tts_YOUR_KEY";
const BASE_URL = "https://aitts.theproductivepixel.com/api/v1";

async function generateSpeech(
  text: string,
  voice_id = "polly:en-GB-Generative-Brian"
): Promise<string> {
  const res = await fetch(`${BASE_URL}/tts`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ text, voice_id })
  });
  
  const { data: job } = await res.json();
  
  // Poll for completion
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/tts/${job.job_id}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` }
    });
    const { data: status } = await statusRes.json();
    
    if (status.status === "completed") return status.audio_endpoint;
    if (status.status === "failed") throw new Error(status.error?.message);
    
    await new Promise(r => setTimeout(r, 1000));
  }
}

const audioEndpoint = await generateSpeech("Hello from TypeScript!");

// Download the audio file
const audioRes = await fetch(`${BASE_URL}${audioEndpoint}`, {
  headers: { "Authorization": `Bearer ${API_KEY}` },
  redirect: "follow",
});
const buffer = Buffer.from(await audioRes.arrayBuffer());
const fs = await import("fs");
fs.writeFileSync("output.wav", buffer);
console.log("Saved to output.wav");

cURL

Submit Job

curl -X POST https://aitts.theproductivepixel.com/api/v1/tts \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world!", "voice_id": "polly:en-GB-Generative-Brian"}'

Check Status

curl https://aitts.theproductivepixel.com/api/v1/tts/JOB_ID \
  -H "Authorization: Bearer tts_YOUR_KEY"

List Voices

curl "https://aitts.theproductivepixel.com/api/v1/voices?model_type=premium" \
  -H "Authorization: Bearer tts_YOUR_KEY"

Output Formats

Customize audio output with output_format, sample_rate_hertz, and output_bitrate_kbps.

MP3 with custom settings

response = requests.post(
    f"{BASE_URL}/tts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "High quality MP3 audio output.",
        "voice_id": "polly:en-GB-Generative-Brian",
        "output_format": "mp3",
        "sample_rate_hertz": 24000,
        "output_bitrate_kbps": 192
    }
)

OGG Opus (smaller file size)

response = requests.post(
    f"{BASE_URL}/tts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "Compressed OGG Opus audio.",
        "voice_id": "kokoro:en-US-Kokoro-Bella",
        "output_format": "ogg_opus",
        "sample_rate_hertz": 24000,
        "output_bitrate_kbps": 64
    }
)

Note: Default format is wav. Bitrate (output_bitrate_kbps) only applies to mp3 and ogg_opus. See Provider Capabilities for support details.

Multi-Speaker Dialogue

Use two voices from the same provider and language that support multi-speaker mode. See Provider Capabilities and GET /api/v1/voices for supported combinations.

Two Speakers

response = requests.post(
    f"{BASE_URL}/tts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "Instruction: Be cheerful and friendly.\nSpeaker 1: How are you today?\nSpeaker 2: I'm doing great, thanks for asking!",
        "speaker_type": "multi",
        "voice_id_speaker_1": "google:en-US-Gemini-Kore",
        "voice_id_speaker_2": "google:en-US-Gemini-Puck"
    }
)

Example Voices

Public voice_id format: provider:{language}-{Family}-{Name}

polly:en-GB-Generative-Briankokoro:en-US-Kokoro-Bellagoogle:en-US-Chirp3HD-Charongoogle:en-US-Gemini-Kore

Use GET /api/v1/voices for the full list.

Browse the full voice library for all available options.

Streaming

Two-step flow: create a streaming job, then open the stream URL. Short-form only.

cURL

Streaming — cURL

# Step 1: Create streaming job
RESPONSE=$(curl -s -X POST https://aitts.theproductivepixel.com/api/v1/tts/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from streaming", "voice_id": "google:en-US-Chirp3HD-Charon"}')

echo $RESPONSE
# {"success":true,"data":{"job_id":"...","stream_url":"...","transport_format":"ogg_opus",...}}

# Step 2: Stream the audio
STREAM_URL=$(echo $RESPONSE | jq -r '.data.stream_url')
curl -o audio.ogg "$STREAM_URL"

# The completed file is also available at audio_endpoint afterward

Streaming — Explicit Format

# Request a specific format and sample rate
curl -s -X POST https://aitts.theproductivepixel.com/api/v1/tts/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "voice_id": "polly:en-US-Neural-Danielle", "output_format": "mp3", "sample_rate_hertz": 24000}'
# Bitrate is not available in stream mode — omit output_bitrate_kbps

Python

Streaming — Python

import requests

# Step 1: Create streaming job
resp = requests.post("https://aitts.theproductivepixel.com/api/v1/tts/stream",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"text": "Hello from streaming", "voice_id": "polly:en-US-Neural-Danielle"})
data = resp.json()["data"]
print(f"Transport: {data['transport_format']}")

# Step 2: Stream the audio
if "stream_url" in data:
    audio = requests.get(data["stream_url"])
    with open("audio.ogg", "wb") as f:
        f.write(audio.content)
else:
    # Completed result returned immediately (repeat request)
    print(f"Audio ready at: {data['audio_endpoint']}")

Node.js / TypeScript

Streaming — Node.js

const resp = await fetch("https://aitts.theproductivepixel.com/api/v1/tts/stream", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ text: "Hello from streaming", voice_id: "kokoro:en-US-Kokoro-Bella" }),
});
const { data } = await resp.json();
console.log("Transport:", data.transport_format);

if (data.stream_url) {
  const audio = await fetch(data.stream_url);
  // audio.body is a ReadableStream of chunked audio
} else {
  // Completed result returned immediately
  console.log("Audio ready at:", data.audio_endpoint);
}

Repeated requests for the same text and voice may return the completed result immediately. See Provider Capabilities for which voices support streaming.

Create share — cURL

curl -X POST https://aitts.theproductivepixel.com/api/v1/shares \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_ids": ["JOB_ID"], "share_mode": "snapshot", "allow_download": true}'

Create share — Python

resp = requests.post(f"{BASE_URL}/api/v1/shares",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"job_ids": ["JOB_ID"], "share_mode": "snapshot"})
share = resp.json()["data"]
print(f"Share URL: {share['url']}")

List shares — Node.js

const res = await fetch(`${BASE_URL}/api/v1/shares`, {
  headers: { "Authorization": `Bearer ${API_KEY}` }
});
const { data } = await res.json();
console.log(`${data.shares.length} shares`);

Revoke share

curl -X DELETE https://aitts.theproductivepixel.com/api/v1/shares/SHARE_CODE \
  -H "Authorization: Bearer tts_YOUR_KEY"

MCP Tool Calls

Send JSON-RPC messages to POST /api/v1/mcp or use the stdio CLI. See MCP docs for connection setup.

generate_speech (async)

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_speech",
    "arguments": { "text": "Hello!", "voice_id": "google:en-US-Chirp3HD-Charon" }
  }
}

generate_speech (stream + idempotency)

{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "generate_speech",
    "arguments": {
      "text": "Stream this audio.",
      "voice_id": "google:en-US-Chirp3HD-Charon",
      "delivery_mode": "stream",
      "idempotency_key": "unique-key-abc"
    }
  }
}

Stream via Python (MCP HTTP)

import requests

resp = requests.post(f"{BASE_URL}/api/v1/mcp",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/call",
          "params": {"name": "generate_speech", "arguments": {
              "text": "Hello from Python!",
              "voice_id": "google:en-US-Chirp3HD-Charon",
              "delivery_mode": "stream"}}})
result = resp.json()["result"]["content"][0]["text"]
print(result)  # {"job_id": "...", "stream_url": "...", ...}

search_voices

{
  "jsonrpc": "2.0", "id": 3,
  "method": "tools/call",
  "params": { "name": "search_voices", "arguments": { "language": "en-US" } }
}

Tags & Collections

TTS with tags

curl -X POST https://aitts.theproductivepixel.com/api/v1/tts \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Tagged", "voice_id": "kokoro:en-US-Kokoro-Bella", "tags": ["podcast"]}'

Create collection

curl -X POST https://aitts.theproductivepixel.com/api/v1/collections \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project"}'

List tags

curl https://aitts.theproductivepixel.com/api/v1/tags \
  -H "Authorization: Bearer tts_YOUR_KEY"

Storage

Get storage usage

curl https://aitts.theproductivepixel.com/api/v1/storage \
  -H "Authorization: Bearer tts_YOUR_KEY"

List storage items

curl "https://aitts.theproductivepixel.com/api/v1/storage/items?limit=20" \
  -H "Authorization: Bearer tts_YOUR_KEY"

Bulk delete

curl -X POST https://aitts.theproductivepixel.com/api/v1/storage/bulk-delete \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_ids": ["JOB_1", "JOB_2"]}'

Jobs Management

List jobs

curl "https://aitts.theproductivepixel.com/api/v1/jobs?limit=10" \
  -H "Authorization: Bearer tts_YOUR_KEY"

Update metadata (tags + collection)

curl -X PATCH https://aitts.theproductivepixel.com/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["final"], "collection_id": "COLLECTION_ID"}'

Get job text

curl https://aitts.theproductivepixel.com/api/v1/jobs/JOB_ID/text \
  -H "Authorization: Bearer tts_YOUR_KEY"

Pricing Estimate

Estimate cost

curl -X POST https://aitts.theproductivepixel.com/api/v1/pricing/estimate \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice_id": "google:en-US-Chirp3HD-Charon"}'

Python

resp = requests.post(f"{BASE_URL}/api/v1/pricing/estimate",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"text": "Hello world", "voice_id": "polly:en-GB-Generative-Brian"})
est = resp.json()["data"]
print(f"Cost: {est['estimated_cost']} credits ({est['chars_charged']} chars)")

Access Codes & QR

Create access codes

curl -X POST https://aitts.theproductivepixel.com/api/v1/shares/SHARE_CODE/access-codes/bulk \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 5, "label_prefix": "event"}'

Generate QR code (returns data_uri)

curl -X POST https://aitts.theproductivepixel.com/api/v1/shares/SHARE_CODE/qr \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "png"}'

# Response: { "success": true, "data": { "data_uri": "data:image/png;base64,...", "format": "png" } }

Export codes (JSON)

curl "https://aitts.theproductivepixel.com/api/v1/shares/SHARE_CODE/access-codes/export" \
  -H "Authorization: Bearer tts_YOUR_KEY"

# Response: { "success": true, "data": { "access_codes": [...] } }

Bookmarks

Create bookmark (from share code)

curl -X POST https://aitts.theproductivepixel.com/api/v1/bookmarks \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "SHARE_CODE"}'

List bookmarks

curl https://aitts.theproductivepixel.com/api/v1/bookmarks \
  -H "Authorization: Bearer tts_YOUR_KEY"

Rate Limits

Generation limits apply per account. Additional anti-abuse protections may also apply.

Pay-as-you-go	10 requests / 15 min
Pro	100 requests / 15 min
Enterprise	1,000 requests / 15 min

Back to Documentation

Code Examples

Python

Node.js / TypeScript

cURL

Output Formats

Multi-Speaker Dialogue

Example Voices

Streaming

cURL

Python

Node.js / TypeScript

Shares

MCP Tool Calls

Tags & Collections

Storage

Jobs Management

Pricing Estimate

Access Codes & QR

Bookmarks

Rate Limits