Voicely API reference

Base URL https://api.tryvoicely.com. The API is for server-side integrations: browser calls are not supported, and your key must never reach a browser or app. Machine-readable spec: OpenAPI 3.1. Get a key on API access. New to the API? Start with the text-to-speech API overview.

Switching from ElevenLabs

What stays the same and what to change. Only the endpoints and fields on this page are supported.

Authentication

Send your key (vly_live_ followed by 43 characters) in the xi-api-key header, or as Authorization: Bearer <key>. A key in the URL or query string is refused (400 api_key_in_query). Keys are shown once when created; revoke a leaked key immediately on the API access page.

Endpoints

• GET /v1/models List models
• GET /v1/voices List voices
• GET /v2/voices Search and page voices (ElevenLabs v2 shape)
• GET /v1/voices/{voice_id} Get one voice
• GET /v1/user Account, key and balance summary
• GET /v1/user/subscription Balances, limits and conversion setting
• POST /v1/text-to-speech/{voice_id} Synthesize speech (complete MP3 or raw audio)
• POST /v1/text-to-speech/{voice_id}/stream Synthesize speech (MP3 or raw audio, streamed while it is generated)

Text to speech

POST /v1/text-to-speech/{voice_id}?output_format=mp3_44100_128 with a JSON body. The response is the complete audio (MP3 by default, or a raw format chosen with output_format). To receive audio while it is generated, use streaming.

• text (required): 1 to 1,000 Unicode code points.
• model_id: voicely-flash-v1, the only model and the default. See models.
• language_code: any language available in Voicely Studio, as an ISO code or an exact Studio locale (see Languages). When omitted, Urdu script, Devanagari and Latin text are detected as ur, hi and en. For Roman Urdu see Urdu.
• Other fields some clients send are validated but not applied; their names are returned in X-Voicely-Ignored-Parameters. Pronunciation dictionaries are refused (422).
• Output format (output_format): mp3_44100_128, pcm_24000, pcm_16000, ulaw_8000. Raw formats have no header, so your client must know the format.
  • mp3_44100_128: MP3, 44.1 kHz, 128 kbit/s, mono (audio/mpeg). The default.
  • pcm_24000: raw PCM, signed 16-bit little-endian, mono, 24,000 Hz, with no header, not a WAV file (audio/pcm). The engine’s own audio passed through unchanged (lossless); it skips the MP3 encoding step. About 384 kbit/s.
  • pcm_16000: raw PCM, signed 16-bit little-endian, mono, 16,000 Hz, with no header (audio/pcm). Resampled from the engine’s 24 kHz audio. About 256 kbit/s.
  • ulaw_8000: raw G.711 μ-law, mono, 8,000 Hz, 1 byte per sample, with no header, not an AU file (audio/basic). Phone-line (narrowband) quality, for telephony. 64 kbit/s.

Models

• Send model_id: "voicely-flash-v1". It is the only advertised model, and the default.
• eleven_v3 is still accepted temporarily as a deprecated legacy request-compatibility alias. It resolves to voicely-flash-v1: no ElevenLabs engine is used, and it provides no Eleven v3 quality, audio-tag behaviour or feature parity. Responses to a request that used it carry a Deprecation header, and X-Voicely-Model-Requested and X-Voicely-Model show the alias and voicely-flash-v1. Send model_id voicely-flash-v1.
• Audio tags (bracketed cues such as [laughs]) are not part of the Voicely API contract. They may be read aloud literally or behave inconsistently. Do not rely on them.

Languages (31)

• Every language available in Voicely Studio is available through the API. Send its ISO code (for example es) or an exact Studio locale (for example es-MX). A base code uses the Studio's default locale for that language.
• When language_code is omitted, only Urdu script (ur), Devanagari (hi) and Latin text (en) are detected. Send language_code for every other language.
• Any other language_code answers 422 unsupported_language, including a region the Studio does not list for that language (for example es-XX, pt-AO or zh-HK). Only English, Urdu and Hindi also accept any other regional spelling (en-ZA is English), as they always have.
• Mandarin Chinese uses the public code zh. zh, zh-CN, cmn and cmn-CN are the same language (Studio locale cmn-CN); zh-TW and cmn-TW are Taiwan Mandarin (Studio locale cmn-TW).
• In voice objects, languages lists what a voice can be requested with; verified_languages lists only languages with production API evidence (today en, ur, hi).

Urdu

