# DubVoice.ai Public API

Base URL: `https://www.dubvoice.ai/api/v1` (TTS / voices / translate / video / me)
Other endpoints: `https://www.dubvoice.ai/api/<feature>` (image, music, edge-tts, minimax-tts).

All `/api/v1/*` endpoints and most other endpoints accept either of:
- `Authorization: Bearer sk_your_api_key`
- `X-API-Key: sk_your_api_key`

Exception: `/api/video` and `/api/video/grok` accept only `Authorization: Bearer sk_your_api_key`.

Generate / rotate keys at https://www.dubvoice.ai/dashboard/api-docs.

---

## Recent changes

- **Seedance 2.0 and 2.5**: new video models `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.5` and `seedance-2.5-variant` on `POST /api/v1/video`. Text, opening and closing frames, or up to 9 reference images; 480p to 4K; 4 to 30 seconds with sound; priced per second (see the *Video* tab).
- **Meta Muse video**: new video model `meta-muse` on `POST /api/v1/video` — any whole length from 1 to 60 seconds with sound, 1,200 credits per second, six aspect ratios (see the *Video* tab).
- **Meta Muse image**: new image model `meta-muse` on `POST /api/image-generate` — 2,000 credits per image, ten aspect ratios, up to 14 references (see the *Image* tab).
- **Veo reference images are 8 s only**: a Veo 3.1 request with `mode_image: "ingredient"` and a `duration` other than 8 now returns 400 before anything is charged (the value used to be ignored).
- **Grok Imagine frames**: with `first_frame: true`, `ref_images` takes 1 to 3 images: opening, opening + closing, or opening + middle + closing.
- **Reference images are all used**: image requests used to forward at most 4 references on most models; every reference within the model's limit is now sent.
- **Voice cloning sample length**: a clone sample is now 10 to 25 seconds; a longer MP3 or WAV is cut to its first 25 seconds.
- **Omni 1.2**: new video model `omni-1.2` — Omni Flash's modes and limits with any whole length from 3 to 15 s, at 1.5× the Omni Flash price (see the *Video* tab).
- **Google Vids up to 15 s**: `duration` on `google-vids` now takes any whole number from 3 to 15, still 900 credits per second.
- **No watermark on Veo and Omni videos**: Veo 3.1, Omni Flash and Omni 1.2 clips are now requested without the provider watermark, as Google Vids already was. No field to set.
- **Per-model ElevenLabs settings**: with the extended model set, Multilingual v2 now applies `speed`, `style` and `use_speaker_boost` as well as stability and similarity; each model applies only its own settings (see the TTS table).
- **Vbee / Fish Audio maintenance**: while either provider is paused, requests with its voices return `503` `code: "FEATURE_MAINTENANCE"` before anything is charged.
- **ElevenLabs v4 and v4 Turbo**: `model_id: "eleven_v4"` / `"eleven_v4_turbo"` on `POST /api/v1/tts`, honoured while the extended ElevenLabs model set is enabled (see the *ElevenLabs TTS* tab).
- **Voice not found before charging**: a deleted Vbee / Fish Audio voice, or an ElevenLabs voice outside the active list, returns HTTP 400 `code: "VOICE_NOT_FOUND"`; nothing is charged.
- **Dubbing**: `voice_id` on `POST /api/v1/dubbing` is now applied (voice-replacement output, +25% credits).
- **Dialogue**: if a segment fails, the credits for the segments that succeeded are refunded.
- **Nano Banana 2.1**: the model behind `nano-banana-2` is now Nano Banana 2.1. Same id, no code change.
- **Google Pics**: new image model `google-pics` (ten aspect ratios, up to 14 references).
- **Google Vids**: new video model `google-vids` (3-15 s, 720p or 1080p).
- **Grok Imagine video**: 1080p and the `first_frame` field.
- **Nano Banana Pro**: 2K upscale alongside 4K, same price.

## tab:elevenlabs — ElevenLabs TTS

### POST /api/v1/tts
Submit a text-to-speech job. Returns a `task_id` immediately. Poll the job
with `GET /api/v1/tts?task_id=...`. Cost = 1 credit per character.

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | yes | Text to synthesise. Up to 500,000 characters. |
| `voice_id` | string | yes | A 15-25 char alphanumeric ElevenLabs voice id (e.g. `LB3SchLS4lHotJg4GcZW`, "Aaden - Friendly, Warm and Confident"), **or** a prefixed `vbee_...` / `fishaudio_...` id from `GET /voices?provider=vbee|fishaudio` (see the *Vbee & Fish Audio* tab). List with `GET /voices`. Minimax ids are rejected here — use `POST /api/minimax-tts`. |
| `model_id` | string | no | Stored as `eleven_multilingual_v2` when omitted. On the standard backend `model_id` is stored with the job but every request renders with the same standard model. While the extended ElevenLabs model set is enabled, `model_id` is honoured: `eleven_v4` (also used for any unknown id), `eleven_v4_turbo`, `eleven_multilingual_v2`, `eleven_v3`, `eleven_turbo_v2_5`, `eleven_flash_v2_5`, `eleven_turbo_v2`, `eleven_flash_v2`. See *Which model set is active* below. |
| `language` | string | no | `auto` (default — server auto-detects from `text`) or ISO 639-1 code (`en`, `tr`, `es`, `fr`, `de`, `it`, `pt`, `ru`, `pl`, `cs`, `ro`, `uk`, `nl`, `ar`, `hi`, `ja`, `ko`, `zh`, ...). Invalid values are dropped silently and the server falls back to auto-detect. |
| `voice_settings` | object | no | See below. |
| `webhook_url` | string | no | Called once with the final audio URL when the job finishes. |

**voice_settings object**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `speed` | number | 1.0 | Standard backend: 0.5 – 1.5; out-of-range values fall back to the default. Extended model set: applied on Multilingual v2 and the Turbo / Flash models, clamped to 0.7 – 1.2. |
| `context_chaining` | boolean | false | Standard backend: keeps multi-turn voice continuity across the whole script and **bills +50% credits**. While the extended model set is enabled it is not applied and not billed. |
| `with_transcript` | boolean | false | Returns an SRT subtitle file alongside the audio. Works on both backends. |
| `pronunciation_dictionary_id` | string | – | Applies the given dictionary's rules to the text before synthesis. Only affects audio. |
| `stability` | number | 0.5 | Extended model set: applied on every model, 0 – 1. Standard backend: ignored. |
| `similarity_boost` | number | 0.75 | Extended model set: applied on every model except v3, 0 – 1. Standard backend: ignored. |
| `style` | number | 0 | Style exaggeration, 0 – 1. Applied on `eleven_multilingual_v2` with the extended model set; ignored otherwise. |
| `use_speaker_boost` | boolean | true | Speaker boost. Applied on `eleven_multilingual_v2` with the extended model set; ignored otherwise. |

