# AI TTS Microservice
> Multi-provider text-to-speech platform. Generate, stream, and manage audio via REST API or MCP. Unified access to Google Cloud TTS, Gemini TTS (2.5 Flash/Pro/Lite, 3.1 Flash), Amazon Polly, and Kokoro — across 90+ languages.

For complete machine-readable API spec: https://aitts.theproductivepixel.com/api/v1/openapi

## Platform
- [Overview](https://aitts.theproductivepixel.com/docs): API documentation hub — quickstart, reference, MCP, webhooks, examples
- [Voice Gallery](https://aitts.theproductivepixel.com/voices): Browse and filter voices by provider, language, gender, style
- [Pricing](https://aitts.theproductivepixel.com/pricing): Pay-as-you-go, Pro, and Enterprise plans. Use authenticated pricing tools or the user's browser-rendered pricing page for current account-specific prices.
- [Rates Explorer](https://aitts.theproductivepixel.com/pricing/rates): Per-provider, per-voice-class usage rates by plan type

## API
- [Quickstart](https://aitts.theproductivepixel.com/docs/quickstart): Get started in 2 minutes with curl or SDK
- [API Reference](https://aitts.theproductivepixel.com/docs/api): 46 endpoints — TTS generation, job polling, shares, library, storage, usage
- [OpenAPI Spec](https://aitts.theproductivepixel.com/api/v1/openapi): Machine-readable spec (JSON/YAML download)
- [Provider Capabilities](https://aitts.theproductivepixel.com/docs/provider-capabilities): SSML, markup, speed, multi-speaker, prompt, format support by provider and tier
- [Webhooks](https://aitts.theproductivepixel.com/docs/webhooks): Real-time job completion notifications via HTTPS POST
- [Examples](https://aitts.theproductivepixel.com/docs/examples): Code samples in multiple languages

## MCP
- [MCP Integration](https://aitts.theproductivepixel.com/docs/mcp): 57 tools via remote HTTP POST /api/v1/mcp and 56 REST-proxied tools via stdio (npx @theproductivepixel/aittsm). Covers voice search, generation (async + stream), jobs, shares (including revoke and bulk-revoke), access codes, QR, library, storage, usage, cost estimation, account pricing, and personalization.

## Authentication
API keys start with `tts_` — create from dashboard. Pass as `Authorization: Bearer tts_YOUR_KEY`. MCP uses the same key via `AITTSM_API_KEY` env var.

## Providers
- Google Cloud TTS (Premium): Chirp-HD, Chirp3-HD, Neural2, Studio, Wavenet, News, Polyglot — SSML conditional, bitrate config, up to 500,000 bytes
- Google Ultra (Gemini TTS): 2.5 Flash, 2.5 Pro, 2.5 Flash Lite Preview, 3.1 Flash — prompt support, multi-speaker, model selection, up to 4,000 bytes text + 4,000 bytes prompt
- Amazon Polly (Premium/Ultra): Generative, Neural, Long-Form, Standard — SSML, up to 100,000 bytes
- Kokoro (Premium): Speed control, bitrate config, up to 5,000 bytes

## Voice deep-links
The /voices gallery is fully URL-filterable, so a link reproduces a filtered view down to a single pinned voice. Query params:
- provider: provider to browse (mandatory in a deep-link; family slugs like Standard are shared across providers)
- q: free-text fuzzy search across voice id, family, name, language, and provider
- tier: all, premium, or ultra (default all is omitted)
- lang: BCP-47 language, canonical casing (e.g. en-US)
- family: model family slug (e.g. Wavenet, Chirp3-HD, Neural, Long-Form, Gemini)
- model: generic sub-model selector, provider-agnostic (today targets Google Gemini sub-models)
- voice: pin one voice card — accepts THREE forms (resolved in priority order):
  1. Full public voice_id: provider:lang-Family-Name (e.g. google:en-US-Wavenet-A, polly:en-US-Neural-Joanna)
  2. Legacy canonical id: provider:voiceName (e.g. google:en-US-Wavenet-A — same as internal id)
  3. Plain name: just the voice name token (e.g. Kore, Joanna, Adam) — requires provider param; optionally narrowed by family, lang, model

The plain-name form (3) is what GET /api/v1/voices/{voice_id}/sample-url and MCP get_voice_sample_url return in their voices_url field. It is the most stable form (survives provider-internal id renaming). All three forms are backward-compatible and resolve via a priority cascade on the client.

Pin examples:
- Plain-name (preferred): /voices?provider=google&voice=Kore&family=Gemini&lang=en-US&model=gemini-2.5-flash-tts
- Full public id: /voices?provider=google&voice=google:en-US-Wavenet-A
- Legacy canonical: /voices?provider=polly&voice=polly:en-US-Neural-Joanna
- Polly plain-name: /voices?provider=polly&voice=Joanna&family=Neural&lang=en-US
- Kokoro plain-name: /voices?provider=kokoro&voice=Adam&family=Kokoro&lang=en-US

GET /api/v1/voices/{voice_id}/sample-url (and the get_voice_sample_url MCP tool) return a voices_url deep-link to that exact voice alongside sample_url, so an agent can hand the user both the raw audio URL and the /voices gallery view.

## Voice share readback
GET /api/v1/voice-shares/{code} (public, no auth) returns the voice references for a shared voice gallery by its 8-character base62 short code. Response: { success: true, data: { code, voice_refs, voices, created_at, expires_at? } }. The voice_refs array carries { id, language?, ultra_model? } per voice. Use the code from a voice-share URL path to retrieve the collection.