# Vocify Voice API

> Turn text into natural speech (MP3 + SRT subtitles) with one HTTP request.
> 322 voices in 76 languages, including Urdu, Hindi, Arabic and English.

Base URL: https://vocify.pro
Auth: send the API key as a header -> Authorization: Bearer YOUR_API_KEY
Get a key: sign in with Google at https://vocify.pro and open Account (the key starts with "sk_").
Billing: 1 token = 1 character of text. Packs: $5 = 2,000,000 tokens · $10 = 5,000,000 tokens · $25 = 15,000,000 tokens · $50 = 35,000,000 tokens. Buy at https://vocify.pro/#/pricing

## 1. Generate speech (main endpoint)

POST https://vocify.pro/api/v1/tts
Content-Type: application/json
Body:
  text    (string, required)  words to speak. Add [pause 2s] or [pause 500ms] for silence.
  voice   (string, optional)  voice id, default "en-us-julia-multi". Get ids from GET /api/v1/voices.
  speed   (number, optional)  0.5 to 2.0, default 1.0
  pitch   (number, optional)  -50 to 50 (Hz), default 0
  volume  (number, optional)  -100 to 100 (%), default 0
  format  (string, optional)  "mp3" (default) returns the MP3 bytes. "json" returns links instead.
  emotion (string, optional)  "auto" = each sentence gets the feeling that fits its meaning (recommended),
                              or one of: happy, sad, angry, excited, fearful, suspenseful, curious, surprised, shocked, confident, empathetic, sarcastic, romantic, hopeful, frustrated, nervous, calm, soothing, mysterious, inspirational, neutral
  style   (string, optional)  one of: natural, conversational, cinematic, documentary, storytelling, audiobook, podcast, news, motivational, comedic, whispering, shouting, asmr
  intensity (number, optional) 0 to 2, default 1 (strength of the emotion)
  dramatic_pauses, pitch_variation (booleans, optional, default true)

Tags you can write inside the text (each lasts until the next tag or the end of the paragraph):
  emotions: [happy] [sad] [angry] [excited] [mysterious] ... (any emotion above), [neutral] resets
  delivery: [whisper] [shout]
  sounds:   [laugh] [chuckle] [sigh] [gasp] [breath] [cry]  (short spoken cues and pauses)
  emphasis: **word**        pause: [pause 2s] or [pause 500ms]

Response for format "mp3": audio/mpeg bytes. Headers: X-Audio-Duration (seconds), X-Characters, X-Tokens-Remaining, X-Audio-Id.
Response for format "json":
  {"id": "...", "audio_url": "https://vocify.pro/files/ID.mp3", "srt_url": "https://vocify.pro/files/ID.srt", "duration": 6.7,
    "characters": 68, "voice": "en-us-julia-multi", "cues": [[start, end, "sentence"], ...], "quota": {"tokens": 1999932, ...}}
Files are kept for 7 days in your library (GET /api/v1/library).

Example (curl):
  curl -X POST https://vocify.pro/api/v1/tts -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
       -d '{"text": "Hello world", "voice": "en-us-julia-multi"}' --output speech.mp3

Example (Python):
  import requests
  r = requests.post("https://vocify.pro/api/v1/tts", headers={"Authorization": "Bearer YOUR_API_KEY"},
                    json={"text": "Hello world", "voice": "ur-pk-hina"})
  r.raise_for_status(); open("speech.mp3", "wb").write(r.content)

