Frequently asked questions
How do I set the base_url for the OpenAI Python SDK?
Set base_url to https://api.playvn500.com/v1. This allows the official OpenAI SDKs to work by changing the base_url to your site's API domain. Use your Bearer token for authentication. The request shape matches the OpenAI speech endpoint, ensuring seamless integration into your existing Python workflows without needing custom clients or complex configuration steps.
Can I use the official OpenAI SDK with this API?
Yes. The API mirrors the OpenAI speech endpoint structure, allowing you to use the official OpenAI SDK by simply updating the base_url to https://api.playvn500.com/v1. Authenticate using your SynthCode key. This enables seamless integration with familiar Python libraries for dataset generation without writing custom HTTP clients or handling complex serialization logic manually.
What is the maximum length of text per request?
The API accepts up to 4096 characters per request. For longer texts, split the input into chunks of this size and join the resulting audio files. Note that spaces and punctuation count toward the character limit. This approach ensures consistent processing and allows you to manage large datasets efficiently within the API constraints.
How do I handle audio binary data in Python?
The API returns the audio file directly in the response body. In Python, access this binary data from the SDK response object. Save it to a file or process it further. The response format depends on your specified response_format, such as mp3, wav, opus, flac, or pcm, ensuring compatibility with your storage needs.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key (10 before your first top-up). Under load, requests are processed sequentially and may wait in a queue. Failed requests are free, so you are not charged for retries or failures caused by rate limiting or synthesis errors. We do not guarantee immediate processing during high volume, so plan your dataset generation workflows accordingly.
Is there a WebSocket endpoint for streaming audio?
No. The API returns the complete audio file in the response body; there is no WebSocket endpoint for real-time partial streaming. You must wait for the full synthesis to complete before receiving the data. This design simplifies integration into your data ingestion workflows, though it does not support live streaming use cases.
Do I need to install a specific Python package?
No. SynthCode does not offer an official SDK. Use the standard OpenAI Python library or plain HTTP requests. Configure the base_url to https://api.playvn500.com/v1. The API uses the same request shape as OpenAI, ensuring compatibility with existing Python environments and reducing dependency management overhead for your synthetic speech dataset workflows.
How do I specify a language other than English?
Include the optional language field with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly set the parameter for non-English Latin-script inputs. Supported languages are Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
Can I use multiple voices in one request?
Yes, but each request supports only one voice. To combine voices, send separate requests for each preset (aria, nova, luna, sage, felix, milo, atlas, orion) and join the resulting audio files. This approach ensures consistent quality and simplifies synthesis for each segment within your synthetic speech dataset workflow.
How do I know if a request failed?
Check the HTTP status code for failure indicators. Failed requests are free, and any charge is returned in full. You can verify billing details and character usage via your usage dashboard. Since failed synthesis results in no character deduction, you only pay for successfully generated audio files.
Is the API compatible with Python 3.8+?
Yes, the API works with Python 3.8+. Since the endpoint matches the OpenAI request shape, you can use the official OpenAI SDK or standard HTTP libraries. This enables seamless integration into your data ingestion and model training workflows, ensuring reliable, character-priced synthesis for generating large-scale synthetic speech datasets.
Can I send audio in WAV format?
Yes. Set the response_format field to "wav" in your request body. The API supports mp3, wav, opus, flac, and pcm. This allows you to select the format that best fits your storage and processing requirements for synthetic speech datasets.
How do I revoke my API key?
To revoke your API key, issue a new one from your account dashboard. The new key activates immediately, and the previous key stops at once. You can issue a new key any time. This effectively revokes the old key. Ensure you update your applications with the new key.
Is there a demo endpoint for testing?
No separate demo endpoint exists; use the standard /v1/audio/speech endpoint. Sign up with Google to receive $0.50 in trial credit, valid for seven days. This provides approximately 50,000 characters, allowing you to verify integration and test voice outputs before scaling your synthetic speech dataset workflows.
First request
curl
curl https://api.playvn500.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.playvn500.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.playvn500.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
Access your SynthCode API key by signing in at /get-api-key/. This dashboard displays your active key, current balance, trial status, characters remaining, and a ready curl example for immediate testing. Accounts are created per site via Google or email, ensuring a direct link between your credentials and usage metrics.
The API authenticates requests using a Bearer token. Include your key in the Authorization header as Authorization: Bearer tts-.... Each account maintains one active key. When you generate a new key, the previous one is revoked instantly, ensuring only one active credential exists at any time for security and simplicity.
Generate API key via /get-api-key/ page
Navigate to the /get-api-key/ page to create your account via Google or email. The interface provides immediate access to your unique API key, current balance, trial status, characters left, and a ready curl example. This centralized dashboard ensures you have all necessary credentials and usage data in one place without navigating external portals.
Signing up establishes your account on playvn500.com. The page reflects real-time data, allowing you to monitor consumption directly. No separate billing portal is required; all key management and usage visibility are handled within this single interface, streamlining the setup for your ML data pipelines.
- Sign up via Google or email
- View active key and balance
- Access ready curl example
Use Bearer token in Authorization header
Include your key in the Authorization header using the format Authorization: Bearer tts-.... This standard authentication method works seamlessly with the official OpenAI Python SDK by setting the base_url to https://api.playvn500.com/v1. Ensure the token is passed with every request to the POST /v1/audio/speech endpoint.
This header-based authentication is consistent across all endpoints, including voice and model listings. Using the Bearer token ensures secure access to your account's resources. The token must be included in every request to distinguish your usage from other tenants on the network.
Revoke old keys instantly when issuing new ones
When you generate a new API key from the dashboard, the previous key becomes invalid immediately. This instant revocation ensures that if a key is compromised or rotated, old credentials cannot be used to incur further charges. Only the newly issued key remains active.
This one-key-per-account model simplifies security management. There is no need to track multiple active tokens. If you need a new key, issue it from the dashboard, and the old one stops at once, providing a clean audit trail for your synthetic speech dataset generation workflows.
Base URL and SDK Configuration
The SynthCode API mirrors the standard JSON structure used by major providers, allowing product teams to integrate synthetic speech generation into existing data ingestion pipelines without building custom wrappers. This compatibility is achieved by simply directing your client library to our specific base URL while preserving the familiar request body shape.
Set base_url to https://api.playvn500.com/v1
Configure your client’s base_url to https://api.playvn500.com/v1. This single change directs all synthesis requests to SynthCode’s servers, ensuring that your standard JSON payloads reach the correct engine without requiring code refactoring.
Use official OpenAI Python SDK
You can leverage the official OpenAI Python SDK for this integration. Since the request shape is identical, you do not need to learn a new interface or manage a proprietary client library. This allows your team to maintain a single codebase for both standard and synthetic text-to-speech workflows.
Change endpoint for speech synthesis
By updating the base URL, the SDK’s standard speech endpoint automatically points to SynthCode’s infrastructure. This preserves the standard JSON body structure, enabling seamless handoff of text data from your ingestion pipelines directly to the TTS engine for character-based billing and generation.