**Settings applied per model (extended model set)** — each model applies only its own; other fields are ignored for it:

| model_id | Applied settings |
|---|---|
| `eleven_v4`, `eleven_v4_turbo` | stability, similarity_boost |
| `eleven_multilingual_v2` | speed, stability, similarity_boost, style, use_speaker_boost |
| `eleven_v3` | stability |
| `eleven_turbo_v2_5`, `eleven_flash_v2_5`, `eleven_turbo_v2`, `eleven_flash_v2` | speed, stability, similarity_boost |

`language` works on both backends. On the standard backend stability / similarity / style / speaker boost have no effect — performance is driven by **inline tags in `text`** (see *Performance tags* below). Sending the fields is harmless.

**Which model set is active**

`GET /api/tts/backend` (no auth) reports it:

```json
{ "elevenlabs": "backup", "models": [{ "id": "eleven_v4", "label": "v4", "settings": ["stability", "similarity_boost"] }, ...], "default_model": "eleven_v4", "speed_range": { "min": 0.7, "max": 1.2 } }
```

`elevenlabs` is `"primary"` or `"backup"`. A non-empty `models` array means the extended ElevenLabs model set is enabled and `model_id` is honoured, with each model's `settings` listing the voice settings it applies; an empty array means the standard backend (`default_model` is then `eleven_multilingual_v2`).

**Performance tags (inline in `text`)**

Drop these tags directly into the text — they steer pacing, pauses, emotion, sound effects, style and tone.

- **Speed:** `[speed_very_slow]` · `[speed_slow]` · `[speed_fast]` · `[speed_very_fast]`
- **Pause:** `[pause]` · `[long_pause]`
- **Emotion (31):** `[affection]`, `[amusement]`, `[anger]`, `[awe]`, `[confusion]`, `[contentment]`, `[curiosity]`, `[disappointment]`, `[doubt]`, `[empathy]`, `[envy]`, `[excitement]`, `[fear]`, `[guilt]`, `[happiness]`, `[hesitation]`, `[hope]`, `[hurt]`, `[interest]`, `[joy]`, `[love]`, `[nostalgia]`, `[pity]`, `[pride]`, `[relief]`, `[sadness]`, `[satisfaction]`, `[shame]`, `[surprise]`, `[sympathy]`, `[wonder]`
- **Sound effects (onomatopoeia is part of the tag — keep it attached):** `[cough]ahem` · `[laughter]haha` · `[crying]boohoo` · `[screaming]ahh` · `[burping]burp` · `[humming]hmm` · `[sigh]uh` · `[sniff]sniff` · `[sneeze]achoo`
- **Style:** `[whispering]` · `[shouting]` · `[singing]` · `[narrating]` · `[storytelling]` · `[announcing]` · `[reporting]` · `[conversational]`
- **Tone:** `[serious]` · `[playful]` · `[formal]` · `[casual]` · `[confident]` · `[warm]` · `[friendly]` · `[calm]` · `[authoritative]` · `[sarcastic]` · `[dramatic]` · `[mysterious]`

Tags go between words or between sentences — never inside a word. The dashboard exposes a one-click tag picker plus an *Enhance text with AI* button that injects them automatically (via `POST /api/tts/enhance`).

**Example**

```bash
curl -X POST "https://www.dubvoice.ai/api/v1/tts" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "[warm] Hello there. [pause] [excitement] Today is going to be amazing!",
    "voice_id": "LB3SchLS4lHotJg4GcZW",
    "model_id": "eleven_multilingual_v2",
    "language": "auto",
    "voice_settings": { "speed": 1.0, "context_chaining": false }
  }'
```

**Response (immediate)**

```json
{ "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "characters": 30 }
```

### GET /api/v1/tts?task_id=&lt;id&gt;
Poll a single job. Returns status, audio URL, progress %, and error if any.

```json
{
  "task_id": "...", "status": "completed",
  "result": "https://your-storage.supabase.co/.../final.mp3",
  "characters": 30, "progress": 100,
  "created_at": "...", "completed_at": "..."
}
```

Statuses: `pending` → `processing` → `completed` | `failed`. Recommended poll
interval: 3-5 seconds.

### GET /api/v1/tts
Paginated list of your jobs: `?page=1&limit=20` (max 100).

### Limits
- Up to 30 jobs in progress per user.
- 240 requests / minute per API key.
- Max text length: 500,000 chars per job.

---

## tab:edge — Edge TTS

Microsoft Edge neural voices. **1 credit per 10 characters** (Math.ceil — e.g. 250 chars = 25 cr).

### POST /api/edge-tts
Returns the MP3 binary directly (no polling). Response headers: `X-Credits-Used`,
`X-Characters`, `X-Job-Id` and, when known, `X-Credits-Remaining`.

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | yes | Text to synthesise. |
| `voice_id` | string | yes | Edge voice id from `GET /api/edge-tts` (e.g. `en-US-AriaNeural`, `tr-TR-EmelNeural`). An unknown id returns 400 with the list of available voices. |
| `rate` | number | no | 0 – 200, default 100 (normal speed). |
| `pitch` | number | no | -50 – 50, default 0 (normal pitch). |
| `volume` | number | no | 0 – 100, default 100. |
| `style` | string | no | Optional speaking style, for voices that list `style` values. |

```bash
curl -X POST "https://www.dubvoice.ai/api/edge-tts" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello world", "voice_id": "en-US-AriaNeural", "rate": 100, "pitch": 0 }' \
  --output out.mp3
```

### GET /api/edge-tts
Returns the full Edge voice catalogue (393 voices, 116 languages) and the pricing:

```json
{
  "voices": [{ "id": "en-US-AriaNeural", "name": "Aria", "language": "English (US)", "locale": "en-US", "gender": "female", "style": ["chat", "cheerful", ...] }, ...],
  "pricing": { "rate": "10 characters = 1 credit", "discount": "90% cheaper than ElevenLabs" }
}
```

`style` is present only on voices that support speaking styles.

---

## tab:vbee-fishaudio — Vbee & Fish Audio TTS

Two extra voice libraries that synthesise through the **same endpoint and
job flow as ElevenLabs** — `POST /api/v1/tts`. There is no separate
synthesis endpoint: list the voices, then pass the returned `voice_id`
straight to `/api/v1/tts`. **1 character = 1 credit**, same as ElevenLabs.

| Provider | Voices | Focus |
|----------|--------|-------|
| `vbee` | **1,649** | Vietnamese-heavy (1,212 of them) but 52 languages in total — Arabic, Hindi, Japanese, French, Indonesian, Filipino … |
| `fishaudio` | **273** | Multilingual community library, 14 languages (96 English, plus Chinese, Spanish, Portuguese, Arabic, Turkish, …) |

### 1. List the voices

