Public API

Multilingual text-to-speech API for developers

Send text from your server and receive MP3 or raw audio. The Voicely Public API offers buffered HTTP, HTTP audio streaming and WebSocket streaming, with 30 voices, 130+ languages (by model) and self-serve keys.

For Businesses, Teams & Developers

Build speech into your product

Send text from your backend and receive audio through the supported HTTP or streaming workflow. Keep API keys server-side; language, model and wallet requirements are documented separately.

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.

Server-side Public API · 30 voices · MP3 and raw audio output

How the text-to-speech API works

  1. Step 1

    Create a server-side key

    Sign in, accept the Public API Terms and create a key on the API access page. Store it in an environment variable on your server.

  2. Step 2

    Send text, a voice and a model

    POST your text to /v1/text-to-speech/{voice_id} with the xi-api-key header, model_id voicely-flash-v1 and an optional language_code.

  3. Step 3

    Receive an MP3

    The response body is the finished audio (MP3, 44.1 kHz, 128 kbps). Save it or serve it to your users from your backend.

One request, one MP3. Run it on your server with the key in an environment variable:

# 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 and Python versions, every parameter and the full error list are in the Voicely API reference. The machine-readable OpenAPI 3.1 specification describes the HTTP endpoints only; WebSocket protocols are documented in the reference.

What developers build with it

App and product narration

Read out onboarding, lessons, notifications or articles inside your app, generated on your server.

Accessibility and audio publishing

Offer a spoken version of written content in your audience’s language for readers who prefer audio.

Automated content pipelines

Turn scripts from your CMS or batch jobs into MP3 files without anyone opening a studio.

Backend integrations

Call the API from any server language that can send an HTTPS request and store a file.

Text-to-speech API languages and locales

The API covers Urdu, Hindi, English and 130+ languages, depending on model (Voicely Narration covers the widest set), with GA and preview locale designations preserved. Send an ISO code (es) or an exact Studio locale (es-MX). Urdu works in Urdu script, or in Roman Urdu with language_code ur. 30 built-in voices are available; Urdu uses two dedicated voices, one female and one male, and Urdu sent with any other voice ID is read by the dedicated voice of the same gender (the response headers say which voice was used).

Arabic text-to-speech API

Write Arabic text in Arabic script and set language_code explicitly; omitted Arabic-script input is detected as Urdu.

language_code: ar-EG. ar-EG (Generally available).

Prefer no code? Try Arabic text to speech in the browser studio.

Bangla text-to-speech API

Use Bengali script and set language_code explicitly.

language_code: bn-BD. bn-BD (Generally available).

Prefer no code? Try Bangla text to speech in the browser studio.

Chinese Mandarin text-to-speech API

Use Chinese characters and an explicit language_code. Public API spellings for Mandarin are generated from the catalog aliases.

language_code: zh-CN. cmn-CN (Preview), cmn-TW (Preview).

Prefer no code? Try Explore Chinese Mandarin in the language directory.

Dutch text-to-speech API

Write in Dutch and send language_code explicitly.

language_code: nl-NL. nl-NL (Generally available).

Prefer no code? Try Explore Dutch in the language directory.

English text-to-speech API

Choose the English locale that matches your script and audience.

language_code: en-IN. en-IN (Generally available), en-US (Generally available), en-GB (Preview), en-AU (Preview).

Prefer no code? Try English text to speech in the browser studio.

French text-to-speech API

Keep French accents and punctuation; choose the matching regional locale.

language_code: fr-FR. fr-FR (Generally available), fr-CA (Preview).

Prefer no code? Try French text to speech in the browser studio.

German text-to-speech API

Keep German umlauts and punctuation in your script; send language_code explicitly.

language_code: de-DE. de-DE (Generally available).

Prefer no code? Try German text to speech in the browser studio.

Gujarati text-to-speech API

Use Gujarati script and send its language_code explicitly. The catalog marks this language as preview.

language_code: gu-IN. gu-IN (Preview).

Prefer no code? Try Gujarati text to speech in the browser studio.

Hebrew text-to-speech API

Use Hebrew script and set language_code explicitly. The catalog marks this language as preview.

language_code: he-IL. he-IL (Preview).

Prefer no code? Try Explore Hebrew in the language directory.

Hindi text-to-speech API

Use Devanagari for the Hindi script example and set language_code to select Hindi explicitly.

language_code: hi-IN. hi-IN (Generally available).