Request Parameters
The API accepts a model parameter set to either "tts-1" or "tts-1-hd". Both identifiers utilize the identical synthesis engine and incur the same charge per character, allowing you to switch tiers without altering cost-per-character calculations or billing logic. This uniformity simplifies budgeting for large-scale dataset generation where volume predictability matters more than subtle audio nuances.
Choose the model that best fits your pipeline’s requirements. Since the underlying engine is consistent, the decision rests on specific audio fidelity needs rather than price or speed differences. The API handles the synthesis consistently regardless of the selected model identifier, ensuring stable integration into your data ingestion workflows.
Model: tts-1 or tts-1-hd
The model field accepts "tts-1" or "tts-1-hd". Both options use the same engine and price structure, meaning your cost per character remains constant regardless of your choice. This consistency allows for predictable budgeting when generating thousands of audio samples for machine learning training sets.
Input: text up to 4096 characters
The input field accepts plain text strings up to 4096 characters per request. Longer passages must be split programmatically and the resulting audio files joined. Spaces and punctuation count toward the character limit, so plan your text segmentation accordingly to avoid truncation during dataset creation.
Voice: 8 presets available
Select from eight voice presets: aria, nova, luna, sage, felix, milo, atlas, orion. Each voice supports all 23 languages. For non-English Latin script text, explicitly set the language parameter to ensure accurate pronunciation, as the API defaults to English otherwise. This flexibility supports diverse dataset requirements without needing multiple voice providers.
Voices are derived from licensed recordings, ensuring legal clarity for commercial datasets. Every generated file includes an inaudible watermark identifying it as synthetic speech, which is useful for tracking data provenance in your training pipelines.
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
- felix: energetic, promo
- milo: friendly, conversational
- atlas: neutral, news
- orion: deep, documentary
Response Formats
The API returns audio data directly within the HTTP response body, eliminating the need for polling or managing temporary storage buckets. You receive the synthesized file immediately upon successful synthesis, allowing you to pipe the output straight into your data ingestion pipeline or save it locally with minimal overhead.
Supported: mp3, wav, opus, flac, pcm
Specify your preferred output format using the response_format parameter. We support mp3, wav, opus, flac, and pcm. Choose uncompressed formats like wav or flac for maximum fidelity in ML training datasets, or compressed formats like mp3 and opus to reduce storage costs for large-scale audio corpora.
Audio returned directly in response
Since the audio is returned directly, there is no need for polling or storage management on your end. The response contains the raw binary audio data, enabling seamless integration into automated generation scripts without intermediate database lookups or file retrieval steps.
Handle binary data in Python
Use standard Python libraries to process the binary response. You can write the bytes directly to a file or pass them into audio processing libraries like librosa or soundfile for immediate feature extraction. This direct stream approach keeps your data pipeline fast and efficient for high-volume dataset creation.
Rate Limits and Queuing
SynthCode enforces a rate limit of 60 requests per minute per API key. This limit applies to your key, allowing product teams to scale synthetic speech generation efficiently once their account is funded.
60 requests per minute per key
After topping up, your key supports up to 60 requests per minute. This throughput is designed to handle batch dataset creation without immediate throttling, provided you stay within the per-minute boundary.
10 requests per minute before first top-up
New keys start with a limit of 10 requests per minute. This lower cap persists until your first USDT (TRC-20) top-up is credited. The upgrade to 60 requests per minute occurs automatically once the balance reflects the deposit.
Requests processed sequentially under load
Requests are processed one after another. Under heavy load, a request may wait in a queue before synthesis begins. This sequential handling ensures stable processing but means bursty workloads may experience variable latency depending on current server demand.