Example (JavaScript):
  const r = await fetch("https://vocify.pro/api/v1/tts", {method: "POST",
    headers: {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    body: JSON.stringify({text: "Hello world", voice: "en-us-julia-multi"})});
  const blob = await r.blob();  // MP3

## 2. List voices (no key needed)

GET https://vocify.pro/api/v1/voices            optional query: lang=ur | locale=en-GB | gender=Female | multilingual=true | q=search
Returns {"count": N, "voices": [{"id": "ur-pk-hina", "name": "Hina", "language": "Urdu", "region": "Pakistan", "gender": "Female", "multilingual": false}, ...]}
Popular ids: en-us-julia-multi, en-us-max-multi, en-us-eva-multi, en-us-lucas-multi (most natural, speak many languages),
             ur-pk-hina, ur-pk-hamza, hi-in-kavya, hi-in-arjun, ar-sa-nadia, ar-sa-majid, en-gb-iris, en-gb-owen
Preview a voice: GET https://vocify.pro/api/v1/voices/VOICE_ID/preview  (short MP3)

## 3. Dialogue (several voices in one file)

POST https://vocify.pro/api/v1/dialogue
Body: {"lines": [{"voice": "ur-pk-hamza", "text": "..."}, {"voice": "ur-pk-hina", "text": "..."}], "gap": 0.35}
Also accepts speed, pitch, volume, format. Returns the same as /api/v1/tts.

## 4. Dub subtitles (SRT -> timed audio)

POST https://vocify.pro/api/v1/srt
Body: {"srt": "<full .srt file text>", "voice": "hi-in-kavya", "auto_fit": true}
Each subtitle line is voiced and placed at its timestamp. auto_fit speeds up lines that would overlap.

## Long texts

If the audio takes longer than about 85 seconds to make, the answer is HTTP 202 with
{"job_id": "...", "status": "processing", "poll_url": "https://vocify.pro/api/v1/jobs/JOB_ID"}.
Poll GET poll_url (same Authorization header) every 3-5 seconds until "status" is "done"; that answer has the same
fields as format=json (audio_url, srt_url, duration, ...). "failed" includes {"error": {"code", "message"}}.
The finished audio is also saved in your library.

## 5. Check balance

GET https://vocify.pro/api/v1/me   (with the Authorization header)
Returns {"kind": "key", "name": "...", "quota": {"available": 1999932, "tokens": 1999932, "plan": null, "unlimited": false, ...}}
"available" is what you can spend. With a monthly plan, "plan" shows {"name", "tokens" left, "until" (last day), "active"};
plan tokens are used first and end with the plan, bought tokens never expire.

## 6. Your library (re-download earlier audio)

GET https://vocify.pro/api/v1/library   (with the Authorization header; optional ?limit=50&offset=0)
Every file you generate with your key is kept for 7 days (newest 200).
Returns {"retention_days": 7, "total": N, "items": [{"id": "...", "title": "...", "voice": "...", "duration": 6.7,
  "created_at": 1790000000, "expires_at": 1790600000, "audio_url": "https://vocify.pro/files/ID.mp3", "srt_url": "https://vocify.pro/files/ID.srt"}]}
Delete one: POST https://vocify.pro/api/v1/library/ID/delete

## 7. OpenAI-compatible endpoint

POST https://vocify.pro/v1/audio/speech with {"model": "tts-1", "input": "text", "voice": "en-us-julia-multi", "speed": 1.0}
Works with the official OpenAI SDKs: OpenAI(api_key="YOUR_API_KEY", base_url="https://vocify.pro/v1")
OpenAI voice names (alloy, echo, fable, onyx, nova, shimmer) are also accepted.

## Errors

All errors are JSON: {"error": {"code": "...", "message": "..."}}
400 empty_text | invalid_voice | invalid_param | invalid_srt    -> fix the request
401 invalid_key | key_required                                  -> missing or wrong key
402 insufficient_tokens                                         -> top up at https://vocify.pro/#/pricing
403 key_disabled | key_expired
413 text_too_long                                               -> split text (max 100,000 characters per request)
429 quota_exceeded                                              -> daily limit reached
502 tts_failed                                                  -> temporary, retry after a few seconds

## Tips for AI agents

- For long text, send it in one request (up to the limit); it is split and voiced in parallel automatically.
- Use format "json" when you need a shareable link instead of raw bytes.
- Markdown symbols (#, **, -) and emoji are removed automatically before speaking.
- Machine-readable spec: https://vocify.pro/openapi.json