Prefer no code? Try Hindi text to speech in the browser studio.

Indonesian text-to-speech API

Write in Indonesian and send language_code explicitly rather than relying on Latin-script detection.

language_code: id-ID. id-ID (Generally available).

Prefer no code? Try Indonesian text to speech in the browser studio.

Italian text-to-speech API

Keep Italian accents and punctuation; send language_code explicitly.

language_code: it-IT. it-IT (Generally available).

Prefer no code? Try Italian text to speech in the browser studio.

Japanese text-to-speech API

Use Japanese kanji and kana and send language_code explicitly.

language_code: ja-JP. ja-JP (Generally available).

Prefer no code? Try Japanese text to speech in the browser studio.

Kannada text-to-speech API

Use Kannada script and send language_code explicitly. The catalog marks this language as preview.

language_code: kn-IN. kn-IN (Preview).

Prefer no code? Try Kannada text to speech in the browser studio.

Korean text-to-speech API

Use Korean Hangul and send language_code explicitly.

language_code: ko-KR. ko-KR (Generally available).

Prefer no code? Try Korean text to speech in the browser studio.

Malayalam text-to-speech API

Use Malayalam script and send language_code explicitly. The catalog marks this language as preview.

language_code: ml-IN. ml-IN (Preview).

Prefer no code? Try Malayalam text to speech in the browser studio.

Marathi text-to-speech API

Use Devanagari and set the Marathi language_code explicitly; omitted Devanagari input is detected as Hindi.

language_code: mr-IN. mr-IN (Generally available).

Prefer no code? Try Explore Marathi in the language directory.

Polish text-to-speech API

Keep Polish diacritics and send language_code explicitly.

language_code: pl-PL. pl-PL (Generally available).

Prefer no code? Try Explore Polish in the language directory.

Portuguese text-to-speech API

Keep Portuguese accents and choose the matching regional locale.

language_code: pt-BR. pt-BR (Generally available), pt-PT (Preview).

Prefer no code? Try Portuguese text to speech in the browser studio.

Punjabi text-to-speech API

Use Gurmukhi for the Punjabi locale shown here and send language_code explicitly. The catalog marks it as preview.

language_code: pa-IN. pa-IN (Preview).

Prefer no code? Try Punjabi text to speech in the browser studio.

Romanian text-to-speech API

Keep Romanian diacritics and send language_code explicitly.

language_code: ro-RO. ro-RO (Generally available).

Prefer no code? Try Explore Romanian in the language directory.

Russian text-to-speech API

Use Russian Cyrillic and send language_code explicitly.

language_code: ru-RU. ru-RU (Generally available).

Prefer no code? Try Russian text to speech in the browser studio.

Spanish text-to-speech API

Keep Spanish accents and punctuation; choose the matching regional locale.

language_code: es-ES. es-ES (Generally available), es-MX (Preview), es-419 (Preview).

Prefer no code? Try Spanish text to speech in the browser studio.

Swahili text-to-speech API

Write in Swahili and send language_code explicitly. The catalog marks this language as preview.

language_code: sw-KE. sw-KE (Preview).

Prefer no code? Try Explore Swahili in the language directory.

Tamil text-to-speech API

Use Tamil script and send language_code explicitly.

language_code: ta-IN. ta-IN (Generally available).

Prefer no code? Try Tamil text to speech in the browser studio.

Telugu text-to-speech API

Use Telugu script and send language_code explicitly.

language_code: te-IN. te-IN (Generally available).

Prefer no code? Try Telugu text to speech in the browser studio.

Thai text-to-speech API

Use Thai script and send language_code explicitly.

language_code: th-TH. th-TH (Generally available).

Prefer no code? Try Thai text to speech in the browser studio.

Turkish text-to-speech API

Keep Turkish dotted and dotless letters and send language_code explicitly.

language_code: tr-TR. tr-TR (Generally available).

Prefer no code? Try Turkish text to speech in the browser studio.

Ukrainian text-to-speech API

Use Ukrainian Cyrillic and send language_code explicitly.

language_code: uk-UA. uk-UA (Generally available).

Prefer no code? Try Explore Ukrainian in the language directory.

Urdu text-to-speech API

Use Urdu script, or send Roman Urdu with language_code ur. The API routes Urdu to its dedicated voices.

language_code: ur-PK. ur-PK (Generally available).

Prefer no code? Try Urdu text to speech in the browser studio.

