# Speech Generation API

> **Beta Access Required**: The Speech API requires whitelisted access.
>
> To request access, email **sales@demeterics.com** with:
> - Subject: "Feature Access Request"
> - Feature name: **"Text-to-Speech (TTS)"**
>
> For multi-speaker podcast generation, also request: **"TTS Multi-Speaker"**

The Demeterics Speech API provides a unified Text-to-Speech (TTS) interface across multiple providers. Convert text to natural-sounding audio with a single API while automatically tracking usage, costs, and storing generated audio for analysis.

## Overview

**Base URL:** `https://api.demeterics.com/tts/v1`

**Features:**
- **Unified API**: Single endpoint for OpenAI, ElevenLabs, Google Cloud TTS, Murf.ai, Groq Orpheus, and Google Gemini
- **Multi-Speaker**: Generate podcasts and dialogues either as a single Gemini call (up to 2 speakers, native prosody) or via the dialog meta-providers (`gemini-dialog`, `openai-dialog`, `elevenlabs-dialog`, `murf-dialog`) for unlimited speakers and large dialogues
- **Auto-tracking**: Every request logged to BigQuery with full observability
- **Audio Storage**: Generated audio stored in GCS with 15-minute signed URLs
- **BYOK Support**: Use your own provider API keys with dual-key authentication
- **Cost Control**: Automatic credit billing with 15% managed or 10% BYOK fee

## Authentication

### Managed Keys (Default)

Use only your Demeterics API key:

```bash
curl -X POST https://api.demeterics.com/tts/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

### Bring Your Own Key (BYOK)

Use the dual-key format to provide your own provider API key:

```bash
curl -X POST https://api.demeterics.com/tts/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key;sk-your_openai_key" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

The format is: `[demeterics_api_key];[provider_api_key]`

**BYOK Benefits:**
- 10% service fee instead of 15%
- Use your own rate limits and quotas
- Provider costs billed directly to your account

## Endpoints

### Generate Speech

`POST /tts/v1/generate`