```bash
curl "https://www.dubvoice.ai/api/v1/voices?provider=vbee&page_size=50" \
  -H "Authorization: Bearer sk_..."

curl "https://www.dubvoice.ai/api/v1/voices?provider=fishaudio&gender=female" \
  -H "Authorization: Bearer sk_..."
```

Both providers ship as bundled catalogues, so listing needs no upstream
round-trip. Filters `search`, `language`, `gender`, `page`, `page_size`
work the same as for ElevenLabs. Each voice comes back with its id
**already prefixed**:

```json
{
  "voices": [
    {
      "voice_id": "vbee_n_phutho_female_anbinhan_advertise_vc",
      "name": "An Bình An",
      "gender": "female",
      "language": "Vietnamese",
      "preview_url": "https://..."
    }
  ],
  "total": 1649, "page": 1, "page_size": 50, "provider": "vbee"
}
```

> **`language` filter — the two providers label languages differently.**
> `vbee` uses full names (`Vietnamese`, `Arabic`, `Bengali (India)`),
> `fishaudio` uses ISO 639-1 codes (`en`, `zh`, `es`, `tr`). The filter is
> an exact, case-insensitive match, so `?provider=fishaudio&language=english`
> returns nothing — use `language=en`. When in doubt, list without the
> filter and read the `language` field.

### 2. Synthesise

Pass the prefixed id to the normal TTS endpoint — do **not** strip the
`vbee_` / `fishaudio_` prefix, it is what selects the provider upstream.

```bash
# Vbee (Vietnamese)
curl -X POST "https://www.dubvoice.ai/api/v1/tts" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Xin chào, đây là giọng đọc tiếng Việt.",
    "voice_id": "vbee_n_phutho_female_anbinhan_advertise_vc",
    "voice_settings": { "speed": 1.0 }
  }'

# Fish Audio (English)
curl -X POST "https://www.dubvoice.ai/api/v1/tts" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a Fish Audio voice.",
    "voice_id": "fishaudio_7ffbc30676794fd989cda022638314b5"
  }'
```

Returns a `task_id` immediately; poll `GET /api/v1/tts?task_id=...` exactly
as with ElevenLabs. Statuses, webhooks, concurrency caps and the 500,000
character limit are all identical. A voice that has been removed from the
catalogue returns HTTP 400 `code: "VOICE_NOT_FOUND"` before anything is charged.

`model_id` is ignored for these providers — the upstream picks the model
from the voice prefix. You may send it or omit it.

**Notes**

- Inline performance tags (`[warm]`, `[pause]`, …) are an ElevenLabs
  feature and are not interpreted by Vbee / Fish Audio — the text is read
  as written, so leave the tags out.
- `speed` (0.5–1.5) is honoured. The other legacy `voice_settings` fields
  are ignored, same as on the ElevenLabs path.
- An ElevenLabs maintenance window does **not** block these providers.
- Sending a Minimax voice id here returns `MINIMAX_NOT_SUPPORTED_HERE` —
  use `POST /api/minimax-tts` for those.

---

## tab:minimax — Minimax TTS

High-quality multilingual TTS using Minimax models. 1 character = 1 credit.
**481 voices** across 30+ languages.

### POST /api/minimax-tts
Synchronous (~5-30 s). The response body is the binary audio itself
(`Content-Type: audio/mpeg`), not a URL — save it to a file. Response headers:
`X-Credits-Used`, `X-Credits-Remaining`, `X-Characters`, `X-Job-Id`.

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | yes | Up to 500,000 chars per call. |
| `voice_id` | string | yes | Numeric Minimax `voice_id` from `POST /api/minimax-tts/voices` (e.g. `209533299589184` "Calm Woman", `209533299589198` "Captivating Storyteller"). Pass the `voice_id` the list returned, verbatim. Slug ids such as `English_CalmWoman` are still accepted as a legacy alias. An unknown voice returns HTTP 400 `"Selected voice is not available..."` before anything is charged. |
| `speed` | number | no | 0.5–1.5 (default 1.0). |

The upstream picks the model itself; `model`, `language_boost`, `vol`, `pitch` and `emotion` are accepted for backward compatibility but ignored.

```bash
curl -X POST "https://www.dubvoice.ai/api/minimax-tts" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world",
    "voice_id": "209533299589184"
  }' \
  --output out.mp3
```

### POST /api/minimax-tts/voices
List Minimax voices (481 total). Empty body `{}` returns the first 100;
`page_size` goes up to 500. Filter with `tag_list` (`["Turkish"]`,
`["Male", "Mature"]`) and/or a free-text `search` (matches id, name,
language, accent, tags and description).

Each voice in the response has both `voice_id` (numeric, e.g.
`209533299589184`) and `voice_name` (short display label, e.g.
`Calm Woman`). **Always pass the `voice_id` to `/api/minimax-tts`** — the
`voice_name` is for display only; sending it returns HTTP 400
`"Selected voice is not available..."` and nothing is charged.

`sample_audio` carries a playable preview URL for 480 of the 481 voices.
Where it is still an empty string no precomputed preview exists upstream —
synthesise one on demand by sending a few words through `/api/minimax-tts`
with the desired `voice_id`.

```bash
curl -X POST "https://www.dubvoice.ai/api/minimax-tts/voices" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "tag_list": ["Turkish"] }'
```

### POST /api/voice-clone — Clone a voice
Free. Uploads a sample audio file and returns a `cloned_voice_id`.
Cloned voices are used from the dashboard; they are **not available through
the public TTS API yet**. Synthesis with a clone in the dashboard bills the
standard 1 character = 1 credit.

**Multipart body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | file | yes | MP3 or WAV, 10 to 25 seconds of clear speech, max 10 MB. A longer MP3 or WAV is cut to its first 25 seconds; a longer file in another format is refused with HTTP 400. |
| `voice_name` | string | no | Display name (default `"My Voice"`). |
| `language_tag` | string | no | Primary language label (English / Turkish / Spanish / …). Default `English`. |
| `gender_tag` | string | no | `male` / `female` (default `male`). |

```bash
curl -X POST "https://www.dubvoice.ai/api/voice-clone" \
  -H "Authorization: Bearer sk_..." \
  -F "file=@sample.mp3" \
  -F "voice_name=Rachel Clone" \
  -F "language_tag=English" \
  -F "gender_tag=female"
```

→ `{ "success": true, "cloned_voice_id": "<voice_id from the clone response>", "voice_name": "Rachel Clone" }`

The clone then appears in the dashboard voice picker.

### GET /api/voice-clone — List cloned voices
```bash
curl "https://www.dubvoice.ai/api/voice-clone" \
  -H "Authorization: Bearer sk_..."
```

### DELETE /api/voice-clone?voice_id=&lt;id&gt;
```bash
curl -X DELETE "https://www.dubvoice.ai/api/voice-clone?voice_id=<voice_id from the clone response>" \
  -H "Authorization: Bearer sk_..."
```

---