Vietnamese text-to-speech API

Keep Vietnamese tone marks and send language_code explicitly.

language_code: vi-VN. vi-VN (Generally available).

Prefer no code? Try Vietnamese text to speech in the browser studio.

The accepted language codes and locale designations are listed in the API reference.

Using Voicely with Pipecat or LiveKit

Building a voice pipeline with Pipecat or LiveKit? Call Voicely from your backend and pass the returned audio into your pipeline. Use HTTP for a complete text request, or WebSocket streaming when text arrives incrementally. Your application supplies the adapter and manages its conversation and audio transport; this is not a bundled Voicely plugin or an official framework integration.

Read the HTTP audio streaming reference and WebSocket protocol reference for request shapes, audio formats and connection handling.

Text to speech in n8n workflows

Generate audio with the Voicely-maintained n8n community node. Choose HTTP or WebSocket speech generation and pass the completed audio binary to your next workflow step.

Set up the Voicely n8n text-to-speech integration

Moving from another TTS API

The request shape is one many TTS clients already use: an xi-api-key header, POST /v1/text-to-speech/{voice_id} with a JSON body, and GET /v1/voices and GET /v1/models for discovery.

To switch, change the base URL to https://api.tryvoicely.com, use a Voicely key, pick Voicely voice IDs and set model_id to voicely-flash-v1. It is not a drop-in replacement for any other provider: voice IDs, models and some fields differ. HTTP supports mp3_44100_128, pcm_24000, pcm_16000, ulaw_8000; WebSocket supports mp3_44100_128, pcm_16000, pcm_24000, ulaw_8000, mp3_22050_32, pcm_8000. WebSocket access requires completed paid-credit conversion and a funded API wallet; test your client against the reference first.

Comparing tools for creators rather than code? See how Voicely compares with ElevenLabs.

Available transports and features

  • Buffered HTTP: receive a complete audio file.
  • HTTP audio streaming: receive audio while it is generated.
  • WebSocket streaming: send incremental text and receive audio frames.
  • /v1/text-to-speech/{voice_id}/stream-input
  • /v1/text-to-speech/{voice_id}/multi-stream-input
  • WebSocket formats: mp3_44100_128, pcm_16000, pcm_24000, ulaw_8000, mp3_22050_32, pcm_8000
  • GET /v1/models
  • GET /v1/voices
  • GET /v2/voices
  • GET /v1/voices/{voice_id}
  • GET /v1/user
  • GET /v1/user/subscription
  • POST /v1/text-to-speech/{voice_id}
  • POST /v1/text-to-speech/{voice_id}/stream
  • HTTP MP3, raw PCM or G.711 μ-law (mp3_44100_128, pcm_24000, pcm_16000, ulaw_8000), complete or streamed
  • 30 voices · 130+ languages, depending on model (GA and preview)

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

Access requirements

WebSocket streaming requires a funded API wallet and a completed paid credit conversion. Free-trial-only accounts do not unlock it. Keep the key on your server; the API is not for browser or mobile-app use.

Explore the WebSocket text-to-speech API for incremental text and streamed audio.

Limits and availability

HTTP /stream may return 503 streaming_not_available when paused or at capacity. The request is not charged. The buffered endpoint remains a separate transport; clients must choose how to handle the refusal. There is no uptime SLA. Features, limits and response details may change.

Billing and limits in plain language

  • Completed HTTP requests are billed in rounded blocks from your API wallet. A failed HTTP request is not charged. Within the documented replay window, HTTP retries with the same Idempotency-Key and payload replay the stored outcome without a second charge; a running request returns request_in_progress.
  • Purchased Voicely credits cover API usage only if you switch that on, and only up to a daily limit you choose. Website free and trial credits are never used by the API.
  • The API is paid. Request a separate device-verified API trial on the API access page; Free credits are the browser Studio offer.
  • WebSocket usage accumulates across the session. A segment is charged only after its audio was fully generated and every frame was sent. Failed and later segments are not charged; earlier charged segments stay charged. HTTP Idempotency-Key replay does not replay WebSocket sessions.
  • See the billing reference and request limits for technical units and limits.

Your balances and spend setting are on the API access page.

Keep your API key on the server

  • Keep the key on your server, in an environment variable or a secrets manager.
  • Never put it in browser JavaScript, a mobile app or a public repository.
  • Never send it in a URL or query string, and keep it out of logs.
  • If a key is exposed, revoke it on the API access page and create a replacement. Keep replacement keys on your server too.

