# SecretVoice API — Full Reference for AI Agents

SecretVoice is a low-latency text-to-speech API tuned for closeness: 29 premade voices (13 female, 16 male), 21 languages, and three delivery modes (synchronous, streaming, realtime WebSocket). Drop-in compatible with the ElevenLabs protocol — point any ElevenLabs client at `https://api.secretvoice.dev` with a SecretVoice API key.

Base URL: `https://api.secretvoice.dev` · WebSocket: `wss://ws.secretvoice.dev`
Auth: `xi-api-key: $SECRETVOICE_API_KEY` (also `X-API-Key` / `Authorization: Bearer`)

## Models
`GET /v1/models` → `{"models":[{"model_id":"secret-v1","name":"SecretVoice v1","can_do_text_to_speech":true,"can_do_voice_conversion":false,"languages":["en","es","de","fr","it","pt","ru","zh","ja","ko","th","id","vi","ms","nl","pl","et","fi","hi","ta","cs"]}]}`
Common model aliases (`eleven_multilingual_v2`, `eleven_flash_v2_5`, `eleven_turbo_v2_5`) are accepted and mapped to `secret-v1`.

## Voices
`GET /v1/voices` → ElevenLabs-shaped roster:
```json
{"voices":[{"voice_id":"velvet","name":"Velvet","category":"premade","labels":{"gender":"female","style":"rich and luxurious"},"preview_url":"https://api.secretvoice.dev/v1/voices/velvet/preview.mp3"}, ...]}
```
`GET /v1/voices/{voice_id}/preview.mp3` — 301 redirect to the preview audio.
Female: velvet, whisper, angel, jade, dominique, chloe, honey, crystal, diamond, sunny, star, candy, bubbles
Male: professor, titan, blaze, phoenix, stone, duke, ace, chase, rico, rocco, steele, sage, rex, chill, maverick, tender

`GET /v1/voices/{voice_id}` — single voice.

## Text to Speech (synchronous)
`POST /v1/text-to-speech/{voice_id}?output_format=mp3_44100_128`
Body (JSON):
- `text` (required)
- `model_id` (default `secret-v1`)
- `language_code` (ISO 639-1, default `en`)
- `voice_settings` — `stability` (0-1), `similarity_boost` (0-1), `style` (0-1, accepted), `speed` (0.5-2), `use_speaker_boost` (accepted)
- `apply_text_normalization` — `auto` | `on` | `off`

Compatibility: `seed`, `previous_request_ids`, `next_request_ids`, `pronunciation_dictionary_locators` are accepted and safely ignored. `previous_text`/`next_text` improve continuity.

Response: `200` audio file. Headers: `X-Request-Id`, `X-Duration` (audio-seconds billed).

Output formats: `mp3_*` (22050/24000/44100 Hz, 32-192 kbps), `wav_*` (8000-44100), `pcm_*` (8000-48000), `opus_48000_*`, `ulaw_8000`, `alaw_8000`.

## Streaming (HTTP)
`POST /v1/text-to-speech/{voice_id}/stream` — same body; audio streams back chunked.

## Realtime (WebSocket)
`WS wss://ws.secretvoice.dev/v1/text-to-speech/{voice_id}/stream-input`
Client sends: `{"text":" "}` (init) → `{"text":"..."}` chunks → `{"flush":true}` → `{"text":""}` (close).
Server sends: `{"audio":"<base64>","isFinal":false}` chunks → `{"isFinal":true}`; `{"error":"..."}` on failure.

## History
- `GET /v1/history` — list generations (history_item_id, voice_id, text, date_unix, seconds)
- `GET /v1/history/{history_item_id}` — download audio
- `DELETE /v1/history/{history_item_id}` — delete
- `?enable_logging=false` on synthesis = zero retention

## Account & Billing
- `GET /v1/user` — account
- `GET /v1/user/subscription` — `{"tier":"pay_as_you_go","character_count":<seconds used>,"character_limit":-1,"next_character_count_reset_unix":0}`
Billing: per audio-second of produced content.

## Errors
All errors: `{"detail":"..."}`. 400 invalid request · 401 invalid key · 402 insufficient balance · 404 voice/model not found · 422 validation · 429 rate limited · 500 internal · 501 not implemented.

## Multilingual
21 languages: en, es, de, fr, it, pt, ru, zh, ja, ko, th, id, vi, ms, nl, pl, et, fi, hi, ta, cs.
Example: `POST /v1/text-to-speech/whisper` with `{"text":"もっと近くに来て。秘密を教えてあげる。","language_code":"ja","model_id":"secret-v1"}`.

## Quickstart
```bash
curl -X POST https://api.secretvoice.dev/v1/text-to-speech/velvet \
  -H "xi-api-key: $SECRETVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Come closer. Let me tell you a secret.", "model_id": "secret-v1"}' \
  --output voice.mp3
```