## tab:audio — Audio Tools (STT, Voice Changer, Dubbing, Dialogue, Sound Effects)

These `/api/v1/*` endpoints accept JSON with a public `audio_url` / `source_url`.
(The non-v1 paths — /api/speech-to-text, /api/voice-changer, /api/dubbing —
still accept a direct multipart/form-data file upload.)
Auth: `Authorization: Bearer sk_...` or `X-API-Key`. Credits are charged per use and refunded on failure.

### POST /api/v1/stt — Speech to Text
Transcribe audio to text (returns JSON + SRT transcript URLs). Source ≤200MB. 1,000 credits/minute.
```bash
curl -X POST "https://www.dubvoice.ai/api/v1/stt" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "audio_url": "https://example.com/audio.mp3" }'
```

### POST /api/v1/voice-changer — Voice Changer
Transform the voice in an audio file into a target ElevenLabs voice (`target_voice_id` is a bare ElevenLabs voice id; Minimax, Edge and cloned voices are not accepted). 2,000 credits/minute.
```bash
curl -X POST "https://www.dubvoice.ai/api/v1/voice-changer" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "audio_url": "https://example.com/source.mp3", "target_voice_id": "LB3SchLS4lHotJg4GcZW" }'
```

### POST /api/v1/dubbing — Auto Dubbing
Dub audio into a target language (returns dubbed audio + SRT). Source: MP3 or M4A only, ≤20MB or 5 min. 30,000 credits per task. Optional `voice_id` (a provider-prefixed id from `/api/v1/voices`, e.g. `elevenlabs_...`) is forwarded and applied: it adds a second, voice-replacement output spoken by that voice for 25% more credits.
```bash
curl -X POST "https://www.dubvoice.ai/api/v1/dubbing" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "source_url": "https://example.com/speech.mp3", "target_lang": "tr" }'
```

### POST /api/v1/dialogue — Text to Dialogue
Render a multi-speaker dialogue: each segment is synthesized with its own voice and concatenated.
Provider `minimax` (default) or `edge`. Credits charged per segment; if a segment fails, the credits for the segments that succeeded are refunded too.
```bash
curl -X POST "https://www.dubvoice.ai/api/v1/dialogue" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "provider": "minimax", "segments": [
    { "voice_id": "209533299589184", "text": "Hello, how are you?" },
    { "voice_id": "209533299589198", "text": "I am doing great, thanks!" }
  ] }'
```

### POST /api/sound-effect — Sound Effects
Turn a description into a short sound effect. Synchronous: the response is JSON
`{ "success": true, "audio_url": "https://...mp3", "audio_urls": ["https://...mp3"], "credit_cost": 750, "duration_seconds": 5, "model": "v3" }`
pointing at the finished MP3s. 150 credits per requested second (minimum 300), or 600 credits when
`duration_seconds` is omitted and the model picks the length, for each sound effect.
```bash
curl -X POST "https://www.dubvoice.ai/api/sound-effect" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "Thunder rolling with heavy rain", "duration_seconds": 5, "prompt_influence": 0.3, "loop": false, "model": "v3", "quantity": 2 }'
```
`duration_seconds` 0.5–30 (omit for auto), `prompt_influence` 0–1 (higher sticks closer
to the description), `loop` makes the clip tile seamlessly, `model` is `v3` (default) or
`v2`, `quantity` 1–4 returns that many takes in `audio_urls`. If some takes fail, the rest
are returned, their credits are refunded and `warning` says how many. Text ≤450 characters.

### Pronunciation dictionaries
A dictionary is a saved list of find/replace rules applied to the text just before
synthesis, so a brand name or acronym is spoken the way you want on **every** voice
provider. Pass its id to `/api/v1/tts` as `pronunciation_dictionary_id`; the text you
send is stored and returned unchanged, only the audio differs.
```bash
# Create
curl -X POST "https://www.dubvoice.ai/api/pronunciation-dictionaries" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Brand names", "rules": [
    { "from": "AI", "to": "Ey Ay", "matchType": "word", "caseSensitive": true }
  ] }'

# List / read / update / delete
curl "https://www.dubvoice.ai/api/pronunciation-dictionaries" -H "Authorization: Bearer sk_..."
curl -X PUT "https://www.dubvoice.ai/api/pronunciation-dictionaries/<id>" ...
curl -X DELETE "https://www.dubvoice.ai/api/pronunciation-dictionaries/<id>" ...

# Dry-run a rule set without saving it
curl -X POST "https://www.dubvoice.ai/api/pronunciation-dictionaries/preview" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "AI voices", "rules": [{ "from": "AI", "to": "Ey Ay", "matchType": "word", "caseSensitive": true }] }'
```
`matchType`: `word` (whole words only, Unicode-aware) or `contains` (anywhere).
Max 200 rules per dictionary, 200 characters per side. Rules run in order.

---

## tab:translate — Translate

1 credit per 10 characters of input text (Math.ceil — e.g. 250 chars = 25 cr). Cultural-adapted translation. Credits refunded if every chunk fails.

### POST /api/v1/translate

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | yes | Up to 100,000 chars. |
| `target_language` | string | yes | One of the 36 supported languages, by English name (`English`, `Turkish`, `Spanish`, ...). An unsupported name returns 400 `{ "error": "Unsupported language", "supported_languages": [...] }`. |
| `source_language` | string | no | English name of the input language. Default `English`. There is no auto-detect — name the source language when it is not English. |

```bash
curl -X POST "https://www.dubvoice.ai/api/v1/translate" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "Merhaba, bugün nasılsın?", "target_language": "English", "source_language": "Turkish" }'
```

`source_language` and `target_language` are echoed exactly as you sent them:

```json
{
  "success": true,
  "original_length": 24,
  "translated_length": 25,
  "target_language": "English",
  "source_language": "Turkish",
  "chunks_processed": 1,
  "credits_used": 3,
  "remaining_credits": 249997,
  "translated_text": "Hello, how are you today?"
}
```

**Rate limit:** 10 requests / minute per API key.

### GET /api/v1/translate
Returns the supported languages (36 English names), the text limit and the pricing:

```json
{
  "languages": ["English", "Turkish", "Spanish", ...],
  "max_text_length": 100000,
  "chunk_size": 6000,
  "pricing": "1 credit per 10 characters of input text (rounded up)."
}
```

---

## tab:video — Video Generation

All video endpoints share the same auth (sk_…). Each provider charges credits up-front and refunds on failure.

### POST /api/v1/video — Veo / Meta AI / Meta Muse / Omni Flash / Omni 1.2 / Google Vids / Seedance
Single endpoint that fans out to multiple providers based on `model`. All
durations are inclusive of audio; failures are refunded automatically.

