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.
For Businesses, Teams & Developers
Integrate with explicit API contracts
Use the documented request, audio-format and streaming contracts to connect your backend. API credentials and allowance are separate from ordinary Studio generation.
For Creators
Making videos or voiceovers?
Use Voicely Studio to turn your finished script into audio. Choose the model and language that fit your content.
Catalog and model routing checked 2026-11-04. Live authenticated discovery remains authoritative.
WebSocket text-to-speech API guide explains transport selection and server-side integration. For automation workflows, use the Voicely n8n text-to-speech integration. The reference below retains the protocol, billing units and limits.
5-minute quickstart
- Create a server-side key on API access.
- Set it as
VOICELY_API_KEYin your terminal environment. Never paste it into browser or mobile code. - Run the command below. It saves a playable
speech.mp3in the current directory.
# 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.mp3Play it with your normal audio player, or run ffplay speech.mp3 if ffplay is installed.
/stream to receive one complete text request as audio while it is generated, or WebSocket streaming when text arrives incrementally or a conversation needs multiple contexts on one persistent connection.Switching from ElevenLabs
What stays the same and what to change. Only the endpoints and fields on this page are supported.
| Topic | Same or change | Voicely |
|---|---|---|
| Base URL | Change | https://api.tryvoicely.com |
| Authentication | Same | xi-api-key header (Authorization: Bearer also works) |
| Endpoints | Same | POST /v1/text-to-speech/{voice_id} (complete audio) and POST /v1/text-to-speech/{voice_id}/stream |
| Voice IDs | Change | Voicely voice IDs (vly_f01 to vly_f14, vly_m01 to vly_m16), listed by GET /v2/voices and GET /v1/voices |
| model_id | Change | Seven Voicely models from GET /v1/models; voicely-flash-v1 remains the default when model_id is omitted |
| Characters per request | Change | 1 to 5,000 |
| Languages | Change | Choose the language_code from the selected API model’s catalog. Narration offers 138 options and Narration Lite 109; legacy models retain their existing catalog and aliases. |
| Output formats | Change | mp3_44100_128, pcm_24000, pcm_16000, ulaw_8000 |
| Streaming | Same | HTTP streaming on /stream. WebSocket stream-input and multi-stream-input require a completed paid credit conversion and at least one billing block in the API wallet (see WebSocket access requirements). |
| voice_settings, seed | Change | Validated but not applied. Named in X-Voicely-Ignored-Parameters. |
| Timestamps, voice cloning, pronunciation dictionaries | Change | WebSocket sync_alignment=true returns estimated per-segment character timings derived from audio duration, not provider-native or forced alignment. There is no timestamp endpoint or voice cloning; pronunciation_dictionary_locators is refused (422). |
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/modelsList modelsGET /v1/voicesList voicesGET /v2/voicesSearch and page voices (ElevenLabs v2 shape)GET /v1/voices/{voice_id}Get one voiceGET /v1/userAccount, key and balance summaryGET /v1/user/subscriptionBalances, limits and conversion settingPOST /v1/text-to-speech/{voice_id}Synthesize speech (complete MP3 or raw audio)POST /v1/text-to-speech/{voice_id}/streamSynthesize 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 5,000 Unicode code points.model_id: choose one of the seven current model IDs.voicely-flash-v1remains the default when omitted. See models.language_code: a language code from your selected API model’s catalog, or a supported legacy locale alias (see Languages). Legacy models detect Urdu script, Devanagari and Latin text as ur, hi and en when omitted. Narration models use provider auto-detection from the supplied text. For Roman Urdu see Urdu.webhook: optional boolean, default false. Set true for a completion or failure event after this HTTP generation finishes. See webhooks.- 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.
Seven models. One stable API contract.
Use Voicely model IDs returned by GET /v1/models. Your existing voicely-flash-v1 default, API keys and voice IDs stay compatible. Switching models is an explicit choice; a larger language catalog does not silently replace your selected model.
| Model | Technical ID | Language options | HTTP / WS audio delivery |
|---|---|---|---|
| Voicely Classic | voicely-flash-v1 | 31 | Supported · provider streaming |
| Voicely HD | voicely-tts-hd-v1 | 31 | Supported · buffered segments |
| Voicely Classic Pro | voicely-tts-classic-pro-v1 | 31 | Supported · provider streaming |
| Voicely Speech Preview | voicely-tts-preview-v1 | 31 | Supported · provider streaming |
| Voicely Narration | voicely-tts-narration-v1 | 138 | Supported · provider streaming |
| Voicely Narration Lite | voicely-tts-narration-lite-v1 | 109 | Supported · provider streaming |
| Voicely Classic Lite (Preview) | voicely-tts-classic-lite-v1 | 31 | Supported · provider streaming |
Keep existing clients stable
The default is Voicely Classic. Keep your existing model_id when repeatability matters; model and language changes should be deliberate.
Choose transport separately
HTTP returns a complete file; /stream delivers one request as audio; WebSocket accepts incremental text. HD buffers segments rather than promising provider-native streaming.
Check feature scope
The Public API catalog currently advertises can_use_style:false. Studio and n8n Suite style controls do not automatically become Public API parameters; legacy voice_settings and seed remain ignored.
Legacy alias and audio-tag compatibility
- 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.
Choose languages for the model you actually use
Narration has 138 selectable language/script options and aliases; Narration Lite has 109. The five legacy models retain their 31 public base-language entries and existing locale aliases. These counts describe selectable entries, not a claim that every model supports 138 independent languages or that every option has individual provider UAT.
voicely-flash-v1
31 language options · 31 shown
Use the exact code below as language_code. Entries can include scripts and compatibility aliases; they are not a count of independent languages. A Voicely preview label is separate from the underlying model’s release stage.
| Language | Request code | Availability |
|---|---|---|
| English | en | Catalog option |
| Urdu | ur | Catalog option |
| Hindi | hi | Catalog option |
| Arabic | ar | Catalog option |
| Bangla | bn | Catalog option |
| Dutch | nl | Catalog option |
| French | fr | Catalog option |
| German | de | Catalog option |
| Indonesian | id | Catalog option |
| Italian | it | Catalog option |
| Japanese | ja | Catalog option |
| Korean | ko | Catalog option |
| Marathi | mr | Catalog option |
| Polish | pl | Catalog option |
| Portuguese | pt | Catalog option |
| Romanian | ro | Catalog option |
| Russian | ru | Catalog option |
| Spanish | es | Catalog option |
| Tamil | ta | Catalog option |
| Telugu | te | Catalog option |
| Thai | th | Catalog option |
| Turkish | tr | Catalog option |
| Ukrainian | uk | Catalog option |
| Vietnamese | vi | Catalog option |
| Chinese Mandarin | zh | Catalog option |
| Punjabi | pa | Catalog option |
| Gujarati | gu | Catalog option |
| Kannada | kn | Catalog option |
| Malayalam | ml | Catalog option |
| Hebrew | he | Catalog option |
| Swahili | sw | Catalog option |
For live discovery, call GET /v1/models and read the selected model’s languages, language_options, streaming_mode and language_detection. Never assume every model accepts the largest catalog.
Legacy base codes and locale aliases
- Languages are model-specific. GET /v1/models is the live discovery authority; use its language_id values as language_code. The legacy reference below remains useful for older base codes and locale aliases.
- Legacy models use the existing Urdu/Devanagari/Latin script heuristic when language_code is omitted. Narration models use provider language auto-detection; the selected code still controls admission and applicable input normalization, not translation.
- Unsupported model/language combinations answer 422 unsupported_language. Existing legacy locale aliases remain accepted where supported; do not invent regional or vly-lang codes.
- 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).
| language_code | Language | Supported legacy locales | Aliases |
|---|---|---|---|
en | English | en-IN, en-US, en-GB, en-AU | |
ur | Urdu | ur-PK | |
hi | Hindi | hi-IN | |
ar | Arabic | ar-EG | |
bn | Bangla | bn-BD | |
nl | Dutch | nl-NL | |
fr | French | fr-FR, fr-CA | |
de | German | de-DE | |
id | Indonesian | id-ID | |
it | Italian | it-IT | |
ja | Japanese | ja-JP | |
ko | Korean | ko-KR | |
mr | Marathi | mr-IN | |
pl | Polish | pl-PL | |
pt | Portuguese | pt-BR, pt-PT | |
ro | Romanian | ro-RO | |
ru | Russian | ru-RU | |
es | Spanish | es-ES, es-MX, es-419 | |
ta | Tamil | ta-IN | |
te | Telugu | te-IN | |
th | Thai | th-TH | |
tr | Turkish | tr-TR | |
uk | Ukrainian | uk-UA | |
vi | Vietnamese | vi-VN | |
zh | Chinese Mandarin | cmn-CN, cmn-TW | cmn, zh-CN, zh-TW |
pa | Punjabi | pa-IN | |
gu | Gujarati | gu-IN | |
kn | Kannada | kn-IN | |
ml | Malayalam | ml-IN | |
he | Hebrew | he-IL | |
sw | Swahili | sw-KE |
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 uses one additional normalization request before synthesis, so first audio may take roughly one extra model round trip. The added time varies with provider and network load; there is no fixed latency promise.
Webhooks
Create a signed HTTPS endpoint and choose its events in API Access > Webhooks. Events are recorded with the service result and delivered separately. A failed or slow receiver does not fail the service.
For public TTS, send "webhook": true in the JSON body of the buffered or HTTP streaming request. It defaults to false and must be a boolean. Keep the same flag when retrying an Idempotency-Key. A replay does not create another event. Only accepted generations ending in completed or failed states produce TTS events; authentication, validation and pre-generation refusals do not. WebSocket TTS and browser Studio generations are excluded.
| Event | Source reference | Data fields |
|---|---|---|
stt.job.completedstt.job.failed | job_id | job_id, language, billable_ms, charged_ms, error_code, completed_at, result_expires_at |
voice.profile.approvedvoice.profile.rejected | voice_id | voice_id, status, error_code |
voice.conversion.completedvoice.conversion.failed | operation_id | operation_id, voice_id, duration_ms, status |
calling.call.completed | call_id | call_id, agent_id, started_at, ended_at, duration_ms, charged_micro |
tts.generation.completedtts.generation.failed | request_id | request_id, voice_id, model_id, characters, billing_blocks, status |
The common envelope contains id, type, created_at, account_id, api_version and data. The current api_version is 2026-11. No input text, transcript text, audio bytes or private provider handles are included in these events. Fetch an STT result with its job ID. Failed TTS generations have zero billing_blocks; conversion duration_ms describes normalized input duration.
Voice-profile verification happens inside creation, so approval or rejection normally arrives within seconds. It does not represent a later manual review. Uncertain outcomes wait for resolution. STT retries and customer cancellations are silent until a completed or failed result exists.
Verify x-voicely-event-id, x-voicely-timestamp and x-voicely-signature against the raw request body using the v1 signing scheme. Reject stale timestamps, acknowledge with 2xx and deduplicate by event id. Delivery order is not guaranteed. Existing n8n call.completed subscriptions keep their original payload and delivery behavior; calling.call.completed is the platform event. Use a standard n8n Webhook node for the new catalog until the Voicely Trigger event picker is updated.
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, so you can start playing or forwarding it before the whole file exists. For a persistent connection that takes text as it arrives, see WebSocket streaming (completed paid-credit conversion and funded API wallet required).
In short: HTTP streaming accepts one complete text payload in one POST; WebSocket streaming keeps a connection open and accepts incremental text, flushes and (on multi-stream-input) multiple conversational contexts.
- 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) andX-Voicely-Charge-Status: reserved. A live stream never states a charge or a balance; read them afterwards withGET /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-Keyto read the stored outcome with a retry of the same key and body (the stored audio in the requested format after a clean end, or the stored error after a failed stream). Without a key no audio is stored. - A stream lasts at most 120 seconds and its audio is capped at 170 seconds. The per-minute and concurrency 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"WebSocket streaming (Public API)
WebSocket access requirements
WebSocket streaming is open to API accounts that have completed a paid credit conversion (Voicely credits bought and converted into the API wallet) and currently have at least one 100-character billing block in that wallet. Free-trial-only accounts do not unlock it. A key whose account has never converted paid credit is refused after the connection opens with websocket_not_enabled_for_account (close code 1008); a wallet below one 100-character block is refused with insufficient_balance. Every limit below applies to every account.
Connect to wss://api.tryvoicely.com. The OpenAPI document covers the HTTPS endpoints only; this section is the WebSocket reference.
- Send your key in the xi-api-key header of the upgrade request.
- Server runtimes whose standard WebSocket constructor cannot set headers may instead send the key as xi_api_key in the required first JSON message (see the first-message shapes and the standard WebSocket example below).
- Never put a key in a URL (a key in the query string is refused before the upgrade with 403 api_key_in_query), in browser-delivered code, in a mobile app, in logs or in public code. The API is for server-side integrations: browser (CORS) use is not supported.
| Endpoint | Use |
|---|---|
/v1/text-to-speech/{voice_id}/stream-input | One text stream per connection: send text as it arrives, receive audio frames, end with an empty text message. |
/v1/text-to-speech/{voice_id}/multi-stream-input | Up to 5 independent contexts on one connection, each identified by context_id; for voice agents that interrupt or overlap turns. |
Output formats
mp3_44100_128: MP3, 44.1 kHz, 128 kbit/s, mono. The default.pcm_16000: Raw PCM, signed 16-bit little-endian, mono, 16,000 Hz, no header.pcm_24000: Raw PCM, signed 16-bit little-endian, mono, 24,000 Hz, no header. The engine’s own audio, unchanged.ulaw_8000: Raw G.711 μ-law, mono, 8,000 Hz, 1 byte per sample, no header. For telephony.mp3_22050_32: MP3, 22.05 kHz, 32 kbit/s, mono. For low-bandwidth links.pcm_8000: Raw PCM, signed 16-bit little-endian, mono, 8,000 Hz, no header.
Query parameters
output_format | One of mp3_44100_128, pcm_16000, pcm_24000, ulaw_8000, mp3_22050_32, pcm_8000. Default mp3_44100_128. |
model_id | Choose one of voicely-flash-v1, voicely-tts-hd-v1, voicely-tts-classic-pro-v1, voicely-tts-preview-v1, voicely-tts-narration-v1, voicely-tts-narration-lite-v1, voicely-tts-classic-lite-v1. voicely-flash-v1 remains the default. All seven support the transport; HD buffers each generated segment, while the other six use provider streaming. Deprecated external-provider aliases are not accepted on WebSocket. |
language_code | Optional. Locks the language; when omitted it is detected from the first spoken text. |
inactivity_timeout | Seconds without input before an idle session closes. Default 20, minimum 1; larger values are clamped to 180. |
auto_mode | true or false. When true, text is cut at sentence boundaries instead of the chunk schedule. |
sync_alignment | true returns estimated per-segment character timings in alignment and normalizedAlignment on a segment’s last audio frame. They are derived from the exact text and real PCM duration, relative to that segment’s first real sample; they are not provider-native, forced alignment, confidence-scored or precise. false or omitted keeps both fields null. |
enable_logging, apply_text_normalization, seed | Validated and ignored. Named in the X-Voicely-Ignored-Parameters upgrade response header. |
enable_ssml_parsing | false is accepted; true is refused (SSML is not supported). |
Messages you send: stream-input
{"text": " "} | Required first message: exactly one space. It may also carry voice_settings and generation_config. |
{"text": " ", "xi_api_key": "<your key>"} | The same required first message carrying the key, only for server runtimes that cannot set the xi-api-key header. |
{"text": "Hello there. "} | Text to speak. Send it as it arrives; it is buffered and cut into segments at spaces or punctuation once 120 characters are buffered (then 160, 250, 290; change it with generation_config.chunk_length_schedule, values 50 to 500). |
{"text": "…", "flush": true} | Speak everything buffered now, without waiting for more text. |
{"text": "…", "try_trigger_generation": true} | Start speaking once 50 characters are buffered, if a cut point exists. |
{"text": ""} | End of sequence: everything buffered is spoken, then a final frame, then the server closes with 1000. |
Every message is a JSON text frame. Unknown fields are ignored; voice_settings and generation_config can only be set in the first message.
Messages you send: multi-stream-input
{"text": " ", "context_id": "turn-1"} | Required first message (one space), optionally naming the first context. Without context_id the context is called default. |
{"text": " ", "context_id": "turn-1", "xi_api_key": "<your key>"} | The same required first message carrying the key, only for server runtimes that cannot set the xi-api-key header. |
{"text": "Hello. ", "context_id": "turn-1"} | Text for a context. A new context_id opens a new context. |
{"context_id": "turn-1", "flush": true} | Speak that context’s buffered text now. |
{"context_id": "turn-1", "close_context": true} | Finish the context: its buffered text, including an unfinished last sentence, is still spoken, then one final frame for that context. Other contexts are unaffected. Repeating it changes nothing. |
{"close_socket": true} | Finish every open context the same way, then the server closes with 1000. |
{"text": "", "context_id": "turn-1"} | Keeps the context alive without adding text. |
A context_id is 1 to 64 letters, digits or . _ : - characters. Text sent to a context after its close_context is ignored.
Frames you receive
{"audio": "<base64>", "isFinal": null, "normalizedAlignment": null, "alignment": null} | An audio chunk in the requested output_format, base64-encoded. With sync_alignment=true, the last audio frame of a segment may replace both nulls with estimated timing objects containing chars, charStartTimesMs and charDurationsMs. |
{"audio": null, "isFinal": true, "normalizedAlignment": null, "alignment": null} | The final frame: all audio for the sequence (or context) has been sent. Nothing for it follows. |
{"message": "…", "error": "<id>", "code": 1008} | An error. The server then closes the connection with the same code and the message as the reason. |
On multi-stream-input every audio and final frame also carries contextId after these four keys; error frames do not.
- Each context ends with exactly one final frame, and no audio or final frame for a context is ever sent after its final frame.
- Audio frames of a context arrive in order. Contexts share one synthesis stream and a segment being spoken is never cut off: a context that starts while another is closing is spoken next, and the closing context resumes afterwards.
- Only fatal errors cancel speech; close_context and close_socket always finish what was already sent.
Example: two turns on multi-stream-input
→ {"text": " ", "context_id": "turn-1"}
→ {"text": "Here is a long answer about your order. ", "context_id": "turn-1"}
← {"audio": "…", "isFinal": null, "normalizedAlignment": null, "alignment": null, "contextId": "turn-1"}
→ {"context_id": "turn-1", "close_context": true} (the user interrupts)
→ {"text": "Sure, go ahead. ", "context_id": "turn-2", "flush": true}
← {"audio": "…", …, "contextId": "turn-2"} (turn-2 is spoken next)
← {"audio": null, "isFinal": true, …, "contextId": "turn-2"}
← {"audio": "…", …, "contextId": "turn-1"} (turn-1 finishes what it was sent)
← {"audio": null, "isFinal": true, …, "contextId": "turn-1"}
→ {"close_socket": true}
← close 1000Node.js (ws)
// Node 18+ with the "ws" package (npm install ws). Server-side only; never ship the key to a browser.
import WebSocket from "ws";
import { createWriteStream } from "node:fs";
const apiKey = process.env.VOICELY_API_KEY;
if (!apiKey) throw new Error("Set VOICELY_API_KEY in the server environment first.");
const url = "wss://api.tryvoicely.com/v1/text-to-speech/vly_f02/stream-input?output_format=mp3_44100_128";
const ws = new WebSocket(url, { headers: { "xi-api-key": apiKey } });
const out = createWriteStream("speech.mp3");
ws.on("unexpected-response", (_req, res) => { // refused before the upgrade (HTTP status + JSON detail)
console.error("refused:", res.statusCode);
ws.terminate();
});
ws.on("open", () => {
ws.send(JSON.stringify({ text: " " })); // first message: exactly one space
ws.send(JSON.stringify({ text: "Hello from the Voicely WebSocket API. " }));
ws.send(JSON.stringify({ text: "" })); // end of sequence
});
ws.on("message", (data) => {
const msg = JSON.parse(data.toString());
if (msg.error) { console.error(`${msg.error}: ${msg.message}`); return; } // the close that follows has the same code
if (msg.audio) out.write(Buffer.from(msg.audio, "base64"));
if (msg.isFinal) console.log("all audio received");
});
ws.on("close", (code, reason) => { out.end(); console.log("closed", code, reason.toString()); });
ws.on("error", (err) => console.error("connection error:", err.message));Python (websockets)
# Python 3.9+ with websockets 14 or newer (pip install websockets). Server-side only.
import asyncio, base64, json, os
import websockets
URL = "wss://api.tryvoicely.com/v1/text-to-speech/vly_f02/stream-input?output_format=mp3_44100_128"
async def main():
headers = {"xi-api-key": os.environ["VOICELY_API_KEY"]}
try:
async with websockets.connect(URL, additional_headers=headers) as ws:
await ws.send(json.dumps({"text": " "})) # first message: exactly one space
await ws.send(json.dumps({"text": "Hello from the Voicely WebSocket API. "}))
await ws.send(json.dumps({"text": ""})) # end of sequence
with open("speech.mp3", "wb") as out:
async for raw in ws: # ends when the server closes normally
msg = json.loads(raw)
if msg.get("error"):
print(f"{msg['error']}: {msg['message']}")
elif msg.get("audio"):
out.write(base64.b64decode(msg["audio"]))
if msg.get("isFinal"):
print("all audio received")
except websockets.InvalidStatus as e: # refused before the upgrade
print("refused:", e.response.status_code)
except websockets.ConnectionClosedError as e: # closed with an error code
print("closed:", e.rcvd.code if e.rcvd else None, e.rcvd.reason if e.rcvd else "")
asyncio.run(main())Standard WebSocket in a server runtime (key in the first message)
// A server runtime with the standard WebSocket (Node.js 22+, Deno, Bun), whose constructor cannot set headers.
// Server-side only: never run this in a browser or a mobile app. The key comes from the server environment.
const apiKey = process.env.VOICELY_API_KEY;
if (!apiKey) throw new Error("Set VOICELY_API_KEY in the server environment first.");
const url = "wss://api.tryvoicely.com/v1/text-to-speech/vly_f02/stream-input?output_format=mp3_44100_128";
const ws = new WebSocket(url); // no key in the URL, ever
const chunks = [];
ws.onopen = () => {
ws.send(JSON.stringify({ text: " ", xi_api_key: apiKey })); // required first message, carrying the key
ws.send(JSON.stringify({ text: "Hello from a server runtime. " }));
ws.send(JSON.stringify({ text: "" })); // end of sequence
};
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
if (msg.error) { console.error(`${msg.error}: ${msg.message}`); return; }
if (msg.audio) chunks.push(Uint8Array.from(atob(msg.audio), (c) => c.charCodeAt(0)));
if (msg.isFinal) console.log("all audio received");
};
ws.onerror = () => console.error("connection error");
ws.onclose = (event) => console.log("closed", event.code, "bytes", chunks.reduce((n, c) => n + c.length, 0));WebSocket billing
- A session is billed in cumulative 100-character blocks of the text actually spoken, counted the same way as the HTTP API: the running total is rounded up to the next 100. A new block is charged only when the total crosses it, so many short messages are not each rounded up.
- A segment is charged only after its audio was fully generated and every frame of it was sent. If a segment fails, it and every later segment are not charged; segments already charged stay charged, and the session ends with an error.
- The same API wallet as the HTTP API (1 paid Voicely credit = 1000 API characters). If the balance runs out the session ends with insufficient_balance.
- After an explicit flush, close_context or the end of sequence, up to 200 ms of silence can be added so the encoder releases the last audio. It is never billed.
WebSocket limits
- A session lasts at most 15 minutes, speaks at most 20,000 billable characters and at most 200 segments.
- A single run of text with no space or punctuation to cut at may be at most 1,000 characters (segment_too_long).
- Multi-context: at most 5 contexts at once; a context still closing counts until its final frame. Opening one more is refused with context_limit_exceeded. Too much text waiting to be spoken is refused with input_queue_full.
- Per-account request and concurrency limits apply, as on the HTTP API (rate_limit_exceeded, concurrency_limit_exceeded). Per-account speech-request limits can refuse a session with provider_attempt_rate_limited (reconnect shortly) or provider_attempt_limit_exceeded.
- Binary frames, keys in the URL, duplicate query parameters, Bearer authorization and pronunciation dictionaries are refused.
- When the service is at capacity, a new session is refused with service_busy (close code 1013): reconnect after a short wait.
- Public API: limits may change.
Refusals before the upgrade
The connection is not upgraded; the HTTP response carries a JSON detail body.
| Status | Error |
|---|---|
| 403 | api_key_in_query |
| 403 | duplicate_query_parameter |
| 403 | invalid_inactivity_timeout |
| 403 | invalid_model_id |
| 403 | invalid_output_format |
| 403 | invalid_query_parameter |
| 403 | model_not_supported_on_websocket |
| 403 | ssml_not_supported |
| 403 | unsupported_language |
| 403 | voice_not_found |
| 503 | websocket_not_available |
Close codes and error frames
| Close | Meaning | Errors |
|---|---|---|
| 1000 | Normal: end of sequence, close_socket, or an idle session. | none (normal close) |
| 1008 | A problem with the request, the account or a limit. Fix it before reconnecting. | account_suspended, api_key_revoked, auth_timeout, bearer_authorization_not_supported, binary_frame_not_supported, concurrency_limit_exceeded, conflicting_api_keys, context_limit_exceeded, input_message_json_decode_fail, input_queue_full, insufficient_balance, invalid_api_key, invalid_context_id, invalid_generation_config, invalid_initial_message, invalid_message, invalid_voice_settings, message_after_end_of_sequence, missing_api_key, pronunciation_dictionaries_not_supported, provider_attempt_limit_exceeded, rate_limit_exceeded, segment_too_long, session_char_limit_exceeded, session_lifetime_exceeded, session_segment_limit_exceeded, settings_immutable, websocket_not_enabled_for_account |
| 1011 | Speech generation or the server failed. Reconnect to continue. | internal_error, provider_error, session_lease_lost |
| 1012 | The server is restarting. Reconnect. | server_restarting |
| 1013 | Busy or rate limited. Reconnect shortly. | provider_attempt_rate_limited, service_busy |
An idle session closes with 1000 and the reason Session closed after inactivity.
Upgrade response headers
X-Voicely-Session-Id: Identifies the session; quote it when you contact support.X-Voicely-Model: Always voicely-flash-v1.X-Voicely-Model-Alias: The alias you sent in model_id, if any.X-Voicely-Ignored-Parameters: Query parameters that were accepted but had no effect.
ElevenLabs WebSocket clients
- The endpoints, message fields and frame keys follow ElevenLabs’ stream-input and multi-stream-input protocols for the fields documented on this page. It is not a complete or drop-in implementation.
- Change the base URL, use a Voicely key and Voicely voice IDs. Select one of the seven model IDs listed above; each keeps its own routing and language support. voicely-flash-v1 remains the default when omitted. eleven_v3 and eleven_v4 are refused on WebSocket.
- voice_settings is validated but not applied. generation_config.chunk_length_schedule is applied. sync_alignment=true returns estimated per-segment character timings derived from text and real PCM duration. They are not provider-native or forced alignment, carry no confidence value and can differ from spoken word boundaries; false or omitted returns null alignment fields.
- Most error ids and messages are Voicely’s own; only invalid_api_key, input_message_json_decode_fail and invalid_output_format share ElevenLabs’ ids.
- Tested in our own test environment with unmodified LiveKit Agents 1.8.4 (livekit-plugins-elevenlabs 1.8.4) and Pipecat 1.12.0 on multi-stream-input. LiveKit requests sync_alignment by default and consumes the estimated objects, but version 1.8.4 treats timings as context-wide while Voicely restarts them at 0 for each provider segment. Pipecat consumes them when sync_alignment reaches the server, but version 1.12.0 does not send that flag itself. Test timing behavior in your own client before relying on it.
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.mp3Node.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)HTTP 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) andX-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-Balanceis what you can spend right now.GET /v1/user/subscriptionalso 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-Resetgives the reset time (00:00 UTC).
HTTP 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.
Idempotency-Key replay applies to HTTP requests only; it does not replay WebSocket sessions. WebSocket segment billing and partial-session outcomes are described above.
HTTP limits and availability
600 requests per minute and up to 50 concurrent requests per account. These are account limits, not a guarantee of simultaneous service capacity. On 429 wait forRetry-After (60 s for the per-minute limit, 5 s for concurrency).
503 streaming_not_availablemeans HTTP streaming is paused or at capacity. The request is not charged. The buffered endpoint remains a separate transport; clients choose how to handle this refusal.- 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-Afteris 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).- Need higher limits for a production workload? Contact support with your expected requests per minute, concurrent requests, typical text length and launch date. Increases are reviewed and are not guaranteed.
- Proactive rate-limit headers (
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset) are not sent. Read your limits fromGET /v1/user/subscription.
Errors and retries
Errors are JSON: {"detail":{"status","message"},"code","request_id"}. The same diagnostic id is returned in the X-Voicely-Request-Id response header. Record either value when contacting support. 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.
All error codes (69)
The same list is in the OpenAPI spec.
| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 400 | api_key_in_query | A key was sent in the URL. | Revoke that key (URLs end up in logs) and send the new one in the xi-api-key header. |
| 400 | client_aborted | The client closed the connection before the response. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 400 | empty_text | text is blank. | Fix the request; retrying it unchanged will fail again. |
| 400 | invalid_content_type | Content-Type is not application/json. | Send Content-Type: application/json. |
| 400 | invalid_idempotency_key | Idempotency-Key is not 1-128 printable ASCII characters without spaces. | Fix the request; retrying it unchanged will fail again. |
| 400 | invalid_json | The body is not a valid JSON object. | Fix the request; retrying it unchanged will fail again. |
| 400 | invalid_request | The request is malformed. | Fix the request; retrying it unchanged will fail again. |
| 400 | invalid_text | text is not a valid string. | Fix the request; retrying it unchanged will fail again. |
| 400 | missing_text | text is required. | Fix the request; retrying it unchanged will fail again. |
| 401 | invalid_api_key | The key is unknown or malformed. | Check the key; create a new one on the API access page if needed. |
| 401 | missing_api_key | No key in xi-api-key or Authorization: Bearer. | Send your key in the xi-api-key header. |
| 402 | api_spend_limit_reached | Today's paid-credit conversion limit is used up. | Wait for X-Voicely-Spend-Limit-Reset (00:00 UTC) or raise your daily limit, then retry. |
| 402 | insufficient_balance | The spendable balance cannot cover the billed characters. | Buy credits or turn on auto-conversion, then retry (the same Idempotency-Key may be reused). |
| 403 | account_suspended | The API account is suspended. | Contact support (tryvoicely.com/contact). |
| 403 | revoked_api_key | The key was revoked. | Create a new key on the API access page. |
| 404 | voice_not_found | Unknown voice_id. | Use an id from GET /v2/voices or GET /v1/voices. |
| 409 | idempotency_mismatch | The Idempotency-Key was used before with a different payload. | Use a new Idempotency-Key for a different request. |
| 409 | replay_expired | The stored result for this Idempotency-Key has expired. | Send a new request with a new Idempotency-Key (it will be charged). |
| 409 | replay_unavailable | The stored result for this Idempotency-Key cannot be served. | Send a new request with a new Idempotency-Key. |
| 409 | request_in_progress | A request with this Idempotency-Key is still running. | Retry the same request with the same Idempotency-Key after Retry-After. |
| 413 | body_too_large | The request body is too large. | Fix the request; retrying it unchanged will fail again. |
| 413 | text_too_long | text exceeds the per-request character limit. | Split the text into shorter requests. |
| 422 | invalid_apply_language_text_normalization | apply_language_text_normalization must be a boolean. | Fix the request; retrying it unchanged will fail again. |
| 422 | invalid_apply_text_normalization | apply_text_normalization must be auto, on or off. | Fix the request; retrying it unchanged will fail again. |
| 422 | invalid_context_text | previous_text or next_text is invalid or too long. | Fix the request; retrying it unchanged will fail again. |
| 422 | invalid_request_ids | previous_request_ids or next_request_ids is invalid. | Fix the request; retrying it unchanged will fail again. |
| 422 | invalid_seed | seed is not an unsigned 32-bit integer. | Fix the request; retrying it unchanged will fail again. |
| 422 | invalid_voice_settings | voice_settings has an invalid value. | Fix the request; retrying it unchanged will fail again. |
| 422 | invalid_webhook | webhook is not a boolean. | Fix the request; retrying it unchanged will fail again. |
| 422 | provider_input_too_long | The speech engine rejected the input length. | Shorten the text. You were not charged. |
| 422 | provider_rejected_text | The speech engine declined this text. | Change the text; retrying it unchanged will fail again. You were not charged. |
| 422 | provider_unsupported_voice | This voice cannot speak this text/language. | Choose another voice or language_code. You were not charged. |
| 422 | text_not_speakable | Nothing speakable remains after cleanup (e.g. only symbols). | Fix the request; retrying it unchanged will fail again. |
| 422 | unsupported_language | language_code is not a supported Voicely Studio language, locale or documented alias. | Use GET /v1/models or the Languages table in the API reference, then send a listed language_code. |
| 422 | unsupported_model | model_id is not voicely-flash-v1 or an accepted alias. | Fix the request; retrying it unchanged will fail again. |
| 422 | unsupported_output_format | The output_format is not supported. Supported: mp3_44100_128, pcm_24000, pcm_16000, ulaw_8000. | Fix the request; retrying it unchanged will fail again. |
| 422 | unsupported_pronunciation_dictionaries | Pronunciation dictionaries are not supported. | Remove pronunciation_dictionary_locators. |
| 429 | concurrency_limit_exceeded | Another request for this account is still running. | You were not charged. Retry after Retry-After; the same Idempotency-Key may be reused. |
| 429 | rate_limit_exceeded | Too many requests this minute. | You were not charged. Retry after Retry-After; the same Idempotency-Key may be reused. |
| 500 | already_finalized | Defensive internal check (not expected in normal operation). | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | artifact_conflict | The replay audio could not be stored (conflict). Only from /stream, or when retrying an Idempotency-Key first used there. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | artifact_install_failed | The replay audio could not be stored. Only from /stream, or when retrying an Idempotency-Key first used there. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | audio_conversion_failed | The audio could not be encoded. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | audio_validation_failed | The encoded audio failed validation. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | capture_failed | The request could not be finalised. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | internal_error | Unexpected server error. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | replay_store_failed | The audio could not be stored for replay. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | request_interrupted | The request was interrupted before it completed. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 500 | stream_validation_failed | The streamed audio failed final validation. Only from /stream, or when retrying an Idempotency-Key first used there. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_auth_error | Voicely's engine credentials failed (our side). | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_billing_error | Voicely's engine account has a billing problem (our side). | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_error | The speech engine failed. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_incomplete | The speech engine stopped the stream before completing it. Only from /stream, or when retrying an Idempotency-Key first used there. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_invalid_audio | The speech engine returned unusable audio. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_invalid_output | Synthesis produced no valid audio. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_invalid_response | The speech engine returned an unusable response. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_no_final_marker | The speech engine ended the stream without its completion marker. Only from /stream, or when retrying an Idempotency-Key first used there. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | provider_permission_denied | Voicely's engine access was denied (our side). | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 502 | stream_interrupted | The stream was cut off after audio started (engine or encoder failure). Only from /stream, or when retrying an Idempotency-Key first used there. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 503 | api_disabled | The API is switched off. | You were not charged. Retry later with exponential backoff; the same Idempotency-Key may be reused. |
| 503 | capture_failed | The request could not be finalised. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 503 | provider_quota_exceeded | The speech engine quota is exhausted. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 503 | provider_rate_limited | The speech engine is rate limiting us. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 503 | provider_unavailable | Synthesis is temporarily unavailable. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 503 | schema_not_ready | The API is not ready. | You were not charged. Retry later with exponential backoff; the same Idempotency-Key may be reused. |
| 503 | service_busy | Temporarily busy. | You were not charged. Retry after Retry-After; the same Idempotency-Key may be reused. |
| 503 | streaming_not_available | Streaming is paused or at capacity right now. Only from /stream, or when retrying an Idempotency-Key first used there. | You were not charged. Use POST /v1/text-to-speech/{voice_id} (buffered) for this request, and try /stream again later. |
| 504 | provider_timeout | The speech engine did not answer in time. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
| 504 | stream_lifetime_exceeded | The stream exceeded its maximum lifetime. Only from /stream, or when retrying an Idempotency-Key first used there. | You were not charged. Retry after a short backoff with a NEW Idempotency-Key (the old key replays this error). |
Still stuck?
Contact support with the request id (theX-Voicely-Request-Id header or request_id in the error), the approximate UTC time, and the endpoint and HTTP status/code.
Never send your full API key, your Authorization header, or sensitive input text. We never need them.
Voices (30)
Use GET /v1/voices or GET /v2/voices for current voice objects, then check available_for_models. The table below retains the stable stock voice IDs and legacy language reference; expanded model-language discovery comes from GET /v1/models. 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. Descriptions below are shown only where verified; otherwise the tone label is explicitly pending rather than guessed. Test a short sample before choosing a production voice.
| voice_id | Name | Gender | Languages | Style |
|---|---|---|---|---|
vly_f01 | Voicely Female 01 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f02 | Voicely Female 02 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Melodic, warm |
vly_f03 | Voicely Female 03 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f04 | Voicely Female 04 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f05 | Voicely Female 05 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f06 | Voicely Female 06 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f07 | Voicely Female 07 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f08 | Voicely Female 08Urdu voice | female | en, ur, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Warm, friendly |
vly_f09 | Voicely Female 09 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f10 | Voicely Female 10 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Calm, soothing |
vly_f11 | Voicely Female 11 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f12 | Voicely Female 12 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f13 | Voicely Female 13 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_f14 | Voicely Female 14 | female | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Ethereal, soft |
vly_m01 | Voicely Male 01 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m02 | Voicely Male 02 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m03 | Voicely Male 03 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m04 | Voicely Male 04 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m05 | Voicely Male 05Urdu voice | male | en, ur, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Deep, confident |
vly_m06 | Voicely Male 06 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m07 | Voicely Male 07 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Bold, energetic |
vly_m08 | Voicely Male 08 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m09 | Voicely Male 09 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Resonant, authoritative |
vly_m10 | Voicely Male 10 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Playful, light |
vly_m11 | Voicely Male 11 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m12 | Voicely Male 12 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m13 | Voicely Male 13 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m14 | Voicely Male 14 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m15 | Voicely Male 15 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
vly_m16 | Voicely Male 16 | male | en, hi, ar, bn, nl, fr, de, id, it, ja, ko, mr, pl, pt, ro, ru, es, ta, te, th, tr, uk, vi, zh, pa, gu, kn, ml, he, sw | Tone label pending: test a short sample. |
Versioning and changelog
- The /v1 paths (and GET /v2/voices) are the current Public API.
- 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.
- Seven-model API discovery and model-specific language options documented against the deployed service. Legacy default/aliases, voice IDs, billing and transport contracts remain unchanged.
- Language parity: every language available in Voicely Studio (31 languages, 39 locales) is accepted by language_code.
- 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.
- First-class Urdu: Urdu script and Roman Urdu (language_code ur), spoken by vly_f08 and vly_m05.
- Voice discovery: GET /v2/voices (search and paging) and GET /v1/voices/{voice_id}.
- Raw output formats: pcm_24000, pcm_16000 and ulaw_8000.
- HTTP streaming (POST /v1/text-to-speech/{voice_id}/stream) available to every account.
Not currently supported
- Voice cloning or custom voices
- Precise provider-native word timestamps, forced alignment or an HTTP timestamp endpoint
- HTTP output formats other than mp3_44100_128, pcm_24000, pcm_16000, ulaw_8000 (WebSocket formats are listed separately)
- 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.
- Public API: no uptime guarantee; limits and details may change. Use is subject to the Public API Terms shown on the API access page.