Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.playvm9.com/v1. You send POST requests to /v1/audio/speech for speech synthesis. Other endpoints like /v1/voices and /v1/models are also available at this base URL. This structure allows you to use standard HTTP clients or SDKs by pointing them to this domain.
How do I generate an API key?
Sign up on the /get-api-key/ page using Google or email. Your account page displays your single active API key. You can issue a new key at any time, which immediately invalidates the previous one. Keep your key secure as it authenticates all your requests.
Can I use the OpenAI Python SDK?
Yes. The request shape matches the OpenAI speech endpoint. Configure the SDK’s base_url to https://api.playvm9.com/v1 and use your VoiceStack key. This allows you to use official OpenAI SDKs directly without writing custom HTTP logic for basic integration tasks.
What is the maximum input character limit?
The maximum input limit is 4096 characters per request. If your text exceeds this, split it into parts and join the resulting audio files. Spaces and punctuation count toward the character limit. This ensures consistent processing and predictable billing for each synthesis job.
Does the API support websockets?
No. The API does not support websockets or streaming. You send a POST request and receive the complete audio file in the response. There is no real-time partial audio delivery. This synchronous model simplifies integration for batch processing and standard application workflows.
How do I handle rate limit errors?
The limit is 60 requests per minute per key. If you exceed this, implement retry logic with exponential backoff. New accounts start with 10 requests per minute. Monitor your usage via the account dashboard to adjust your request frequency accordingly and avoid service interruptions.
Is SSML supported in the input text?
No. The API does not support SSML. Input is plain text up to 4096 characters. You cannot use SSML tags for pronunciation or prosody control. Use the available voice presets and speed parameters to adjust the audio output characteristics instead.
What happens if I send an invalid voice ID?
The API will return an error response indicating the invalid voice. Valid voices are aria, nova, luna, sage, felix, milo, atlas, and orion. Ensure you check the /v1/voices endpoint for the current list. Invalid IDs prevent synthesis and do not consume credit if handled correctly.
Can I stream the audio response?
No. Streaming is not supported. The API returns the full audio file in the response body after synthesis completes. You must wait for the entire file to be generated and received. This synchronous approach ensures you get a complete, playable audio file.
How do I verify my API key is active?
Make a simple request to any endpoint, such as /v1/voices, using your key in the Authorization header. If the response is successful, the key is active. You can also view your key status and balance directly on the /get-api-key/ account page.
What is the default response format?
The default response format is mp3. You can specify wav, opus, flac, or pcm in the request body. If you omit the response_format field, the API defaults to mp3. This format is widely supported and suitable for most web and mobile applications.
Do I need to install a specific package?
No. You can use any HTTP client library. The official OpenAI SDKs work by changing the base_url. You do not need a proprietary VoiceStack package. Standard libraries like requests, axios, or fetch are sufficient for integrating the API into your application.
How are errors returned in JSON?
Errors are returned as JSON objects with an error message and code. Failed requests are free, and charges are returned if synthesis fails. The response includes details about the error, such as invalid parameters or rate limits, allowing you to handle issues programmatically.
Is there a sandbox environment?
No. There is no separate sandbox environment. The API uses the same production endpoints for testing and live usage. Use your free trial credit or low-volume requests to test integration. The environment is identical, ensuring consistent behavior between development and production.
First request
curl
curl https://api.playvm9.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.playvm9.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.playvm9.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 and Keys
Authentication is handled via a Bearer token passed in the Authorization header. You must include Authorization: Bearer <your_key> with every request to verify your account identity and authorize usage against your balance.
Bearer token format
Your API key is a string starting with tts-. It must be passed exactly as provided in your dashboard without additional prefixes or quotes.
Single active key policy
Each account maintains one active key at a time. The key is displayed on your /get-api-key/ dashboard page alongside your current balance and usage statistics.
Key revocation behavior
You can issue a new key at any time from the dashboard. When a new key is generated, the previous key becomes invalid immediately. Ensure your integration updates before the old key expires if you are rotating credentials.
Endpoint: Speech Synthesis
The core synthesis endpoint accepts text input and returns synthesized audio. It follows the same request shape as the OpenAI speech endpoint, allowing teams to use official SDKs by simply adjusting the base URL. This design simplifies integration for existing voice interface and chatbot applications.
POST /v1/audio/speech
Send a POST request to https://api.playvm9.com/v1/audio/speech. The endpoint processes text up to 4096 characters per request. For longer texts, split the input and join the resulting audio files.
JSON request body structure
The body includes the text input, voice selection, and output format. You can optionally set the language ISO code or adjust the speed between 0.25 and 4.0. The model field accepts either tts-1 or tts-1-hd.
- input: string, max 4096 characters
- voice: one of 8 preset IDs
- model: tts-1 or tts-1-hd
- response_format: mp3, wav, opus, flac, or pcm
Response audio file delivery
The response contains the binary audio data directly. Failed requests return a JSON error object and incur no charge, with the amount returned to your balance. Successful synthesis delivers the audio file ready for playback in your application.
Endpoint: Voices and Models
Retrieve available voice presets, supported languages, and format options via the GET /v1/voices endpoint. This endpoint provides the definitive list of the eight available voice profiles, each capable of speaking any of the 23 supported languages. The response includes metadata necessary for constructing valid synthesis requests, ensuring your application can dynamically select the appropriate voice ID.
GET /v1/voices endpoint
Query this endpoint to discover all available voice options and their associated language support. The response lists each voice preset along with its characteristics, allowing you to map specific voices to your application's needs. Since any voice can speak any supported language, you can reuse the same voice ID across different language contexts by specifying the language parameter in your synthesis requests.
GET /v1/models endpoint
The models endpoint returns the two available synthesis engines: tts-1 and tts-1-hd. Both models utilize the same underlying engine and share identical pricing, allowing you to switch between them without cost implications. Use this endpoint to verify model availability and ensure your integration is compatible with the current API version.
Listing available audio formats
The /v1/voices endpoint also details the supported output formats for synthesis. You can choose from MP3, WAV, OPUS, FLAC, and PCM based on your storage and playback requirements. MP3 is generally preferred for web delivery due to its compression, while WAV and FLAC offer lossless quality for archival or high-fidelity applications.
- MP3: Compressed, widely supported
- WAV: Uncompressed, high quality
- OPUS: Efficient compression
- FLAC: Lossless compression
- PCM: Raw audio data
Request Parameters
The API accepts tts-1 and tts-1-hd models, which use the same engine and pricing. You select the model via the model field in the JSON request body. Both options generate natural-sounding synthetic speech identical in quality, allowing you to choose based on preference without cost variation.
Model selection (tts-1, tts-1-hd)
Choose tts-1 or tts-1-hd based on your preference. Both models deliver the same audio quality and cost $0.01 per 1,000 characters. There is no performance difference between them, so either parameter works identically for your integration.
Input text length limits
Each request supports up to 4,000 characters. Spaces and punctuation count toward this limit. For longer texts, split the input into chunks of 4,096 characters, generate each part, and join the resulting audio files. This ensures consistent processing and avoids truncation errors.
Voice ID selection
Select one of eight preset voices using the voice parameter. Options include female voices like aria and nova, or male voices like felix and atlas. All voices support all 23 listed languages. If unspecified, the system guesses the language from the script.
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
- felix: energetic, promo
- milo: friendly, conversational
Response Formats
The API delivers synthesized audio as a binary response, allowing you to stream or save the file directly to your application. You can specify the desired output format via the response_format parameter to suit your infrastructure needs.
MP3 output support
MP3 is the default and most widely supported format for web players and mobile applications. It provides a good balance between file size and audio quality, making it ideal for most voice interface use cases.
WAV, OPUS, FLAC, PCM options
For lossless quality or specific processing pipelines, choose WAV, FLAC, or raw PCM. OPUS is available for efficient bandwidth usage. All formats are generated from the same engine, ensuring consistent voice character regardless of the container.
Binary audio response handling
The response body contains the raw audio bytes. Ensure your client handles binary data correctly and sets the appropriate Content-Type header based on the requested format. No JSON wrapper is used for the audio content itself.