**Veo 3.1 family** (Google, 60-120 s, 8 s fixed clip):

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | yes | English, 10-2000 chars. |
| `model` | string | no | `veo-3.1-fast` (default, **7,500 cr**) / `veo-3.1-lite` (**9,100 cr**) / `veo-3.1` (17,000 cr, HQ). |
| `resolution` | string | no | `720p` (default) / `1080p` (~1.5× cr). |
| `aspect_ratio` | string | no | `16:9` (default) or `9:16` (portrait, for Reels/Shorts). **Every Veo tier accepts both.** |
| `duration` | number | no | Fixed at 8 s for the Veo 3.1 family. Leave it out or send 8. With `mode_image: "ingredient"` any other value is a 400; otherwise it is ignored. |
| `image_base64` | string | no | Legacy single-image alias for `ref_images[0]` (base64 data URI). |
| `ref_images` | string[] | no | Reference images as base64 data URIs (or http(s) URLs). `frame` mode: up to 2 (ordered `[start, end]`). `ingredient` mode: up to **3** on every Veo tier. |
| `mode_image` | string | no | `frame` (default) — first image = start frame, second = end frame. `ingredient` — subject/style references. Supported across all Veo 3.1 variants. |

**Omni Flash** (`model: "omniflash"`, 16:9 / 9:16). Duration-tiered, and a **360p draft size at half the credits**:

| Duration | 360p draft | 720p |
|----------|-----------:|-----:|
| 4 s  | 2,344 | 4,688 |
| 6 s  | 3,125 | 6,250 |
| 8 s (default) | 3,907 | 7,813 |
| 10 s | 4,688 | 9,375 |

360p exists to make iteration cheap: five drafts cost less than one 720p
render. There is no size above 720p on this model.

Fields: `prompt`, `model: "omniflash"`, `aspect_ratio` (`16:9` / `9:16`), `resolution` (`360p` / `720p`, default 720p), `duration` (4 / 6 / 8 / 10), `ref_images` (optional, **up to 7** base64 data URIs or http(s) URLs). Images are always used as references (visual context); `mode_image` is ignored on Omni Flash, so there is no start / end frame mode.

**Omni 1.2** (`model: "omni-1.2"`, 16:9 / 9:16) — the newer Omni Flash: same fields, same **up to 7** references and the same 360p draft at half price, with **any whole length from 3 to 15 seconds**, priced at 1.5× Omni Flash:

| Duration | 360p draft | 720p |
|----------|-----------:|-----:|
| 3 s  | 2,930 | 5,859 |
| 4 s  | 3,516 | 7,032 |
| 6 s  | 4,688 | 9,375 |
| 8 s (default) | 5,860 | 11,720 |
| 10 s | 7,032 | 14,063 |
| 12 s | 8,204 | 16,407 |
| 15 s | 9,961 | 19,922 |

Fields: `prompt`, `model: "omni-1.2"` (`omni_flash_12` is accepted too), `aspect_ratio`, `resolution` (`360p` / `720p`), `duration` (whole number 3-15, default 8), `ref_images` (optional, up to 7). Clips longer than 10 s can take longer to start.

**Google Vids** (`model: "google-vids"`, 16:9 / 9:16) — **900 credits per second**, 1080p at 1.5×:

| Duration | 720p | 1080p |
|----------|-----:|------:|
| 3 s  | 2,700 | 4,050 |
| 5 s (default) | 4,500 | 6,750 |
| 8 s  | 7,200 | 10,800 |
| 10 s | 9,000 | 13,500 |
| 15 s | 13,500 | 20,250 |

Fields: `prompt`, `model: "google-vids"`, `aspect_ratio` (`16:9` / `9:16`), `resolution` (`720p` / `1080p`), `duration` (any whole number 3-15, default 5), `ref_images` (optional, **up to 3** subject/style references), `mode_image: "frame"` with a single image to start the clip from it. No end frame and no `voice`: either is a 400.

**Meta Muse** (`model: "meta-muse"`) — **1,200 credits per second**, any whole length from 1 to 60 seconds, with sound. The longest single clip on the API.

| Duration | Credits |
|----------|--------:|
| 5 s  | 6,000 |
| 8 s (default) | 9,600 |
| 15 s | 18,000 |
| 30 s | 36,000 |
| 60 s | 72,000 |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | yes | 10-2000 chars. |
| `model` | string | yes | `meta-muse` |
| `duration` | number | no | Whole number 1-60, default 8. Anything else is a 400 (it is not rounded, because the price follows the length). |
| `aspect_ratio` | string | no | `16:9` (default) / `9:16` / `1:1` / `4:3` / `3:4` / `21:9`. Another value is a 400. |
| `start_frame` | string | no | One image (base64 data URI or http(s) URL) used as the opening frame. |
| `ref_images` | string[] | no | 1 to 3 images. One image is the opening frame; two or three are references, used in the order given. Not together with `start_frame`. |

There is no `resolution` (the model chooses it; the field is ignored and absent from the response). `voice`, `end_frame`, `reference_video` and a `count` other than 1 are a 400. All validation errors are returned before any credit is taken.

A short clip usually answers `200` with `video_url`. A longer one answers `202` with `status: "processing"` and a `task_id` after about 150 seconds: poll `GET /api/v1/video?task_id=...` until it returns `completed` (with `video_url`) or `failed` (credits refunded). The success body carries `image_mode`: `"start_frame"`, `"references"` or `null`.

```bash
curl -X POST "https://www.dubvoice.ai/api/v1/video" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a paper boat drifting down a rainy street, slow push in, cinematic",
    "model": "meta-muse",
    "aspect_ratio": "9:16",
    "duration": 30
  }'
```

**Seedance 2.0 and 2.5** (`model: "seedance-2.0"`, `"seedance-2.0-fast"`, `"seedance-2.5"` or `"seedance-2.5-variant"`) — priced **per second** by resolution, with or without sound at the same price. One model covers text to video, opening and closing frames, and reference images: send no images, images with `mode_image: "frame"`, or images with `mode_image: "reference"`.

| Model | Length | 480p | 720p | 1080p | 4K |
|-------|--------|-----:|-----:|------:|---:|
| `seedance-2.0` | 4-15 s | 19,000/s | 40,900/s | 101,100/s | 210,000/s |
| `seedance-2.0-fast` | 4-15 s | 16,900/s | 36,400/s | — | — |
| `seedance-2.5` | 4-30 s | 30,200/s | 65,300/s (68,100/s with references) | 160,000/s (167,500/s with references) | — |
| `seedance-2.5-variant` | 4-30 s | 31,500/s | 68,000/s (70,800/s with references) | 166,400/s (174,200/s with references) | — |