Convert text to speech audio.

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `provider` | string | Yes | Target provider: `openai`, `elevenlabs`, `google`, `murf`, `groq`, `gemini`, `openai-dialog`, `elevenlabs-dialog`, `murf-dialog`, `gemini-dialog` |
| `model` | string | No | TTS model (provider-specific) |
| `voice` | string | No | Voice identifier (single speaker) |
| `input` | string | Yes | Text to convert (max varies by provider) |
| `format` | string | No | Output format: `mp3`, `wav`, `opus`, `flac` |
| `speed` | float | No | Playback speed: 0.25-4.0 (default: 1.0) |
| `language` | string | No | Language code (ISO 639-1) |
| `instructions` | string | No | Voice style instructions (`openai` gpt-4o-mini-tts; on `gemini-3.8-*` used as `style` when `style` is empty) |
| `style` | string | No | Delivery style for `gemini-3.8-*` models, for example `warm and calm` or `whispering`. Sent to Google as `speech_metadata.style`, so it shapes the voice and is never read aloud. Ignored by other models. |
| `speakers` | array | No | Multi-speaker config — required for `gemini` (max 2 speakers) and the `*-dialog` providers (unlimited speakers) |
| `temperature` | float | No | Sampling temperature, 0.0–2.0. Honored by `gemini` / `gemini-dialog` for prosody control; **silently ignored by other providers** (set it freely in a fallback-chain request builder — non-Gemini providers won't reject it). |

**Example Request:**

```bash
curl -X POST https://api.demeterics.com/tts/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "tts-1",
    "voice": "alloy",
    "input": "Hello, welcome to Demeterics!",
    "format": "mp3"
  }'
```

**Response:** by default the body is the raw audio (for example WAV bytes) with the cost in the `X-Cost-USD` response header. Add `?response_format=json` to get the JSON below, which carries an `audio_url` instead.

```json
{
  "id": "01JARV4HZ6XPQMWVCS9N1GKEFD",
  "provider": "openai",
  "model": "tts-1",
  "voice": "alloy",
  "audio_url": "https://storage.googleapis.com/demeterics-data/tts/...",
  "duration_seconds": 2.3,
  "cost_usd": 0.00023,
  "usage": {
    "input_chars": 31
  },
  "metadata": {
    "format": "mp3",
    "sample_rate": 24000,
    "channels": 1,
    "generation_ms": 450
  }
}
```

### List Voices

`GET /tts/v1/voices?provider={provider}`

List available voices for a provider.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider` | string | Yes | Provider: `openai`, `elevenlabs`, `google`, `murf` |

**Example Request:**

```bash
curl -X GET "https://api.demeterics.com/tts/v1/voices?provider=openai" \
  -H "Authorization: Bearer dmt_your_api_key"
```

**Response:**

```json
{
  "voices": [
    {
      "id": "alloy",
      "name": "Alloy",
      "description": "Neutral and balanced",
      "gender": "neutral"
    },
    {
      "id": "echo",
      "name": "Echo",
      "description": "Clear and articulate",
      "gender": "male"
    }
  ]
}
```

## Providers

### OpenAI

**Models:**
- `gpt-4o-mini-tts` - Latest model with better steerability. Dual-priced: $0.60/1M input tokens + $12/1M audio output tokens — effective ~$0.015/min of audio (~$20 per 1M chars). Substantially cheaper than ElevenLabs.
- `tts-1` - Fast and efficient (legacy)
- `tts-1-hd` - Higher quality (legacy)

**Voices:**
- `alloy` - Neutral and balanced
- `ash` - Warm and conversational
- `ballad` - Soft and melodic
- `coral` - Friendly and approachable
- `echo` - Clear and articulate
- `fable` - Expressive and dynamic
- `onyx` - Deep and authoritative
- `nova` - Friendly and warm
- `sage` - Calm and measured
- `shimmer` - Bright and optimistic
- `verse` - Dynamic and engaging

**Supported Formats:** mp3, opus, aac, flac, wav, pcm

**Max Characters:** 4,096

### ElevenLabs

**Models:**
- `eleven_v3` - **Most expressive model** — human-like speech with high emotional range, 70+ languages, supports vocal directions (recommended for high-quality content)
- `eleven_multilingual_v2` - Premium quality, 29 languages, 10K char limit
- `eleven_turbo_v2_5` - High quality + speed (~250-300ms), 32 languages, 40K char limit
- `eleven_turbo_v2` - Fast, English only
- `eleven_flash_v2_5` - Ultra-fast (~75ms), 32 languages, 50% lower cost — great for drafts and real-time
- ~~`eleven_monolingual_v1`~~ - **Deprecated February 28, 2026** — migrate to `eleven_v3`

**Vocal Directions (eleven_v3):**

ElevenLabs v3 supports inline audio tags to direct the performance style:

```
[cheerful] Welcome to our channel!
[whisper] But here's a secret...
[dramatic] Everything is about to change.
[sarcastic] Oh sure, that went exactly as planned.
```

Available directions include: `[cheerful]`, `[whisper]`, `[dramatic]`, `[sarcastic]`, `[excited]`, `[friendly]`, `[warm]`, `[professionally]`, `[authoritatively]`, `[breathy]`, and more.

**Voices:** Over 100 pre-made voices plus custom voice cloning

**Supported Formats:** mp3, pcm, ulaw

**Max Characters:** 5,000 (eleven_v3), 10,000 (multilingual_v2), 40,000 (turbo/flash v2.5)

### Google Cloud TTS

**Models:**
- `standard` - Basic quality
- `neural2` - Neural network based
- `wavenet` - High quality WaveNet
- `journey` - Conversational style
- `studio` - Professional quality

**Voices:** 220+ voices across 40+ languages

**Supported Formats:** mp3, wav, ogg

**Max Characters:** 5,000

### Murf.ai

**Models:**
- `GEN2` - Latest generation, highest quality ($0.03/1000 chars)
- `FALCON` - Fast streaming model ($0.01/1000 chars) **← Recommended for Voice-to-Voice**

**Voices:** 120+ voices across 20+ languages including:
- `en-US-natalie` - Natalie (US English, female) — clear, professional
- `en-US-samantha` - Samantha (US English, female) — warm, conversational
- `en-US-terrell` - Terrell (US English, male) — deep, authoritative
- `en-US-wayne` - Wayne (US English, male) — friendly, casual
- `en-UK-hazel` - Hazel (UK English, female) — British accent
- `en-UK-ruby` - Ruby (UK English, female) — British, professional
- `en-UK-maisie` - Maisie (UK English, female) — British, youthful
- `en-AU-lincoln` - Lincoln (Australian, male) — Australian accent

**Supported Formats:** mp3, wav, flac, ogg, pcm, alaw, ulaw

**Max Characters:** 10,000

**Features:**
- Voice styles (conversational, newscast, etc.)
- Speed and pitch control
- Multi-language support with native locales
- **Streaming support** via `/v1/speech/stream` endpoint

### Murf Falcon Streaming (Widget Integration)

The `FALCON` model supports real-time audio streaming, used internally by the AI Chat Widget's Voice-to-Voice feature.

> **Note:** Murf Falcon streaming is not exposed as a standalone Demeterics API endpoint. It's used automatically when Voice-to-Voice is enabled on your AI Chat Widget. For direct TTS generation, use `POST /tts/v1/generate` with `provider: "murf"` and `model: "FALCON"`.

**How Voice-to-Voice Works:**

When Voice-to-Voice is enabled, the widget uses a two-phase streaming architecture:

1. **Phase 1** — `POST /api/widget/voice`
   - Uploads user audio recording
   - Returns: `transcript`, `response` text, and `stream_token`
   - Text is displayed in the widget immediately

2. **Phase 2** — `GET /api/widget/voice/stream?token=X`
   - Server-Sent Events (SSE) stream audio chunks
   - Web Audio API plays chunks as they arrive
   - ~130ms time-to-first-audio (TTFA)

Additional streaming endpoints (internal use):
- `GET /api/widget/voice/stream/mp3` — MP3 format stream
- `GET /api/widget/voice/stream/raw` — Raw audio stream
- `WS /api/widget/voice/ws` — WebSocket streaming
- `WS /api/widget/voice/live` — Full-duplex WebSocket

**Performance:**
- ~130ms time-to-first-audio
- WAV format at 24kHz mono
- Optimized for low-latency conversational AI

**Cost:** $0.01 per 1,000 characters (billed when stream is consumed)

### Google Gemini TTS

> **Beta Access**: Gemini TTS with multi-speaker support is available to whitelisted users. Contact support to request access.

**Models:**
- `gemini-3.8-flash-tts` - Current model, best quality, `style` control and inline events
- `gemini-3.8-flash-lite-tts` - Current model, lower cost
- `gemini-3.1-flash-tts-preview`, `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts` - **Being shut down by Google, no earlier than 2026-12-18** (see below)

> **Always send `model` explicitly.** If you omit it, the provider default is used. For providers `gemini` and `gemini-dialog` that default is now `gemini-3.8-flash-tts`. Calls that name `gemini-3.1-flash-tts-preview` or the 2.5 preview models fail with the retired-model error (410) from 2026-12-18 (the earliest date Google gives).

#### Retired models

2026-12-18 is the earliest possible shutdown date per Google. Demeterics rejects these models from then (UTC), or earlier if Google retires them sooner. Requests for `gemini-3.1-flash-tts-preview`, `gemini-2.5-flash-preview-tts` or `gemini-2.5-pro-preview-tts` then fail at once with HTTP 410 and error code `model_retired`. The message names the replacement (`gemini-3.8-flash-tts` or `gemini-3.8-flash-lite-tts`). No request goes to Google, nothing is charged, and retrying cannot succeed.

#### Gemini 3.8: style, inline events, WAV output

- **`style`**: set the delivery in `style`, not in the text. Gemini 3.8 reads `input` as a verbatim transcript, so a style sentence typed into `input` is spoken aloud.
- **Inline events**: put these tags in `input` where the sound should happen. They reach Google unchanged: `<short pause>`, `<breath>`, `<laugh>`, `<sigh>`, `<cough>`, `<gasp>`. Use the English tag even when the text is in another language.
- **Output**: a finished WAV file, 24 kHz, 16-bit, mono. Duration is read from the file's `data` chunk.
- **Voices**: `Charon` is verified on 3.8 (accepted by Google on 2026-11-14), and so are the other prebuilt voices.

```bash
curl -X POST https://api.demeterics.com/tts/v1/generate \
  -H "Authorization: Bearer $DEMETERICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gemini","model":"gemini-3.8-flash-tts","voice":"Charon",
       "style":"warm and calm",
       "input":"Welcome back. <short pause> Let us begin."}' \
  --output out.wav
