API Documentation for Text-to-Speech Integration

By Vocalix editorial team · Updated 2026-11-18

This documentation provides the technical specifications for integrating Vocalix’s text-to-speech API into voice assistants and conversational bots. It details the request structure, authentication methods, and supported audio formats required for reliable synthesis in automated voice workflows.

Designed for engineering teams, the guide covers SDK compatibility with standard OpenAI libraries, rate limit handling, and error recovery. Use these endpoints to convert text into speech files with predictable latency and consistent volume for large-scale deployments.

API Documentation for Text-to-Speech Integration

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or email and password. Accounts are per site. The dashboard displays your active API key, balance, and usage statistics immediately after registration. You can issue a new key at any time, which invalidates the previous one instantly.

What is the base URL for the API?

The API base URL is https://api.playu77.com/v1. The main endpoint for generating audio is POST https://api.playu77.com/v1/audio/speech. You can also retrieve available voices and models via GET /v1/voices and GET /v1/models respectively.

Does the API support streaming?

No, the API does not support streaming, WebSockets, or real-time partial audio. The endpoint returns the complete audio file in the response after synthesis is finished. You must wait for the full response to receive the audio data.

How do I handle rate limits?

The limit is 60 requests per minute per key, or 10 per minute before the first top-up. Requests are processed sequentially, so under load, a request may wait in a queue. Implement exponential backoff in your client to handle temporary delays gracefully.

What happens if I exceed the request limit?

Requests are processed one after another. If you exceed the limit, your request will wait in the queue until capacity is available. Failed requests are free, but exceeding the rate limit does not incur extra charges; it only introduces latency.

Is there an official SDK?

No, there is no official SDK from Vocalix. You should use the OpenAI SDK or plain HTTP requests. The request shape matches the OpenAI speech endpoint, allowing you to use existing OpenAI libraries by simply changing the base URL.

Can I use the OpenAI Python SDK?

Yes, you can use the official OpenAI SDKs by changing the base URL to https://api.playu77.com/v1 and providing your API key. The request structure is identical to the OpenAI speech endpoint, ensuring compatibility with your existing Python code.

What is the maximum text length per request?

The maximum input text length is 4096 characters per request. For longer texts, split the input into parts of up to 4096 characters, generate audio for each part, and join the resulting audio files to create the final output.

How do I specify the audio format?

Include the response_format field in your JSON body. Supported formats are mp3, wav, opus, flac, and pcm. The API returns the audio file in the requested format within the HTTP response body.

What is the default voice if not specified?

The API does not specify a default voice if the voice field is omitted. You must explicitly select one of the eight available presets (aria, nova, luna, sage, felix, milo, atlas, or orion) in your request. While the language defaults to English if not set, the voice selection remains undefined by the system, requiring your application to handle the selection logic.

Do I need to set the language for English text?

No, for English text, you do not need to set the language. The API guesses the language from the script, and Latin script defaults to English. However, you must set the language field for non-English Latin-script text.

How do I check available voices?

Send a GET request to https://api.playu77.com/v1/voices. This endpoint returns a list of all available voices, their associated languages, supported formats, and pricing details. You can use this information to select the appropriate voice for your text-to-speech generation task.

Is the API synchronous or asynchronous?

The API is synchronous. You send a POST request and wait for the audio file. Requests are processed sequentially, so latency depends on queue length and text size. Typical speed is roughly real-time for long texts, though short phrases take a few seconds. Under load, requests may wait in a queue before processing begins.

How do I revoke my API key?

To revoke your current API key, issue a new key from your dashboard. The old key stops working immediately when the new one is active. You can generate a new key at any time through the account settings page.

First request

curl

curl https://api.playu77.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playu77.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.playu77.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication

Sound wave illustration for: Authentication

Authentication relies on a single Bearer token passed in the Authorization header. This key grants access to all endpoints and tracks usage against your account balance. Generate it immediately after creating your account on /get-api-key/. Keep it secure; anyone with the key can consume your credits.

The system enforces a strict one-active-key-per-account rule. Issuing a new key automatically invalidates the previous one at once. This ensures that if a key is compromised, access is revoked immediately without waiting for a manual review or sleep period.

Bearer token key

Include Authorization: Bearer tts-... in every request header. The token authenticates your identity and links usage to your specific billing account.

The key format is tts- followed by alphanumeric characters. Do not confuse it with API keys from other providers; use only the key issued by playu77.com.

  • Format: Bearer tts-<your_key>
  • Header: Authorization
  • Scope: Full API access

One active key per account

Your account maintains exactly one valid authentication credential at any time. This simplifies credential management for large teams deploying voice assistants.

If you rotate keys frequently, ensure your infrastructure updates the header value immediately to avoid service interruption.