A 5-second 720p clip is 204,500 credits on 2.0, 182,000 on 2.0 Fast, 326,500 on 2.5 and 340,000 on 2.5 Variant.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | yes | 10-2000 chars. |
| `model` | string | yes | One of the four ids above. |
| `duration` | number | no | Whole seconds in the model's range, default 5. Anything else is a 400. |
| `resolution` | string | no | `480p` / `720p` (default) / `1080p` / `4k` (2.0 only). Fast stops at 720p. Another value is a 400. |
| `aspect_ratio` | string | no | `16:9` (default) / `9:16` / `1:1` / `4:3` / `3:4` / `21:9` / `adaptive`. |
| `audio` | boolean | no | Generate sound with the clip. Default `true`; it does not change the price. |
| `ref_images` | string[] | no | Base64 data URIs or http(s) URLs. With `mode_image: "frame"` (default): one opening frame, or an opening and a closing frame. With `mode_image: "reference"`: up to 9 images that guide the look (not on `seedance-2.0-fast`). |
| `mode_image` | string | no | `frame` or `reference`. |

Seedance renders take a few minutes, so the response is always `202` with `status: "processing"` and a `task_id`. Poll `GET /api/v1/video?task_id=...` every 10 seconds until it returns `completed` (with `video_url`) or `failed` (credits refunded). All validation happens before any credit is taken.

```bash
curl -X POST "https://www.dubvoice.ai/api/v1/video" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a red fox runs through fresh snow at sunrise, tracking shot",
    "model": "seedance-2.0",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": true
  }'
```

**Meta AI** (`model: "meta"`) — **flat 2,000 credits** per clip, the cheapest video model here.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | yes | English scene description. |
| `model` | string | yes | `meta` |
| `aspect_ratio` | string | no | `16:9` (default) / `9:16` / `1:1`. |
| `resolution` | string | no | `720p` (default) / `480p`. |
| `start_frame` | string | no | Base64 data URI or http(s) URL. Supplying it switches Meta to image-to-video. |
| `end_frame` | string | no | Optional second frame — Meta interpolates from start to end. |

`duration` is ignored: Meta returns its own clip length, which is why it prices flat. Meta does **not** use `ref_images` — pass `start_frame` / `end_frame` instead (`ref_images[0]` and `[1]` are accepted as a fallback so callers reusing the Omni Flash shape still work).

```bash
curl -X POST "https://www.dubvoice.ai/api/v1/video" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "waves crashing on a rocky shore at dawn, cinematic",
    "model": "meta",
    "aspect_ratio": "9:16",
    "resolution": "720p"
  }'
```

### POST /api/video/grok — Grok Imagine
xAI Grok video. Renders synchronously (~60-120 s) and returns the final
`file_url`; refunds credits automatically on failure.

| Field | Type | Default | Notes |
|-------|------|---------|-------|
| `prompt` | string | — | English, 10-5000 chars |
| `duration` | number | 6 | **6, 10 or 15 seconds only** — 15 or more becomes 15 s, 10 to 14 becomes 10 s, anything lower becomes 6 s. |
| `resolution` | string | `480p` | `480p` / `720p` / `1080p` |
| `aspect_ratio` | string | `16:9` | `16:9`, `9:16`, `1:1`, `2:3`, `3:2` |
| `image_base64` | string | — | `data:image/...` URI — auto-switches to image-to-video. |
| `image_url` | string | — | Public http(s) URL — same effect as `image_base64`. |
| `ref_images` | string[] | — | With `first_frame: true`: 1 to 3 frames in order. One = opening; two = opening + closing; three = opening + middle + closing. A fourth is a 400. With `first_frame: false`: one reference image. |
| `first_frame` | boolean | `true` | With images: `true` treats them as frames of the clip (the aspect follows the first image); `false` uses the image as a subject/style reference instead. |

Cost — flat-rate matrix (per clip, not per second):

| Duration | 480p | 720p | 1080p |
|---|---|---|---|
| 6 s  | **3,000 cr** | **4,000 cr** | **6,000 cr** |
| 10 s | **5,000 cr** | **5,500 cr** | **8,250 cr** |
| 15 s | **7,500 cr** | **8,250 cr** | **12,375 cr** |

15 seconds is the longest single clip on the platform — every Veo 3.1 tier
is fixed at 8 s.

Response:

```json
{
  "id": "...", "status": "completed",
  "file_url": "https://...mp4",
  "credits_used": 3000, "duration": 6, "resolution": "480p", "aspect_ratio": "16:9",
  "created_at": "..."
}
```

### POST /api/v1/stock-video — Stock-footage edit
Auto-edited video from a stock library, driven by a script + topic.
Optionally re-times to a supplied narration audio. **Async** — returns a
`job_id`; poll `GET /api/v1/stock-video?job_id=…` for the final
`video_url`. Credits are refunded automatically on failure.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | yes | Script / narration text (10 – 50,000 chars). Drives the credit cost. |
| `topic` | string | yes | Stock library search topic (e.g. `ocean waves`, `forest hike`). |
| `audio_url` | string | no | Public http(s) URL to narration audio (MP3/M4A/WAV). The render backend fetches it, so there is **no size limit** on this path. If set, the cut is re-timed to match the audio and the narration is muxed in. |
| `audio_data_uri` | string | no | Alternative to `audio_url`: base64 `data:audio/*;base64,…` URI. Capped at **3 MB** — it travels in the request body, which the platform limits to 4.5 MB, and base64 adds a third. Use `audio_url` for anything longer. |

**Cost:** 500 credits per 1,000 characters (minimum 500 cr).

```bash
curl -X POST "https://www.dubvoice.ai/api/v1/stock-video" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The Pacific is the largest and deepest ocean on Earth...",
    "topic": "ocean waves",
    "audio_url": "https://example.com/narration.mp3"
  }'
```

Status poll response when ready:

```json
{
  "job_id": "abc123...",
  "status": "DONE",
  "video_url": "https://....supabase.co/storage/v1/object/public/tts-audio/videos/...mp4"
}
```

The first completed poll may return a relative `video_url`
(`/api/text-to-stock-video/download?job_id=...`) — prefix it with
`https://www.dubvoice.ai` to download. Later polls return the storage URL shown above.

Status values: `QUEUED` → `PROCESSING` → `DONE` (or `ERROR`).

---

## tab:image — Image Generation

