API Reference

Overview

Expressive speech, one request away.

SecretVoice is a low-latency text-to-speech API tuned for closeness — breathy whispers, intimate narration, and natural conversational turns. Twenty-nine voices across 21 languages, with synchronous, streaming, and realtime WebSocket delivery.

• 29 premade voices — 13 female, 16 male, each with a distinct persona.
• 21 languages — one voice keeps its character in every language.
• Three delivery modes — synchronous audio, HTTP streaming, and realtime WebSocket.
• Drop-in compatibility — point any ElevenLabs client at this API and it works. See Compatibility →

Billing is simple and transparent: you pay for the audio-seconds you produce, tracked live on your balance.

Quickstart

Your first voice in 30 seconds.

Create an account, grab your API key, and synthesize your first line. One endpoint, one body.

{
  "text": "Come closer. Let me tell you a secret. Now, just listen to my voice.",
  "model_id": "secret-v1"
}

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

import requests

r = requests.post(
    "https://api.secretvoice.dev/v1/text-to-speech/velvet",
    headers={"xi-api-key": "YOUR_KEY", "Content-Type": "application/json"},
    json={"text": "Come closer. Let me tell you a secret.", "model_id": "secret-v1"},
)
open("voice.mp3", "wb").write(r.content)

const res = await fetch("https://api.secretvoice.dev/v1/text-to-speech/velvet", {
  method: "POST",
  headers: { "xi-api-key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ text: "Come closer. Let me tell you a secret.", model_id: "secret-v1" }),
});
const blob = await res.blob();
const url = URL.createObjectURL(blob); // play or save it

Authentication

One header, every request.

All endpoints require your API key, sent as the xi-api-key header. The key is tied to your account and is never shared.

xi-api-key: $SECRETVOICE_API_KEY

• All requests must use HTTPS.
• API keys are scoped to your account and cannot be shared across accounts.
• Requests made without a valid key return 401 with {"detail": "Invalid API key"}.
• Rotating a key invalidates the old one immediately.

Models

One model, tuned for closeness.

SecretVoice exposes a single model, secret-v1, engineered for intimate, expressive delivery. Common model identifiers from compatible clients are accepted as aliases.

{
  "models": [{
    "model_id": "secret-v1",
    "name": "SecretVoice v1",
    "can_do_text_to_speech": true,
    "can_do_voice_conversion": false,
    "languages": ["en", "es", "ja", "fr", "de", "it", "pt", "ru", "zh", "ko", "th", "id", "vi", "ms", "nl", "pl", "et", "fi", "hi", "ta", "cs"]
  }]
}

Voices

Twenty-nine voices, tuned for closeness.

Every voice has a distinct persona and keeps its character across all 21 languages. Voice ids are lowercase shorthands.

{
  "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"
  }, /* …28 more */]
}

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

{
  "stability": 0.5,
  "similarity_boost": 0.75,
  "style": 0.0,
  "speed": 1.0,
  "use_speaker_boost": true
}

PATCH /v1/voices/velvet/settings
{
  "stability": 0.4,
  "speed": 0.9
}

The roster

Female

Male

Text to Speech

Convert text to speech.

The core endpoint. Converts text into speech using a voice of your choice and returns the audio file directly.

curl -X POST "https://api.secretvoice.dev/v1/text-to-speech/whisper?output_format=mp3_44100_128" \
  -H "xi-api-key: $SECRETVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Lean in. I have something to tell you.",
  "model_id": "secret-v1",
  "language_code": "en",
  "voice_settings": { "stability": 0.6, "speed": 0.95 }
}' \
  --output whisper.mp3

Output formats

Streaming

Audio as it's synthesized.

Identical request to the synchronous endpoint, but the audio streams back as it is produced — ideal for agents and long-form narration that want the first byte fast.

curl -X POST "https://api.secretvoice.dev/v1/text-to-speech/velvet/stream" \
  -H "xi-api-key: $SECRETVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "There you are. I was starting to miss you.", "model_id": "secret-v1" }' \
  --output live.mp3

Realtime

A voice agent that responds immediately.

Realtime speech over WebSocket — the protocol voice agents and AI companions use. Send text chunks as they arrive; audio comes back as it's spoken, with word timing preserved for captions.

const ws = new WebSocket(
  "wss://ws.secretvoice.dev/v1/text-to-speech/velvet/stream-input?output_format=mp3_44100_128",
  { headers: { "xi-api-key": "YOUR_KEY" } }
);

ws.onopen = () => {
  ws.send(JSON.stringify({ text: " " }));
  ws.send(JSON.stringify({ text: "There you are. I was starting to miss you." }));
  ws.send(JSON.stringify({ flush: true }));
  ws.send(JSON.stringify({ text: "" }));
};

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.audio) playBase64Audio(msg.audio); // decode + queue
  if (msg.isFinal) ws.close();
};

History

Every generation, retrievable.

Generations are stored on your account so you can re-fetch, review, or delete them. Pass ?enable_logging=false on any synthesis call to opt out (zero retention).

{
  "history": [{
    "history_item_id": "req_01HZxK…",
    "voice_id": "velvet",
    "text": "Come closer. Let me tell you a secret.",
    "date_unix": 1770000000,
    "seconds": 8.3
  }]
}

Account & Billing

Pay for what you produce.

You are billed per audio-second of produced content. Your balance is deducted progressively during generation, and you can monitor it at any time.

{
  "id": "usr_01HZxK…",
  "email": "you@example.com",
  "is_new_user": false,
  "subscription": { "tier": "pay_as_you_go" }
}

{
  "tier": "pay_as_you_go",
  "character_count": 4123,    // audio-seconds used (field name kept for compat)
  "character_limit": -1,
  "next_character_count_reset_unix": 0
}

Multilingual

One voice, twenty-one languages.

Pass a language_code and the same voice keeps its warmth and character in that language. Supported codes:

en · es · de · fr · it · pt · ru · zh · ja · ko · th · id · vi · ms · nl · pl · et · fi · hi · ta · cs

curl -X POST "https://api.secretvoice.dev/v1/text-to-speech/whisper" \
  -H "xi-api-key: $SECRETVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "もっと近くに来て。秘密を教えてあげる。",
  "language_code": "ja",
  "model_id": "secret-v1"
}' \
  --output whisper-ja.mp3

Rate Limits

Fair use, for everyone.

Limits protect the reliability of the Service for all users. They scale with your plan.

When a limit is exceeded, the API returns 429 with a Retry-After header. Back off and retry after the indicated delay; exponential backoff is recommended.

Errors

Errors you can read.

All errors use a consistent, machine-readable body: {"detail": "..."}.

Compatibility

Drop-in for the ElevenLabs protocol.

SecretVoice speaks the ElevenLabs API contract. If your code already talks to ElevenLabs, you can point it at SecretVoice by changing the base URL and using a SecretVoice API key — no code changes.

• Same surface — paths, methods, request bodies, and response shapes follow the same contract.
• Same auth header — xi-api-key is accepted natively.
• Same realtime protocol — the WebSocket stream-input flow matches message-for-message.
• Model aliases — common model identifiers map to secret-v1 automatically.
• Safe over-acceptance — optional fields with no equivalent here are accepted and safely ignored, so clients never break.
• Same error shape — {"detail": "..."} bodies and matching status codes.

Machine-readable

OpenAPI & llms.txt

The API is fully described as machine-readable artifacts, kept in sync with these docs.

• /openapi.json — the complete OpenAPI 3 specification.
• /llms.txt — the API index for AI agents.
• /llms-full.txt — the full reference for AI agents.