```

#### Multi-speaker on Gemini 3.8

- With two entries in `speakers`, Demeterics splits `input` into turns on the `Name:` line prefixes and sends one part per turn to Google, each tagged with its speaker (`speech_metadata.speaker`). The prefix is not part of the spoken text. Consecutive lines of the same speaker form one turn, and inline tags such as `<short pause>` pass through unchanged. `style` (or `instructions`) applies to every turn.
- Input must start with a configured speaker name. A line that starts with `Word:` where `Word` is not one of the two configured speakers is rejected with HTTP 400 `invalid_speaker_config`, before any call to Google, with no charge.
- **Open Google bug**: forum reports (open since about 2026-11-06, no Google fix) describe voice bleed between speakers in 3.8 multi-speaker output. Workaround: send one single-speaker request per turn (own `voice`, own `style`) and join the WAV files on your side.
- `gemini-dialog` on 3.8: requests with 1 or 2 speakers and input within the 4000-byte cap are routed to native multi-speaker as described above. Larger requests (3+ speakers or more than 4000 bytes) are rejected. Billing follows the 3.8 rules below. On a routed `gemini-dialog` request the 500-character limit on `instructions` is not applied; the full `instructions` text is sent as style on every turn, is included in the credit check before the call, and is billed as style.
- `style` is limited to 500 characters on every provider; `instructions` is limited to 500 characters on `gemini` only (where it maps to `style`). HTTP 400 `validation_error` above that.
- Billing on 3.8: each request is billed the **higher** of (a) the per-character estimate (`input characters x per-character rate`, plus style) and (b) the cost computed from the token usage Google reports for the call (text tokens in, audio tokens out, at Google's rates on that date, plus style). In most calls the estimate is the higher one. The token cost is higher when the audio is long for the text, for example a very short input, slow or pause-heavy delivery, or non-Latin text. The amount is rounded up to a whole character at the per-character rate; the service fee is added as usual. In the JSON response, `usage.input_chars` is the length of `input`, and `usage.billed_chars` is the character count that was billed (text, plus style, raised to the token-usage cost when that is higher), so `billed_chars` is equal to or above `input_chars`. The provider cost is `billed_chars x per-character rate`. `usage.billed_chars` is present only on `gemini-3.8` models; on all other models the billed count is `input_chars`. The credit check before the call reserves the highest amount the call can reach under (a) and (b), so a short input needs a balance of about $0.02 to $0.03, not only the per-character estimate. If Google returns a response that contains no usable audio but reports token usage, the request fails and is billed the higher of (a) and (b).
- Only `gemini-3.8-flash-tts` and `gemini-3.8-flash-lite-tts` are accepted. Any other model name that starts with `gemini-3.8` (for example a versioned alias such as `gemini-3.8-flash-tts-001`) is rejected with HTTP 400 `validation_error`, before any call to Google, with no charge.
- Style is billed at the text-only token rate, not the audio rate, and counted as an upper bound: 1 token for each UTF-8 byte of style, at $1.00 per 1M tokens. That is $1.00 per 1M ASCII style characters; a non-ASCII character is 2 to 4 bytes (for example 3 for Chinese, Japanese and Korean, 4 for most emoji). A 50-character ASCII style costs $0.00005. On 3.8 multi-speaker requests the style is sent with every turn, so it is counted once per turn; the largest case (200 turns, 500 characters of style) is $0.10 for ASCII and up to $0.40 for 4-byte characters.
- A multi-speaker 3.8 request may have at most 200 turns. More is HTTP 400 `invalid_speaker_config`, before any call to Google, with no charge.
- Turn lines: a line whose text before the first colon is all digits (`10:30 tomorrow`) or whose colon is followed by `//` (a URL) is treated as ordinary text, not a speaker prefix. A speaker name with the wrong case (`host:` for `Host`) is rejected with a `did you mean` hint.