Revoke old keys instantly

Issuing a new key via the dashboard triggers immediate revocation of the old token. No grace period applies.

This feature is critical for security incidents or when decommissioning a specific deployment environment. The old key stops working the moment the new one is active.

Endpoints

Sound wave illustration for: Endpoints

The API exposes three primary endpoints for integration. The core synthesis endpoint accepts text and parameters to generate audio files, while metadata endpoints provide voice details and model information. This structure mirrors standard REST conventions, allowing straightforward integration with existing infrastructure.

Use GET /v1/voices to retrieve available presets, supported languages, formats, and pricing. GET /v1/models lists the engine options. These endpoints ensure your application can dynamically adapt to available resources without hardcoding configuration details.

POST /v1/audio/speech

The primary endpoint for generating audio. Send a JSON body with model, input, voice, response_format, and optional speed or language. The engine returns an audio file directly in the response body, respecting the specified format.

Text is limited to 4096 characters per request. For longer content, split the text and join the resulting audio files. Requests are processed sequentially, so high volume may introduce queue delays.

  • Endpoint: POST https://api.playu77.com/v1/audio/speech
  • Body: JSON with model, input, voice, response_format
  • Output: Audio file in requested format

GET /v1/voices

Returns current voice presets, supported languages, available audio formats, and per-character pricing. This allows clients to validate available options before synthesis. The response includes metadata for the 8 presets and 23 supported languages.

Use this endpoint to dynamically populate UI selectors or validate configuration. Prices and formats are updated centrally, ensuring your application always reflects current capabilities without manual updates.

  • Returns voices, languages, formats, and price
  • Supports 23 languages and 8 voice presets
  • Updates reflect current engine capabilities

GET /v1/models

Lists available TTS models, currently tts-1 and tts-1-hd. Both engines offer identical pricing and voice options, differing only in synthesis quality. Use this to verify model availability before making synthesis requests.

The endpoint ensures compatibility with client-side logic that may need to switch between models based on latency or quality requirements. Both models support all 8 voice presets.

  • Models: tts-1, tts-1-hd
  • Identical pricing and voice support
  • Verify availability before synthesis
Endpoints

Request parameters

Sound wave illustration for: Request parameters

Configure the synthesis engine and input constraints before sending requests. Select the model, define the voice preset, and ensure the input text respects the character limit.

Model selection

Choose between tts-1 and tts-1-hd. Both use the same engine and pricing, offering identical audio quality for standard integration needs.

Input text limit

Each request accepts up to 4096 characters in the input field. For longer scripts, split the text into chunks and join the resulting audio files.

Voice preset selection

Select from 8 presets like nova for upbeat content or atlas for neutral news. Set the language parameter if the script uses non-English Latin scripts to avoid incorrect language guessing.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Response formats

Sound wave illustration for: Response formats

The API accepts MP3, WAV, Opus, FLAC, and PCM as valid values for the response_format field. Clients must explicitly specify the desired format in the JSON body, as no default is assumed. This allows engineering teams to select the optimal codec based on their downstream infrastructure and bandwidth constraints.

MP3

MP3 provides compressed audio suitable for standard playback and storage. It offers a balance between file size and quality, making it ideal for voice assistant responses where bandwidth efficiency matters without sacrificing clarity.

WAV

WAV delivers uncompressed, high-fidelity audio. Use this format when your bot requires lossless quality for processing or when the client device handles large payloads efficiently. It is the safest choice for precise audio analysis.

Opus, FLAC, PCM

Opus offers superior compression for low-latency streaming scenarios. FLAC provides lossless compression for archival needs. PCM returns raw audio data, useful for immediate playback or custom DSP pipelines without decoding overhead.

Rate limits

Sound wave illustration for: Rate limits

Each API key is limited to 60 requests per minute once your account is funded. This capacity is sufficient for most batch processing and moderate-volume voice assistant workflows without requiring complex throttling logic on the client side.

60 requests per minute

The standard rate limit allows 60 requests per minute per active key. This throughput supports steady-state generation for conversational bots and automated voice systems. If you exceed this limit, subsequent requests will return a 429 Too Many Requests error until the window resets.

10 requests before top-up

New accounts start with a 10 requests per minute limit until the first top-up is processed. This lower limit ensures fair usage during the trial period. Once your USDT transfer is confirmed, the limit automatically increases to 60 requests per minute.

Queued processing

Requests are processed sequentially. Under load, a request may wait in a queue before synthesis begins. Long texts are split into 4096-character segments and joined after generation. Typical speed is roughly real-time, but short phrases may take a few seconds due to queueing.

  • Requests are processed one after another
  • Long texts are split into parts
  • Audio files are joined on receipt
