Quickstart

Your first TTS request in 2 minutes

1. Get Your API Key

Sign in to your dashboard
Go to the API tab
Click Create Key
Copy your key (starts with tts_)

Save your key now — you won't see it again.

2. Make Your First Request

curl

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"}'

Python

import requests

response = requests.post(
    "https://aitts.theproductivepixel.com/api/v1/tts",
    headers={"Authorization": "Bearer tts_YOUR_KEY"},
    json={
        "text": "Hello world!",
        "voice_id": "kokoro:en-US-Kokoro-Bella"
    }
)
data = response.json()["data"]
print(f"Job ID: {data['job_id']}")

Node.js

const response = await fetch("https://aitts.theproductivepixel.com/api/v1/tts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tts_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Hello world!",
    voice_id: "polly:en-GB-Generative-Brian"
  })
});
const { data } = await response.json();
console.log(`Job ID: ${data.job_id}`);

3. Poll for Completion

The API returns immediately with a job_id. Poll until status is completed:

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

Response when processing:

{
  "success": true,
  "data": {
    "job_id": "...",
    "status": "processing"
  }
}

Response when ready:

{
  "success": true,
  "data": {
    "job_id": "...",
    "status": "completed",
    "audio_endpoint": "/api/v1/tts/.../audio",
    "chars_charged": 12,
    "audio_url": "https://storage.example.com/audio/...?signature=...",
    "audio_url_expires_at": "2026-01-08T10:00:00.000Z"
  }
}

4. Download Your Audio

# Step 1: call the durable API endpoint with your API key and capture the redirect
headers_file=$(mktemp)
curl -sS -D "$headers_file" -o /dev/null \
  -H "Authorization: Bearer $API_KEY" \
  "https://aitts.theproductivepixel.com/api/v1/tts/$job_id/audio"

# Step 2: extract the signed URL and download without sending the API key to GCS
signed_url=$(awk 'BEGIN{IGNORECASE=1} /^Location:/ {print $2}' "$headers_file" | tr -d '\r')
curl -L -o output.wav "$signed_url"

Done. The audio_endpoint is the durable contract. The legacy audio_url is a temporary signed URL kept for compatibility.

5. Output Format Options

Customize audio output with output_format, sample_rate_hertz, and output_bitrate_kbps:

MP3 with custom bitrate

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",
    "output_format": "mp3",
    "sample_rate_hertz": 24000,
    "output_bitrate_kbps": 128
  }'

Formats: wav (default), mp3, ogg_opus. Bitrate only applies to mp3/ogg_opus. See Provider Capabilities for support details.

6. Complete Python Example

import requests
import time

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

# 1. Submit job
resp = requests.post(
    f"{BASE}/tts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"text": "Hello world!", "voice_id": "kokoro:en-US-Kokoro-Bella"}
)
job_id = resp.json()["data"]["job_id"]
print(f"Job submitted: {job_id}")

# 2. Poll until complete
while True:
    status = requests.get(
        f"{BASE}/tts/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    ).json()["data"]
    
    if status["status"] == "completed":
        print(f"Audio ready: {status['audio_endpoint']}")
        break
    elif status["status"] == "failed":
        raise RuntimeError(f"Failed: {status.get('error')}")
    
    time.sleep(1)  # Poll every second

# 3. Download the audio file
download_url = f"https://aitts.theproductivepixel.com{status['audio_endpoint']}"
audio = requests.get(download_url,
    headers={"Authorization": f"Bearer {API_KEY}"},
    allow_redirects=True)
with open("output.wav", "wb") as f:
    f.write(audio.content)
print("Saved to output.wav")

Streaming Quickstart

For real-time playback, use the streaming endpoint instead. This is a two-step flow — short-form generation only.

Streaming Quickstart

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

# Response includes stream_url, transport_format, and job_id

# Step 2: Open the stream URL for live audio
curl -o audio.ogg "STREAM_URL_FROM_RESPONSE"

# The completed audio is also available at audio_endpoint afterward

Not all voices support streaming. The saved artifact uses the same streamed format. You can optionally specify output_format and sample_rate_hertzfrom the provider's supported stream formats. Bitrate selection is not available in stream mode. See Provider Capabilities for the current support matrix.

MCP Quickstart

Connect AI assistants (Claude Desktop, Cursor, etc.) directly to TTS via the Model Context Protocol:

MCP client config

{
  "mcpServers": {
    "aittsm": {
      "command": "npx",
      "args": ["@theproductivepixel/aittsm"],
      "env": { "AITTSM_API_KEY": "tts_YOUR_KEY" }
    }
  }
}

Once connected, the agent can call generate_speech, search_voices, and 32 other tools. Streaming delivery is supported via delivery_mode: "stream" and safe retries via idempotency_key. See MCP docs for the full tool list.

Shares Quickstart

Create a shareable link from completed jobs:

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_1", "JOB_ID_2"], "share_mode": "snapshot"}'

# Response: { "data": { "code": "abc123", "url": "https://...", "item_count": 2 } }

Shares support access codes, password protection, track ordering, and permanent/expiring modes. See API Reference for full share endpoints.

Permissions

API keys have scoped permissions. Select which scopes to grant when creating a key:

Permission	Grants
tts:generate	Generate speech
tts:status	Check job status, retrieve audio
voices:list	List available voices
usage:read	View credit balance
jobs:read / jobs:write	Browse history, update metadata, delete audio
shares:read / shares:write	Manage shares, access codes, QR
library:read / library:write	Collections, tags, bookmarks
storage:read / storage:write	Storage usage, bulk delete
pricing:estimate	Estimate generation cost

Default key permissions: tts:generate, tts:status, usage:read, voices:list.

Tags & Collections

Organize generated audio by passing tags and collection_id on TTS requests:

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

Tags and collection_id also work on streaming requests (/api/v1/tts/stream) and MCP (generate_speech). Manage collections via /api/v1/collections.

Next steps: API Reference · Provider Capabilities · Webhooks · Examples · MCP

Back to Documentation