#### Price change on 2027-01-01

Google doubles the 3.8 token prices on 2027-01-01. Flash: $1.00 per 1M text tokens in, $18.00 per 1M audio tokens out (now $0.50 and $9.00). Flash-Lite: $1.00 and $12.00 (now $0.50 and $6.00). Demeterics applies the new rates automatically from 2027-01-01 00:00 UTC: the managed per-character price becomes $42.55 per 1M characters for `gemini-3.8-flash-tts` (now $21.85) and $28.75 for `gemini-3.8-flash-lite-tts` (now $14.95), and the token-usage cost uses the new token prices. The switch is keyed to the instant 00:00:00 UTC on 2027-01-01, not to local time, and a request that is in progress at that instant may be billed at the new rate. The table below lists the rates in effect until then.

**Voices (30 prebuilt voices):**
- `Puck` - Upbeat
- `Kore` - Firm
- `Charon` - Informative
- `Zephyr` - Bright
- `Fenrir` - Excitable
- `Leda` - Youthful
- `Aoede` - Breezy
- `Sulafat` - Warm
- `Achird` - Friendly
- And 21 more...

**Supported Formats:** wav

**Max Characters:** 8,000

**Features:**
- **Multi-speaker support**: Up to 2 speakers with different voices
- 30 prebuilt voice options
- Ideal for podcasts, dialogues, and conversational content