Rate limits

Error handling

Sound wave illustration for: Error handling

Synthesis failures are fully refunded. If the engine cannot produce audio, the charge is returned in full. This applies regardless of the failure cause, ensuring you only pay for successful generations. Input validation errors also prevent unnecessary charges, keeping your billing accurate and predictable for high-volume automated voice workflows.

The API uses standard HTTP status codes to indicate success or failure. Use these codes to determine whether to retry or log the issue. Failed requests do not consume your character allowance, preserving your budget for valid synthesis tasks.

Failed requests are free

If synthesis fails, the charge is returned in full. This ensures you only pay for successfully generated audio files, maintaining cost efficiency for large teams processing thousands of requests daily.

HTTP status codes

The API returns standard HTTP status codes to indicate the result of your request. Use these codes to programmatically determine the next step in your automation pipeline.

  • 200: Success, audio file included in response.
  • 400: Bad request, check input format or parameters.
  • 429: Rate limit exceeded, wait before retrying.
  • 500: Internal server error, retry with backoff.

Retry logic

Implement exponential backoff for transient errors. Since requests are processed sequentially, under load a request may wait in a queue. Retry on 500 or 503 errors to handle temporary congestion without overloading the endpoint.

Failed requests due to queue timeouts are rare but result in a full refund if synthesis does not complete.

  • Use exponential backoff for 5xx errors.
  • Retry on 429 after the indicated delay.
  • Failed requests are free, so retrying does not risk double charges.

SDK integration

Sound wave illustration for: SDK integration

The API endpoint mirrors the OpenAI speech structure, allowing teams to leverage existing OpenAI SDKs with minimal configuration changes. This ensures consistent behavior for voice assistant and bot pipelines without requiring custom client wrappers.

OpenAI SDK compatibility

Use the official OpenAI SDK by pointing it to our base URL. The request shape matches the OpenAI speech endpoint exactly, so you can swap the base URL and use your existing integration logic.

  • Compatible with all official OpenAI SDKs
  • Identical JSON request and response shapes
  • No learning curve for existing OpenAI users

Base URL configuration

Set the base_url to https://api.playu77.com/v1 in your SDK client. Include your API key in the Authorization header as Bearer tts-....

  • Base URL: https://api.playu77.com/v1
  • Auth header: Authorization: Bearer tts-...

No custom SDK required

You do not need a proprietary SDK. Standard HTTP libraries or the OpenAI SDK work directly. This reduces dependency overhead for large teams.

SDK integration

Code examples

Sound wave illustration for: Code examples

Below are concrete integration examples for the Vocalix TTS API. All snippets target the standard speech endpoint using the correct base URL for playu77.com.

Ensure your API key is passed as a Bearer token. The examples assume valid credentials and handle the synchronous generation of audio files.

cURL command

Use this command to generate speech directly in your terminal. Replace YOUR_API_KEY with your active key. The request sends a simple text input and specifies the MP3 format, which is one of the supported response formats.

Note that the output file extension is .mp3, not .mp4, matching the API's supported formats.

  • Command: curl -X POST "https://api.playu77.com/v1/audio/speech" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"model\": \"tts-1\", \"input\": \"Hello, this is a test.\", \"voice\": \"nova\", \"response_format\": \"mp3\"}" -o speech.mp3

Python snippet

Install the OpenAI SDK and configure it to use our base URL. This approach leverages the existing library without requiring a custom SDK.

The code below demonstrates a synchronous request. It sends the text payload and saves the resulting audio file locally.

  • ```python import openai client = openai.OpenAI(base_url="https://api.playu77.com/v1", api_key="YOUR_API_KEY") with client.audio.speech.with_streaming_response.create( model="tts-1", voice="nova", input="Integration test complete." ) as response: response.stream_to_file("output.mp3") ```

Node.js example

Use the fetch API or any HTTP client to send the POST request. The JSON body must include the model, voice, and input text.

Handle the binary response data to write the audio file to your filesystem.

  • ```javascript const response = await fetch("https://api.playu77.com/v1/audio/speech", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ model: "tts-1", voice: "nova", input: "Node test" }) }); const buffer = await response.buffer(); ```

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Modern teams now rely on intelligent assistants to streamline workflows and boost overall productivity.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. OpenAI API reference: create speech
  3. LibriVox public-domain audiobooks
  4. Creative Commons Attribution 4.0
  5. openai-node on GitHub
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. IETF RFC 7845: Ogg Opus
  8. openai-python on GitHub
  9. Node.js documentation
  10. LibriTTS-R corpus (OpenSLR 141)
  11. Python documentation
  12. W3C WAI: making audio and video accessible

More on this site