Rate Limits and Throttling
VoiceStack enforces a standard rate limit of 60 requests per minute per API key. This capacity supports most production workloads, but developers generating long-form audio should account for processing time, as requests are handled sequentially.
60 requests per minute limit
Each active key allows up to 60 synthesis requests within a one-minute window. If you exceed this threshold, subsequent requests receive a 429 Too Many Requests error. Ensure your application implements exponential backoff to handle these responses gracefully without overwhelming the API.
10 requests per minute initial limit
New accounts start with a reduced limit of 10 requests per minute. This initial cap remains in place until you perform your first top-up. Once a USDT (TRC-20) transfer is confirmed, the limit automatically increases to the standard 60 requests per minute.
Queue behavior under load
Requests are processed one after another. During high traffic, your synthesis job may enter a queue, causing slight delays before generation begins. Short phrases typically take a few seconds, while longer texts generate at roughly real-time speed (25 characters per second).
Failed requests do not consume your character allowance and are refunded. However, queued requests still incur processing time once they reach the front of the line.
- Use exponential backoff on 429 errors.
- Split texts >4096 characters into parts.
- Monitor queue depth during peak usage.
Error Handling and Status Codes
When synthesis fails, the API returns a standard HTTP error code (such as 400 or 500). Crucially, failed requests are free; if the engine cannot produce audio, the charge is returned in full, so you are never billed for empty or broken files.
Common HTTP error codes
The API uses standard HTTP status codes to indicate success or failure. A 200 OK response contains the audio binary or JSON metadata. Errors like 401 Unauthorized indicate an invalid or revoked Bearer token, while 400 Bad Request signals malformed JSON or missing required fields like input or voice.
Failed request billing logic
Billing is strictly tied to successful synthesis. If the request fails due to a server error or invalid parameter, the character count is not deducted from your balance. This ensures you only pay for deliverable audio files.
Timeout and queue delays
Requests are processed sequentially. Under heavy load, a request may wait in a queue before synthesis begins. While typical generation is near real-time, short phrases may take a few seconds. If the server does not respond within the expected timeframe, the request may time out, but since it failed, no charge occurs.
OpenAI SDK Compatibility
VoiceStack’s speech endpoint mirrors the OpenAI speech endpoint, allowing you to integrate our service by simply adjusting the base URL. This design choice means existing integrations can switch providers with minimal code changes, leveraging familiar patterns for product teams already comfortable with standard TTS workflows.
Base URL configuration
Set your SDK’s base URL to https://api.playvm9.com/v1. This directs all requests to our infrastructure while maintaining the standard JSON structure expected by OpenAI-compatible clients.
Using official SDKs
You can use the official OpenAI SDKs for Python, Node.js, and other languages. Pass your unique Bearer token via the Authorization header, ensuring the key format remains consistent with our authentication standards.
Field name compatibility
The request body uses identical field names: model, input, voice, response_format, and speed. No custom wrapper objects are required, enabling direct drop-in replacement for existing OpenAI TTS implementations.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Your voice assistant must understand context, not just commands, to feel truly conversational to the user.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriTTS-R corpus (OpenSLR 141)
- FFmpeg documentation
- LibriVox public-domain audiobooks
- openai-node on GitHub
- OpenAI API reference: create speech
- curl documentation
- ISO 639 language codes
- W3C WAI: making audio and video accessible
- LibriTTS-R paper (arXiv 2305.18802)
- Node.js documentation
- TRON developer hub: TRC-20