#### Multi-Speaker Mode (Podcasts & Dialogues)

Generate conversational audio with up to 2 distinct speakers, each with their own voice. Perfect for:
- **Podcasts** with host and guest
- **Dialogues** between characters
- **Interview-style** content
- **Educational** back-and-forth explanations

**Request Body (Multi-Speaker):**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `provider` | string | Yes | Must be `gemini` |
| `model` | string | No | `gemini-3.8-flash-tts` (send it explicitly; the provider default is retired no earlier than 2026-12-18) |
| `input` | string | Yes | Dialogue with speaker labels |
| `speakers` | array | Yes | Speaker-to-voice mapping (max 2) |
| `format` | string | No | Output format (default: `wav`) |

**Speaker Configuration:**

Each speaker object has:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Speaker label (must match input text) |
| `voice` | string | Yes | Voice ID (e.g., `Puck`, `Kore`) |

**Example: Podcast Generation**

```bash
curl -X POST https://api.demeterics.com/tts/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gemini",
    "model": "gemini-3.8-flash-tts",
    "input": "Host: Welcome to the AI Insights podcast! Today we explore the future of voice AI.\nGuest: Thanks for having me! Voice technology is transforming how we interact with machines.",
    "speakers": [
      {"name": "Host", "voice": "Puck"},
      {"name": "Guest", "voice": "Kore"}
    ],
    "format": "wav"
  }'
```

**Response:**

```json
{
  "id": "tts_01JARV4HZ6XPQMWVCS9N1GKEFD",
  "provider": "gemini",
  "model": "gemini-3.8-flash-tts",
  "audio_url": "https://storage.googleapis.com/demeterics-data/tts/...",
  "duration_seconds": 8.5,
  "cost_usd": 0.00125,
  "usage": {
    "input_chars": 156
  }
}
```

**Python Example:**

```python
import requests

response = requests.post(
    "https://api.demeterics.com/tts/v1/generate",
    headers={"Authorization": "Bearer dmt_your_api_key"},
    json={
        "provider": "gemini",
        "input": """Host: What's the biggest challenge in AI today?
Guest: I'd say it's making AI accessible to everyone, not just tech companies.""",
        "speakers": [
            {"name": "Host", "voice": "Puck"},
            {"name": "Guest", "voice": "Kore"}
        ]
    }
)

audio_url = response.json()["audio_url"]
print(f"Podcast audio: {audio_url}")
```

**Best Practices for Multi-Speaker:**

1. **Consistent labels**: Use the same speaker names throughout (e.g., `Host:` not `Announcer:`)
2. **Clear formatting**: Start each line with `Speaker: ` followed by their dialogue
3. **Voice pairing**: Choose voices with distinct characteristics (e.g., upbeat + firm)
4. **Keep turns short**: Shorter dialogue turns sound more natural
5. **Max 2 speakers**: Gemini currently supports up to 2 distinct speakers

---

### Dialog Providers (Gemini / OpenAI / ElevenLabs / Murf)

> **Beta Access**: Dialog providers require the **TTS Multi-Speaker** feature flag — same access as Gemini multi-speaker.

The `gemini-dialog`, `openai-dialog`, `elevenlabs-dialog`, and `murf-dialog` providers accept the **same multi-speaker request shape as Gemini** but synthesize each speaker turn independently through the underlying single-speaker provider, then concatenate the per-turn PCM with 250ms inter-turn silence.