### POST /api/image-generate
Models (credit cost in parentheses):
- **Nano Banana 2 Lite** — `nano-banana-2-lite` (500 cr flat) — fastest / cheapest tier. 1K native. Accepts up to 10 `image_input` references. No upscale.
- **Nano Banana 2.1** — `nano-banana-2` (1,000 cr flat; the id is unchanged, the model behind it is now 2.1) — fast general-purpose image model. 1K native. Accepts up to 10 `image_input` references. No upscale.
- **Meta AI** — `meta` (1,500 cr flat) — text-to-image and image-to-image. Aspects `1:1` / `9:16` / `16:9` only. Uses named components `character_image` / `scene_image` / `style_image` (any one switches it into i2i) instead of `image_input`; a single `image_input` entry is mapped onto `character_image`.
- **Meta Muse** — `meta-muse` (2,000 cr flat) — text-to-image, or image-to-image with up to **14** `image_input` references, used in the order given. Ten aspects: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`. An aspect ratio outside that list is a 400 before any charge. One image per request, no upscale.
- **Nano Banana Pro** — `nano-banana-pro` (**3,500 cr flat**, reduced from 5,000) — premium quality. 1K native. Accepts up to 10 `image_input` references; supports an optional upscale via `resolution: "2K"` or `"4K"` at the same price.
- **Google Pics** — `google-pics` (1,000 cr flat) — Google's image model. Text-to-image, or image-to-image with up to **14** `image_input` references. Ten aspects: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`. One image per request, logo removed, no upscale.
- **Grok Image** — `grok-image` (1,000 cr) — xAI Grok. Text-to-image and image-to-image; supply up to 5 `image_input` references and Grok auto-switches into i2i mode. Native aspects: 1:1, 9:16, 16:9, 2:3, 3:2, 4:3, 21:9, 5:2.
- **GPT Image 2** — `gpt-image-2` (**15,000 cr flat**, replacing the old 4,500-80,000 `mode` × `resolution` matrix) — OpenAI GPT Image 2. Photorealistic with strong text rendering. Supports **nine aspect ratios** (`1:1`, `9:16`, `16:9`, `3:4`, `4:3`, `2:3`, `3:2`, `21:9`, `4:5`). Output is capped at ~1.57 MP and follows the aspect ratio — there is **no 2K/4K tier and no upscale**, so `resolution` is ignored. Accepts up to **5** positional `image_input` references (no `@tag` binding). Model-specific controls: `quality`, `prompt_mode`, `reasoning`, `web_search` (see the table below) — these change the output, not the price.

All listed prices are final — there is no surcharge or fallback markup. Failures are refunded automatically.

**Monthly plans do not apply here.** Image Max and Veo Max make covered
models free in the dashboard only. An API-key request is always billed in
credits, and never consumes a plan's daily allowance.

**Rate limit:** **10 requests / minute per user** on `POST /api/image-generate`. Exceeding it returns `429 Too Many Requests` with a `Retry-After` header and a `limit_per_minute` field.

**Concurrency limit:** at most **3 image generations in flight per user** at any moment. A 4th request while 3 are already processing returns `429 Too Many Requests` — wait for one to finish before retrying.

**Nano Banana Pro quota (per user, rolling windows — applies ONLY to `nano-banana-pro`):**
- **Daily** — 300 images.
- **Weekly** — 6,000 images.
- **Monthly** — 30,000 images.

`nano-banana-2` (Nano Banana 2.1) is unmetered — no per-window cap. Only `nano-banana-pro` consumes the budget. Hitting any window returns `429 Too Many Requests` with a `quota_window` field (`daily` / `weekly` / `monthly`) and a `resets_at` ISO timestamp. Check your current usage via `GET /api/image-generate/quota`.

### GET /api/image-generate/quota
Returns the caller's current Nano Banana Pro usage:

```json
{
  "models": ["nano-banana-pro"],
  "limits": { "daily": 300, "weekly": 6000, "monthly": 30000 },
  "usage": {
    "daily":   { "used": 12,  "limit": 300,   "remaining": 288,   "resetsAt": "..." },
    "weekly":  { "used": 87,  "limit": 6000,  "remaining": 5913,  "resetsAt": "..." },
    "monthly": { "used": 342, "limit": 30000, "remaining": 29658, "resetsAt": "..." }
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | string | yes | Image description (max 2,000 chars). |
| `model` | string | yes | One of the model IDs above. |
| `aspect_ratio` | string | no | Model-dependent. Nano Banana family: `1:1` / `9:16` / `16:9` / `3:4` / `4:3`. Grok: adds `2:3` / `3:2` / `21:9` / `5:2`, drops `3:4`. Meta: `1:1` / `9:16` / `16:9` only. GPT Image 2: all nine (adds `21:9` / `4:5`). Google Pics and Meta Muse: the ten listed above. Default when omitted: `4:3` (Meta falls back to `16:9`). A value outside the global list (`1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `2:3`, `3:2`, `4:5`, `5:2`, `5:4`) becomes `4:3`. Pick a ratio from the chosen model's own list. |
| `resolution` | string | no | Only meaningful as **Nano Banana Pro's** upscale tier — pass `"2K"` or `"4K"` (same price as native). Every other model is 1K native and ignores it. |
| `quality` | string | no | **GPT Image 2 only.** `low` / `medium` / `high` (default `high`). Affects output only — the price is flat. |
| `prompt_mode` | string | no | **GPT Image 2 only.** `auto` (default — the model refines your prompt) / `direct` (used verbatim). |
| `reasoning` | string | no | **GPT Image 2 only.** `none` (default) / `low` / `medium` / `high` / `xhigh` / `max`. Higher follows the prompt more closely but is slower. |
| `web_search` | boolean | no | **GPT Image 2 only.** `true` grounds the generation with a web search first. Default `false`. |
| `image_input` | string[] | no | Reference images (base64 data URIs or http(s) URLs). Per-model limits: Google Pics 14 / Meta Muse 14 / Nano Banana family 10 / Grok 5 / GPT Image 2 5. Every reference within the limit is used. Use http(s) URLs for large sets; the request body is capped at 4.5 MB. Meta uses the named component fields instead. |
| `reference_images` | string[] | no | Alias of `image_input`. |

```bash
curl -X POST "https://www.dubvoice.ai/api/image-generate" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A futuristic city skyline at sunset", "model": "nano-banana-2" }'
```

Most requests finish synchronously and return
`{ "success": true, "image_url": "...", "credits_used": 1000, "remaining_credits": ... }`.
A long-running one returns HTTP 202 `{ "success": true, "status": "processing", "job_id": "...", "credits_used": ... }`;
poll it with the endpoint below. `image_url` is a URL on our storage (or an
`/api/image-proxy?t=...` fallback path on `https://www.dubvoice.ai`).

### GET /api/image-generate/status?job_id=&lt;job_id&gt;
Poll long-running image tasks. Returns `{ "status": "processing" }`, then
`{ "status": "completed", "image_url": "..." }` or `{ "status": "failed", "error": "..." }`.

---

## tab:music — Music Generation

### POST /api/music-generate — 5,000 cr (returns 1–2 variations)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `customMode` | boolean | yes | `false` = simple (only `prompt`, ≤500 chars). `true` = custom: lyrics (`prompt`) or `style`, or both; an instrumental needs `style`. `title` optional. |
| `instrumental` | boolean | no | `true` = no vocals. |
| `prompt` | string | simple | Idea (≤500, simple) or lyrics (≤5000, custom with vocals). |
| `style` | string | custom | Genre / mood (≤1000 chars). Required for a custom instrumental. |
| `title` | string | no | Track title (≤80 chars). |
| `vocalGender` | string | no | `m` / `f` — custom mode with vocals only. |