Error Handling
Synthesis failures result in a full credit refund, so you are not charged for audio that does not generate. This ensures your cost per successful file remains accurate without hidden penalties for transient processing issues.
Failed requests are free
If synthesis fails, the charge is returned in full. This applies to failed generation attempts, ensuring you only pay for successfully produced audio files.
Check status codes for issues
Monitor the response status to distinguish between valid requests and errors. Standard HTTP codes indicate the state of the synthesis job, allowing your script to log specific failure reasons.
Retry logic for transient errors
Implement exponential backoff for temporary network or server errors. Since requests are processed sequentially under load, brief waits help avoid queue saturation during high-throughput dataset generation.
Language and Voice Selection
Correct language specification ensures accurate synthesis, especially for non-English texts using Latin scripts. While the API guesses language from the script (defaulting to English), explicitly setting the language parameter prevents misinterpretation for languages like Dutch or Norwegian that share Latin characters with English.
Our eight voice presets cover diverse tonal needs for synthetic datasets. Each voice can speak any of the 23 supported languages, allowing flexible dataset generation without retraining models for specific speaker-l combinations.
Set language via ISO code for Latin script
Explicitly passing the language field ensures the TTS engine applies the correct phonetic rules and prosody. Without it, Latin-script text defaults to English pronunciation, which may sound unnatural for languages like Malay or Turkish. Use standard ISO 639-1 codes (e.g., de, fr, ja) to guarantee consistent output across your training data.
This is critical for multilingual datasets where mixed scripts appear. Explicit configuration removes ambiguity and ensures your ML models receive uniformly processed audio samples.
- Use ISO 639-1 codes for clarity
- Prevents default English pronunciation drift
- Ensures consistent phonetic rendering
Voice presets include aria, nova, luna, sage, felix, milo, atlas, orion
Select voices based on your dataset’s target tone. Female voices like aria (warm narrator) or nova (bright, upbeat) suit varied content. Male options include atlas (neutral, news) or orion (deep, documentary). All eight voices support all 23 languages, enabling uniform voice selection across multilingual corpora.
Voices are derived from LibriVox public-domain readings, providing consistent, high-quality synthetic speech. This uniformity helps reduce voice bias in your training data, ensuring your models generalize better across different tonal styles.
- 8 distinct voice presets
- All voices support 23 languages
- Consistent tone for dataset uniformity
Automatic language detection if not specified
If the language field is omitted, the API guesses the language from the input text’s script. Non-Latin scripts (e.g., Cyrillic, CJK) are detected automatically. For Latin script, the default is English. This simplifies API calls but may cause errors for non-English Latin texts like German or Spanish.
For production datasets, explicit language codes are recommended to avoid detection errors. Automatic detection is sufficient for simple, single-language batches where the script clearly indicates the language.
- Defaults to English for Latin text
- Auto-detects non-Latin scripts
- Explicit codes recommended for accuracy

