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.mp3Python (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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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

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
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
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

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
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.

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.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- OpenAI API reference: create speech
- LibriVox public-domain audiobooks
- Creative Commons Attribution 4.0
- openai-node on GitHub
- LibriTTS-R paper (arXiv 2305.18802)
- IETF RFC 7845: Ogg Opus
- openai-python on GitHub
- Node.js documentation
- LibriTTS-R corpus (OpenSLR 141)
- Python documentation
- W3C WAI: making audio and video accessible