Getting help

Most errors explain themselves: every error response has a code, and the API reference error table says what to do for each one. If you are still stuck, contact support with the request ID from the response, the time in UTC, the endpoint and the HTTP status. Never send your API key or sensitive text.

Text-to-speech API questions

What is the Voicely text-to-speech API?

It is a server-side API for turning text into speech. Choose a voice and language, then receive a complete audio file, an HTTP audio stream or WebSocket audio frames for your application.

Which languages does the API support?

Urdu, Hindi, English and 130+ languages, depending on model. GET /v1/models lists each model's language codes, and the API reference distinguishes generally available and preview locales.

How many voices are available?

30 built-in voices with stable IDs. GET /v1/voices lists them with their languages.

Can I use the API in a Pipecat or LiveKit application?

Building a voice pipeline with Pipecat or LiveKit? Call Voicely from your backend and pass the returned audio into your pipeline. Use HTTP for a complete text request, or WebSocket streaming when text arrives incrementally. Your application supplies the adapter and manages its conversation and audio transport; this is not a bundled Voicely plugin or an official framework integration.

How many characters can I send in one HTTP request?

Requests have a character limit. Check the limits section of the API reference, and split longer text into separate requests.

What are the HTTP rate limits?

Per-account request and concurrency limits apply. The API reference explains the limits, refusal codes and retry handling.

What audio format does the API return?

MP3 at 44.1 kHz and 128 kbps by default. Raw formats: 16-bit PCM mono at 24 kHz (the engine’s own audio, lossless, skipping the MP3 encoding step) or 16 kHz, and G.711 μ-law at 8 kHz, which is phone-line (narrowband) quality for telephony (mp3_44100_128, pcm_24000, pcm_16000, ulaw_8000). Raw formats have no header. HTTP supports only the listed formats; WebSocket streaming also supports mp3_22050_32, pcm_8000. See the transport-specific lists in the API reference.

Does the API support streaming or WebSockets?

Yes. Buffered HTTP returns a complete audio file; POST /v1/text-to-speech/{voice_id}/stream sends audio while it is generated. A clean HTTP stream end means completed and charged; an errored end is not charged. WebSocket stream-input and multi-stream-input accept incremental text and send audio frames. WebSocket streaming requires a funded API wallet and a completed paid credit conversion. Free-trial-only accounts do not unlock it. Keep the key on your server; the API is not for browser or mobile-app use.

Does the API provide timestamps?

Precise word timestamps and forced alignment are not provided. Use the API reference for supported audio transports and formats; there is no HTTP timestamp endpoint.

Which voices can I use through the Public API?

The Public API offers 30 built-in voices. Use the voice catalog endpoint to choose the voice ID for your request.

Is it compatible with ElevenLabs API clients?

Partly. It uses the xi-api-key header and the POST /v1/text-to-speech/{voice_id} path that many clients know, plus GET /v1/voices and /v1/models. It is not a full replacement: voice IDs, models and several features differ, so test your client against the docs.

Can I call the API from a browser or mobile app?

No. The API is for server-side use only and does not allow browser (CORS) calls. Call it from your backend and pass the audio to your users, so the key never leaves your server.

How is API usage billed?

Completed HTTP requests are billed in rounded blocks from your API wallet. A failed HTTP request is not charged. Within the documented replay window, HTTP retries with the same Idempotency-Key and payload replay the stored outcome without a second charge; a running request returns request_in_progress. Purchased Voicely credits can cover API usage only if you enable conversion. Website free and trial credits are never used by the API. WebSocket usage accumulates across the session. A segment is charged only after its audio was fully generated and every frame was sent. Failed and later segments are not charged; earlier charged segments stay charged. HTTP Idempotency-Key replay does not replay WebSocket sessions. The API reference explains billing units and limits.

Is there a free tier for the API?

There is no ongoing free API tier. A device-verified API trial can be requested on the API access page. It is separate from Studio credits; subsequent API usage is paid from your API wallet or, if enabled, purchased Voicely credits. Free credits are the browser Studio offer.

What service commitment does the API offer?

The Public API has no uptime SLA. Features, limits and response details may change; breaking changes are announced in the developer docs.

Start with the Public API

Sign in, create a key on the API access page, then send your first request from your server.

Not writing code?

Not a developer? Voicely for Android™ gives you Voicely in a phone app, with no code.