Example Code and Curl
The dashboard on /get-api-key/ provides a ready-to-use curl command with your specific API key, model, voice, and text input pre-filled. This allows immediate verification of the API endpoint and response structure before embedding logic into production pipelines.
Using the requests library, you can send a POST request to the speech endpoint. The response contains binary audio data, which you write directly to a file or pass to a dataset builder. This approach avoids complex SDK dependencies while maintaining full control over payload structure.
Ready curl example in dashboard
The /get-api-key/ page displays a copy-paste curl command containing your unique Bearer token. This example demonstrates the exact JSON payload required for the /v1/audio/speech endpoint, including model, voice, and input fields. Use this to test connectivity and verify audio generation before automating bulk tasks.
- Copy the command directly from the dashboard interface.
- Replace the placeholder text with your actual dataset samples.
- Verify the response returns a binary audio stream.
Python snippet using requests library
Below is a minimal Python script using the standard requests library. It sends the text payload, receives the binary audio response, and saves it to disk. This snippet is suitable for simple generation tasks or as a building block for larger ingestion scripts.
- Install
requestsvia pip if not already present. - Set
Authorization: Bearer your-api-keyin headers. - Write
response.contentdirectly to a.mp3or.wavfile.
Integrate into your data generation script
For large-scale dataset creation, loop through your text corpus. Split texts exceeding 4096 characters into chunks, generate audio for each, and concatenate the resulting files. This method ensures compatibility with your existing data ingestion workflows while leveraging the character-based pricing model for cost efficiency.
- Handle text splitting logic to respect the 4096-character limit.
- Manage rate limits (60 req/min) with appropriate sleep intervals.
- Store generated audio files in your designated dataset directory.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. High quality synthetic speech data enhances the accuracy and naturalness of our machine learning models.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriTTS-R paper (arXiv 2305.18802)
- LibriVox public-domain audiobooks
- FFmpeg documentation
- Creative Commons Attribution 4.0
- Node.js documentation
- Tether (USDT)
- OpenAI API reference: create speech
- ISO 639 language codes
- W3C WAI: making audio and video accessible
- openai-python on GitHub
- IETF RFC 7845: Ogg Opus