• Urdu script (Nastaliq) is detected automatically as ur when language_code is omitted.
• Roman Urdu (Urdu written in Latin letters) must send language_code: "ur". Without it, Latin text is treated as English.
• Urdu is spoken by two dedicated voices: a request for any female voice uses vly_f08, and any male voice uses vly_m05.
• The response headers X-Voicely-Voice-Requested and X-Voicely-Voice-Used show the voice you asked for and the voice that spoke.
• Billing counts the characters of the text you send, not of the internal Urdu normalization.
• Urdu text is normalized before synthesis, which can add some startup latency to the first audio.

Streaming

POST /v1/text-to-speech/{voice_id}/stream takes the same body, query, voices, languages, character limit and authentication as the buffered endpoint. The response is audio/mpeg, or a raw format (audio/pcm for pcm_24000 and pcm_16000, audio/basic for ulaw_8000), sent while it is being generated, over plain HTTP (no WebSocket), so you can start playing or forwarding it before the whole file exists.

• A clean end of the body means the request completed and was charged. A body that ends with an error (a reset or a truncated response) was not charged, even if some audio already arrived: discard that audio and retry with a new Idempotency-Key.
• If your client closes the connection before the stream ends, the request is not charged.
• Headers are sent before the charge is final: X-Voicely-Characters-Input, X-Voicely-Characters-Reserved (the 100-character blocks held for this request) and X-Voicely-Charge-Status: reserved. A live stream never states a charge or a balance; read them afterwards with GET /v1/user/subscription.
• Errors before the first audio byte are normal JSON responses with the codes below. Errors after it end the stream instead of sending JSON; send an Idempotency-Key to read the stored outcome with a retry of the same key and body (the stored MP3 after a clean end, or the stored error after a failed stream). Without a key no audio is stored.
• 503 streaming_not_available means streaming is paused or at capacity right now. You were not charged: send that request to the buffered endpoint.
• A stream lasts at most 120 seconds and its audio is capped at 170 seconds. The per-minute and one-at-a-time limits are shared with the buffered endpoint.
• Send a sentence or a short paragraph per request if you want audio to start sooner.

curl (streaming)

IDEMPOTENCY_KEY="$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)"

curl -N --fail-with-body -sS -X POST \
  "https://api.tryvoicely.com/v1/text-to-speech/vly_f02/stream?output_format=mp3_44100_128" \
  -H "xi-api-key: $VOICELY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"text":"Hello from the Voicely API.","model_id":"voicely-flash-v1","language_code":"en"}' \
  --output speech.mp3 && echo "complete (charged)" || echo "failed or cut off (not charged): retry with a new key"

Examples

Replace the placeholder with your key via an environment variable (VOICELY_API_KEY). Never paste a key into code you commit.

curl

# A new unique Idempotency-Key per synthesis (uuidgen on macOS/Linux; /proc fallback on Linux)
IDEMPOTENCY_KEY="$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)"

curl --fail-with-body -sS -X POST \
  "https://api.tryvoicely.com/v1/text-to-speech/vly_f02?output_format=mp3_44100_128" \
  -H "xi-api-key: $VOICELY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"text":"Hello from the Voicely API.","model_id":"voicely-flash-v1","language_code":"en"}' \
  --output speech.mp3

Node.js (fetch)