```bash
curl -X POST "https://www.dubvoice.ai/api/music-generate" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customMode": true, "instrumental": false,
    "title": "Childhood Dreams", "style": "Folk, Acoustic, Nostalgic",
    "prompt": "Verse 1: When I was young...",
    "vocalGender": "f"
  }'
```

→ `{ "success": true, "task_id": "5c79...be8e" }`

### GET /api/music-generate?id=&lt;task_id&gt; — poll

```json
{
  "status": "succeeded",
  "audio_url": "https://your-storage.supabase.co/.../music_xxx.mp3",
  "audio_urls": ["...mp3", "...mp3"],
  "task_id": "5c79...be8e",
  "credits_used": 5000
}
```

---

## tab:common — Common (auth, voices, account, errors)

### Dashboard-only features (no API)
These exist in the product but are deliberately not exposed to `sk_` keys.
Calling them with an API key returns 401 — they are session-authenticated only.

| Feature | Where | Why no API |
|---|---|---|
| UGC Studio (video ads, brand images) | /dashboard/ugc-video | Session-only by design |
| Brands (saved brand profiles) | /dashboard/ugc-video | Belongs to UGC Studio |
| YouTube Videos (topic → narrated video) | /dashboard/youtube-videos | Session-only by design |
| Monthly plans (Image Max / Veo Max) | /dashboard/balance | Plans never apply to API traffic; API calls always bill credits |

Everything else in the product — TTS, dialogue, voices, cloning, dubbing,
speech-to-text, voice changer, sound effects, pronunciation
dictionaries, translation, video, image, music and stock video — has an API and
is documented in the other tabs.

---


### Authentication
- `Authorization: Bearer sk_your_api_key` (preferred)
- `X-API-Key: sk_your_api_key` (alt header)

`/api/video` and `/api/video/grok` accept only the `Authorization: Bearer` form.

API keys can be created/rotated/revoked at /dashboard/api-docs. Keys are
prefixed `sk_` and shown once on creation.

### GET /api/v1/voices
List available voices with filtering.

| Query param | Description |
|-------------|-------------|
| `provider` | `elevenlabs` (default, **15,106** voices; **13,481** while the extended ElevenLabs model set is enabled) / `minimax` (**481**) / `vbee` (**1,649**) / `fishaudio` (**273**) / `all` (ElevenLabs + Minimax only) |
| `search` | Substring match on name |
| `language` | Exact, case-insensitive match on the voice's `language` field. ElevenLabs / Fish Audio use ISO 639-1 (`en`, `tr`); Vbee uses full names (`Vietnamese`, `Arabic`). |
| `gender` | `male` / `female` |
| `page`, `page_size` | Pagination (default 1, 30) |

`vbee` (1,649 voices, 52 languages, 1,212 of them Vietnamese) and `fishaudio` (273 voices, 14 languages) ship as bundled catalogues, so listing them needs no upstream call. Their voice ids come back already prefixed (`vbee_...`, `fishaudio_...`) and can be passed straight to `POST /api/v1/tts` — see the *Vbee & Fish Audio* tab for the full flow.

```bash
curl "https://www.dubvoice.ai/api/v1/voices?search=rachel&language=en&gender=female" \
  -H "Authorization: Bearer sk_..."
```

### GET /api/v1/me
Returns the authenticated user's email, credit balance and lifetime credits used.

```json
{ "email": "...", "credits": 12345, "total_used": 67890 }
```

### Rate limits
- TTS submit: 240 req/min per key
- Translate: 10 req/min per key
- Voices list: no rate limit
- Image / video / music: 10 req/min per key (long-running)

A 429 response has the body `{ "error": "Too many requests. Please try again later." }`
and the headers `Retry-After` (seconds) and `X-RateLimit-Reset` (Unix time, seconds).
`X-RateLimit-Remaining` is not sent on a 429.

### Error codes

Most 400 responses carry only an `error` text that says what was wrong. The
machine-readable `code` values that exist:

| HTTP | Code | Meaning |
|------|------|---------|
| 400 | — | Bad body / missing field (`error` text only) |
| 400 | `VOICE_NOT_FOUND` | The voice was deleted or is outside the active list. Nothing is charged. |
| 400 | `MINIMAX_NOT_SUPPORTED_HERE` | Used a Minimax voice on `/api/v1/tts` |
| 401 | `INVALID_API_KEY` | Missing / expired / revoked key |
| 402 | — | Insufficient credits (`required` + `available` in body) |
| 404 | — | Task or resource not found |
| 429 | — | Rate limit hit (see `Retry-After` header) |
| 503 | `SERVICE_MAINTENANCE` | Whole platform under maintenance |
| 503 | `FEATURE_MAINTENANCE` | Specific feature (e.g. ElevenLabs) under maintenance |
| 500 | — | Internal error (please retry) |

### Status values (TTS / video / music / image jobs)

`pending` → `processing` → `completed` (or `succeeded` for music) | `failed`.

### Webhooks
Pass `webhook_url` (a public HTTPS URL) on `POST /api/v1/tts` and we POST the
final result there. On success:

```json
{
  "task_id": "...",
  "status": "completed",
  "result": "https://...mp3",
  "srt_url": "https://...srt",
  "characters": 30,
  "created_at": "2026-05-05T12:34:20Z",
  "completed_at": "2026-05-05T12:34:56Z"
}
```

`srt_url` is `null` when no subtitle file could be made. On failure:

```json
{
  "task_id": "...",
  "status": "failed",
  "error": "Audio generation failed. Please try again.",
  "characters": 30,
  "created_at": "2026-05-05T12:34:20Z"
}
```

Each webhook is delivered **once**: a single attempt with a 10-second timeout
and no redirects followed. There are no retries, so keep polling
`GET /api/v1/tts?task_id=...` as the fallback.

### Code examples

**Node (fetch)**

```js
const res = await fetch("https://www.dubvoice.ai/api/v1/tts", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.DUBVOICE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Hello world",
    voice_id: "LB3SchLS4lHotJg4GcZW",
    language: "auto",
  }),
});
const { task_id } = await res.json();
```

**Python (requests)**

```python
import os, requests
r = requests.post(
  "https://www.dubvoice.ai/api/v1/tts",
  headers={"Authorization": f"Bearer {os.environ['DUBVOICE_API_KEY']}"},
  json={"text": "Hello world", "voice_id": "LB3SchLS4lHotJg4GcZW", "language": "auto"},
)
task_id = r.json()["task_id"]
```

**Polling helper**

```python
import time
while True:
    j = requests.get(
      f"https://www.dubvoice.ai/api/v1/tts?task_id={task_id}",
      headers={"Authorization": f"Bearer {api_key}"},
    ).json()
    if j["status"] in ("completed", "failed"): break
    time.sleep(3)
print(j["result"])
```