**When to use:**
- Gemini multi-speaker is unavailable (fallback path) — pick `elevenlabs-dialog` or `openai-dialog` (independent infrastructure)
- You need more than 2 speakers (Gemini's hard limit)
- Your dialogue exceeds Gemini's 4000-byte multi-speaker cap — pick `gemini-dialog` to keep Gemini voice quality, or any other dialog provider
- You want OpenAI / ElevenLabs / Murf voices in dialog form

**Tradeoff — read this before adopting:** Each turn is synthesized in isolation. There is no cross-turn prosody conditioning, so a reply does not react to the question's intonation. The output sounds like two voice actors reading separate lines, not a real conversation. For high-fidelity podcast dialogue, prefer native `gemini` multi-speaker; use the dialog providers as a length-relief tier (`gemini-dialog`), a reliability tier (`elevenlabs-dialog`/`openai-dialog`), or when Gemini's caps don't fit.

> **`gemini-dialog` does NOT add reliability.** It calls the same `generativelanguage.googleapis.com` endpoint as native `gemini` multi-speaker. When Google has an outage, both go down together. Use `elevenlabs-dialog` or `openai-dialog` for the outage-fallback role — they have independent infrastructure.

**Available providers:**

| Provider ID | Underlying | Default Model | Cost / 1M chars (managed) |
|---|---|---|---|
| `gemini-dialog` | Google Gemini | `gemini-3.1-flash-tts-preview` | $46.00 |
| `openai-dialog` | OpenAI TTS | `gpt-4o-mini-tts` | $23.00 |
| `elevenlabs-dialog` | ElevenLabs | `eleven_v3` | $345.00 |
| `murf-dialog` | Murf.ai | `FALCON` | $15.30 |

> **`elevenlabs-dialog` default is `eleven_v3`** — highest emotional range and supports inline audio tags (`[cheerful]`, `[whisper]`, `[dramatic]`). For a cheaper rescue tier, override with `model: "eleven_flash_v2_5"` ($69.00 / 1M chars) or use `openai-dialog` instead.

**Request shape:** Identical to Gemini multi-speaker (`speakers` array + `input` with `<Name>:` line prefixes).

| Field | Type | Required | Description |
|---|---|---|---|
| `provider` | string | Yes | `gemini-dialog`, `openai-dialog`, `elevenlabs-dialog`, or `murf-dialog` |
| `model` | string | No | Underlying provider model — see table above for defaults |
| `input` | string | Yes | Dialogue text with speaker labels (`Host: ...\nGuest: ...`) |
| `speakers` | array | Yes | Speaker-to-voice mapping (no upper limit) |
| `format` | string | No | Currently `wav` only — mp3 transcoding requires ffmpeg, which the runtime image does not include |

**Limits:**
- **Total input:** 50,000 chars across all turns
- **Per turn:** Each individual turn must fit the underlying provider's per-call limit — OpenAI 4096 chars, ElevenLabs 5000 chars, Murf 10000 chars
- **Speakers:** No upper limit; speaker names must be alphanumeric only
- **Sample rate:** All turns must produce the same sample rate. Defaults are aligned to 24kHz; Murf `GEN2` emits 44.1kHz and would mismatch — stick with `FALCON` for `murf-dialog`

**Example — three-turn dialog with ElevenLabs:**

```bash
curl -X POST https://api.demeterics.com/tts/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "elevenlabs-dialog",
    "model": "eleven_flash_v2_5",
    "input": "Host: Welcome to the show.\nGuest: Thanks for having me.\nHost: Lets dive in.",
    "speakers": [
      {"name": "Host",  "voice": "JBFqnCBsd6RMkjVDRZzb"},
      {"name": "Guest", "voice": "EXAVITQu4vr4xnSDxMaL"}
    ]
  }'
```

**How it works:**

1. Input is split into ordered turns by matching line-leading speaker tags against the configured `speakers` array. Mid-text colons (`I said: "hi"`) are not mistaken for tags because the candidate must be in the speaker whitelist.
2. Each turn is sent to the underlying single-speaker adapter independently with the speaker's mapped voice.
3. Per-turn audio is decoded to raw PCM (WAV header stripped if present), 250ms of silence is inserted between turns, and the result is wrapped as a single 16-bit mono WAV.
4. The response `audio_url`, `duration_seconds`, and `cost_usd` reflect the joined audio. Per-turn cost is summed.

**Failure mode:** If any single turn fails (after the underlying provider's own retries), the whole request fails with a `provider_error`. There is no per-turn retry-with-different-provider logic in v1.

**Voices:** Use the same voice IDs documented above for OpenAI / ElevenLabs / Murf. Each `speaker.voice` is interpreted by the underlying provider, so e.g. `elevenlabs-dialog` accepts ElevenLabs voice IDs (or names like `Rachel`) and `openai-dialog` accepts OpenAI voice names (`alloy`, `echo`, etc.).

---

### Groq Orpheus (Canopy Labs)

> **Migration Notice:** PlayAI TTS models (`playai-tts`, `playai-tts-arabic`) are deprecated and will be decommissioned on December 31, 2025. Please migrate to `canopylabs/orpheus-v1-english`.

**Models:**
- `canopylabs/orpheus-v1-english` - Expressive English TTS with vocal direction support

**Voices (8 voices):**
- `tara` - Female, conversational (default)
- `leah` - Female, professional
- `jess` - Female, friendly
- `leo` - Male, conversational
- `dan` - Male, professional
- `mia` - Female, warm
- `zac` - Male, casual
- `zoe` - Female, clear

**Supported Formats:** wav only

**Max Characters:** 200 per request

**Features:**
- **Vocal Directions:** Control speech style with bracketed commands:
  - Conversational: `[cheerful]`, `[friendly]`, `[casual]`, `[warm]`
  - Professional: `[professionally]`, `[authoritatively]`, `[formally]`
  - Expressive: `[whisper]`, `[excited]`, `[dramatic]`, `[deadpan]`, `[sarcastic]`
  - Vocal qualities: `[gravelly whisper]`, `[rapid babbling]`, `[singsong]`, `[breathy]`
- Fast generation via Groq infrastructure
- More directions = more expressive; fewer/no directions = natural, casual
- 56% cheaper than PlayAI ($22/1M chars vs $50/1M chars)

## Pricing

### Managed Keys

Character-based pricing with 15% service fee:

| Provider | Model | Cost per 1M chars |
|----------|-------|-------------------|
| OpenAI | gpt-4o-mini-tts | $23.00 |
| OpenAI | tts-1 | $17.25 |
| OpenAI | tts-1-hd | $34.50 |
| ElevenLabs | eleven_v3 | $345.00 |
| ElevenLabs | eleven_multilingual_v2 | $138.00 |
| ElevenLabs | eleven_turbo_v2_5 | $69.00 |
| ElevenLabs | eleven_flash_v2_5 | $69.00 |
| Google | wavenet | $18.40 |
| Google | neural2 | $18.40 |
| Google | standard | $4.60 |
| Murf | GEN2 | $34.50 |
| Murf | FALCON | $15.30 |
| Groq | canopylabs/orpheus-v1-english | $22.00 |
| Gemini | gemini-2.5-flash-preview-tts | $23.00 |
| Gemini | gemini-2.5-pro-preview-tts | $57.50 |
| Gemini | gemini-3.1-flash-tts-preview (shutdown no earlier than 2026-12-18) | $46.00 |
| Gemini | gemini-3.8-flash-tts | $21.85 |
| Gemini | gemini-3.8-flash-lite-tts | $14.95 |
| gemini-dialog | gemini-2.5-flash-preview-tts | $23.00 |
| gemini-dialog | gemini-3.1-flash-tts-preview (shutdown no earlier than 2026-12-18) | $46.00 |
| gemini-dialog | gemini-3.8-flash-tts | $21.85 |
| gemini-dialog | gemini-3.8-flash-lite-tts | $14.95 |
| openai-dialog | gpt-4o-mini-tts | $23.00 |
| elevenlabs-dialog | eleven_flash_v2_5 | $69.00 |
| elevenlabs-dialog | eleven_v3 | $345.00 |
| murf-dialog | FALCON | $15.30 |

> **Dialog provider pricing** equals the underlying provider's rate. Cost is the sum of per-turn calls plus the standard 15% managed (or 10% BYOK) service fee.

### BYOK

10% service fee on top of provider costs. Provider costs billed directly to your account.

## Idempotency and replay

Send `Idempotency-Key: <1 to 255 printable ASCII characters>` on `POST /tts/v1/generate` to make retries safe. Use it whenever your client retries on a timeout, because a response lost after Demeterics generated and billed the audio would otherwise be billed again.

- The first request with a key generates and bills once. A retry with the same key and the **same body** replays the stored audio with `X-Cache: HIT`. The replay is **$0** (`X-Cost-USD: 0.000000`), makes no provider call, and is still logged as a $0 row.
- A fresh generation returns `X-Cache: MISS`.
- Replay window: 24 hours. The audio is stored per user, and a key is scoped to your user and to managed versus BYOK, so one user can never read another user's audio.
- **409 `idempotency_in_progress`**: the first request with this key is still running. Wait the `Retry-After` delay (5 seconds) and retry. The server does not hold the connection open.
- **422 `idempotency_key_reused`**: the key was already used with a different body. Use a new key for a new request.
- **400 `invalid_idempotency_key`**: empty, over 255 characters or not printable ASCII.
- A request that fails before it is billed releases the key, so it can be retried. A request that succeeded and was billed keeps the key, so a lost response replays instead of billing twice.
- A request that **fails after the provider may already have charged for the work** (an upstream timeout after the request was sent, a provider 5xx, or a reply with no usable audio) is billed as a failure (the error type ends in `_billed` in the usage log) and also **releases the key**. A retry with the same key is then a new generation and is **billed again**.
- If your client disconnects while a request with a key is running, the generation still completes and is billed once. Retry with the same key: you get 409 while it runs, then the replay at $0.
- If the stored audio for a key is no longer available, the retry generates and bills again instead of failing.

```bash
curl -X POST https://api.demeterics.com/tts/v1/generate \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Idempotency-Key: chapter-3-turn-17-v1" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gemini","model":"gemini-3.8-flash-tts","voice":"Charon","input":"Hello."}' \
  --output out.wav -D headers.txt
```

## Error Handling

**Error Response Format:**

```json
{
  "error": {
    "type": "invalid_request",
    "message": "Input text exceeds maximum length",
    "code": "text_too_long"
  }
}
```

**Common Error Codes:**

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `invalid_provider` | 400 | Unknown provider specified |
| `invalid_voice` | 400 | Voice not available for provider |
| `text_too_long` | 400 | Input exceeds provider limit |
| `insufficient_credits` | 402 | Not enough credits |
| `provider_error` | 502 | Provider API failed |
| `rate_limited` | 429 | Too many requests |
| `idempotency_in_progress` | 409 | Same `Idempotency-Key` is still running; retry after `Retry-After` |
| `idempotency_key_reused` | 422 | `Idempotency-Key` was used with a different body |
| `invalid_idempotency_key` | 400 | Key is empty, too long or not printable ASCII |

## Data Tracking

Every speech generation is automatically tracked in BigQuery with:

- Transaction ID (ULID)
- User and API key identifiers
- Provider, model, and voice used
- Input character count and text hash (privacy-safe)
- Audio duration and format
- GCS storage path
- Cost breakdown (provider cost, service fee, total)
- Latency metrics
- Error information (if failed)

Query your speech generations:

```sql
SELECT
  transaction_id,
  provider,
  model,
  tts.voice,
  tts.input_chars,
  tts.duration_sec,
  total_cost
FROM `demeterics.demeterics.interactions`
WHERE interaction_type = 'tts'
  AND user_id = @user_id
  AND timing.question_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
ORDER BY timing.question_time DESC
```

## SDK Support

### Python

```python
import requests

response = requests.post(
    "https://api.demeterics.com/tts/v1/generate",
    headers={"Authorization": "Bearer dmt_your_api_key"},
    json={
        "provider": "openai",
        "voice": "alloy",
        "input": "Hello, world!",
        "format": "mp3"
    }
)

audio_url = response.json()["audio_url"]
```

### Node.js

```javascript
const response = await fetch("https://api.demeterics.com/tts/v1/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer dmt_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    provider: "openai",
    voice: "alloy",
    input: "Hello, world!",
    format: "mp3"
  })
});

const { audio_url } = await response.json();
```

## Best Practices

1. **Choose the right provider**: OpenAI for speed, ElevenLabs `eleven_v3` for highest quality (YouTube, podcasts), ElevenLabs `eleven_flash_v2_5` for real-time, Google for language coverage
2. **Pick the right multi-speaker mode**: Gemini for highest-fidelity dialogue (cross-turn prosody, max 2 speakers, 4000-byte cap); the `*-dialog` providers when you need more speakers, larger dialogues, or a Gemini-outage fallback
3. **Cache audio**: Store frequently-used audio locally to reduce API calls
4. **Use appropriate formats**: MP3 for web, WAV for editing, Opus for streaming
5. **Monitor costs**: Track usage in your Demeterics dashboard
6. **Handle errors gracefully**: Implement retry logic with exponential backoff