// Node 18+ (server-side only; never ship the key to a browser)
import { writeFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const apiKey = process.env.VOICELY_API_KEY;
if (!apiKey) throw new Error("Set VOICELY_API_KEY in the server environment first.");

const res = await fetch("https://api.tryvoicely.com/v1/text-to-speech/vly_f02?output_format=mp3_44100_128", {
  method: "POST",
  headers: {
    "xi-api-key": apiKey,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({"text":"Hello from the Voicely API.","model_id":"voicely-flash-v1","language_code":"en"}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log("billed characters:", res.headers.get("x-voicely-characters-charged"));
await writeFile("speech.mp3", Buffer.from(await res.arrayBuffer()));

Python (requests)

# Python 3 + requests (server-side only)
import os, uuid, requests

r = requests.post(
    "https://api.tryvoicely.com/v1/text-to-speech/vly_f02",
    params={"output_format": "mp3_44100_128"},
    headers={
        "xi-api-key": os.environ["VOICELY_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"text":"Hello from the Voicely API.","model_id":"voicely-flash-v1","language_code":"en"},
    timeout=180,
)
r.raise_for_status()
print("billed characters:", r.headers.get("x-voicely-characters-charged"))
open("speech.mp3", "wb").write(r.content)

Billing

• Only successful requests are charged. Failed requests (any 4xx or 5xx) cost nothing.
• Actual vs billed characters: each request is billed in whole 100-character blocks, rounded up (for example 1-100 characters = 100, 250 = 300). The response headers X-Voicely-Characters-Input (actual) and X-Voicely-Characters-Charged (billed) show both.
• 1 paid credit = 1,000 API characters. Current packs are on the pricing page. Signed in, buy credits for the API shows what each pack and payment method works out to per 1,000 API characters.
• Requests are paid from your API wallet first. If you turn on auto-conversion, purchased Voicely credits are converted as needed: 1 credit = 1,000 API characters, up to the daily limit you choose. Website free and trial credits are never used.
• Eligible accounts may request one device-verified trial with 12,000 API characters on the API access page. The trial is added directly to your API wallet. Website free and trial credits are never used by the API.
• X-Voicely-Character-Balance is what you can spend right now. GET /v1/user/subscription also shows the total including paid credits not yet convertible today.
• 402 insufficient_balance: not enough spendable balance. 402 api_spend_limit_reached: today's conversion limit is used up; X-Voicely-Spend-Limit-Reset gives the reset time (00:00 UTC).

Idempotent retries

Send Idempotency-Key (1-128 printable ASCII characters, no spaces), a new UUID per synthesis. If the connection drops, retry the same payload with the same key: a finished request returns the stored audio for 48 hours without a second charge; a running one answers 409 request_in_progress. Reusing a key with a different payload answers 409 idempotency_mismatch.

Limits

10 requests per minute and 1 request at a time per account. On 429 wait forRetry-After (60 s for the per-minute limit, 5 s for concurrency).

• Set your HTTP client timeout to at least 180 seconds (a recommendation that covers every server-side wait below).
• Complete audio (buffered): the server waits up to 90 seconds for synthesis.
• Streaming: a stream ends at most 120 seconds after it starts, and its audio is capped at 170 seconds.

• Retry-After is sent on: 429 rate_limit_exceeded, 429 concurrency_limit_exceeded, 409 request_in_progress, 503 service_busy, 503 provider_unavailable (when synthesis is not ready).
• Proactive rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are not sent. Read your limits from GET /v1/user/subscription.

Errors and retries

Errors are JSON: {"detail":{"status","message"},"code","request_id"}. Messages never include provider details or secrets.

• 4xx (except 409 and 429): fix the request. Do not retry it unchanged.
• 409 request_in_progress, 429: wait for Retry-After, then retry the same request (the same Idempotency-Key is fine).
• 500, 502, 503, 504: you were not charged. Retry after a short backoff with a new Idempotency-Key: a failed request's key replays the same error.
• Failures are never charged. Use exponential backoff and stop after a few attempts.

Voices (30)

The same data as GET /v1/voices. Urdu is spoken by the two dedicated Urdu voices; Urdu sent with any other voice uses the one of the same gender. Every voice object has a preview_url field; it is null until first-party preview samples are published. No preview audio exists yet.

Versioning and changelog

• The /v1 paths (and GET /v2/voices) are the current Public Beta.
• New response fields, headers and endpoints may be added at any time. Ignore fields you do not recognise.
• Breaking changes (removing or renaming a field, error code or endpoint, or changing what it means) are announced here first with notice, or shipped under a new version.

• 2026-10-01 Language parity: every language available in Voicely Studio (31 languages, 39 locales) is accepted by language_code.
• 2026-10-01 eleven_v3 deprecated: still accepted as a legacy compatibility alias for voicely-flash-v1, no longer listed in GET /v1/models accepted_aliases, and responses that used it carry a Deprecation header. No removal date yet.
• 2026-09-30 First-class Urdu: Urdu script and Roman Urdu (language_code ur), spoken by vly_f08 and vly_m05.
• 2026-09-30 Voice discovery: GET /v2/voices (search and paging) and GET /v1/voices/{voice_id}.
• 2026-09-30 Raw output formats: pcm_24000, pcm_16000 and ulaw_8000.
• 2026-09-30 HTTP streaming (POST /v1/text-to-speech/{voice_id}/stream) available to every account.

Public Beta scope

• WebSocket connections (streaming is plain HTTP; /stream may answer 503 streaming_not_available when paused or at capacity)
• Voice cloning or custom voices
• Output formats other than mp3_44100_128, pcm_24000, pcm_16000, ulaw_8000
• Browser-direct (CORS) calls: server-side integrations only
• The request shape follows a convention many TTS clients use, but the Voicely API is not a complete replacement for another provider's API. Only the endpoints and fields above are supported.
• Beta: no uptime guarantee; limits and details may change. Use is subject to the API Beta Terms shown on the API access page.