How to Use Python to Generate Synthetic Speech for ML Datasets?

By SynthCode editorial team · Updated 2026-11-18

This guide shows product teams how to generate synthetic speech datasets for machine learning using Python. You will learn to integrate our TTS API into your data ingestion pipelines, handling everything from initial setup to large-scale batch generation. We focus on practical workflows, using the OpenAI SDK for seamless compatibility and character-based pricing that keeps costs predictable.

You will discover how to split long texts, manage rate limits, and select voices for specific languages. The article covers error handling, audio formatting, and processing returned audio files for downstream ML tasks. Whether you are building voice models or expanding training data, this page provides the concrete Python code and API details you need to automate your synthetic audio production.

How to Use Python to Generate Synthetic Speech for ML Datasets?

Frequently asked questions

What Python libraries are needed for TTS integration?

Use the OpenAI Python SDK or standard libraries like requests. Configure the base_url to https://api.playvn500.com/v1. No custom SDK or additional dependencies are required for basic integration. Simply point your client to our API base and use your API key for authentication, ensuring seamless compatibility with existing Python workflows without extra overhead.

How do I split long text into manageable chunks?

Split your input text into parts of up to 4096 characters per request. After generating audio for each chunk, join the resulting audio files to create the final output. This ensures you stay within the character limit while processing longer texts for your synthetic datasets.

Can I use multiprocessing to speed up requests?

Yes. Send multiple requests concurrently via multiprocessing or threading to manage queue wait times. Since requests are processed sequentially under load, parallelism helps reduce latency. Ensure you stay within the 60 requests per minute rate limit per key to avoid throttling.

How do I handle API rate limits in Python?

The limit is 60 requests per minute per key (10 per minute before the first top-up). Implement exponential backoff or a queue in your Python code to respect these limits. Monitor your usage to avoid exceeding the threshold, which may delay processing during high load.

Is the OpenAI SDK required for this API?

No, the OpenAI SDK is not required. You can use any HTTP library like requests or urllib. The API accepts the same JSON body shape as the OpenAI speech endpoint, so you can send POST requests directly to the endpoint using standard Python networking tools.

How do I save audio files in Python?

The API returns the audio file in the response body. Use Python’s open() function to write the response content to a file. Supported formats include mp3, wav, opus, flac, and pcm. Ensure you specify the desired response_format in your request body before saving.

What are the best practices for dataset labeling?

Label your datasets with the voice used, language code, and speed setting. Include metadata like character count and request timestamp for billing. Since generated audio carries an inaudible synthetic watermark, mark files clearly as synthetic speech to distinguish them from human-recorded data in your ML models.

How do I detect language automatically in Python?

The API infers the language from the text script if the language field is omitted, defaulting to English for Latin characters. For non-English Latin text, explicitly set the language parameter. Supported languages include 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 this API for real-time TTS in Python?

No, this API does not support streaming or WebSocket real-time audio. It returns the complete audio file after generation. Typical speed is roughly real-time for long texts, but short phrases take a few seconds. Use it for batch dataset generation rather than live interaction.

How do I troubleshoot API key errors?

Ensure your Authorization header uses the format Bearer tts-.... Check that your key is active; issuing a new key stops the old one immediately. Verify you are using the correct base_url: https://api.playvn500.com/v1. Failed requests are free, so check your balance if charges seem incorrect.

What audio formats are best for ML models?

We support MP3, WAV, Opus, FLAC, and PCM. PCM and WAV provide uncompressed audio, while FLAC offers lossless compression. Our API does not specify which formats are optimal for specific ML models, so select the format that best matches your model’s input requirements and your storage constraints for large synthetic datasets.

How do I monitor my API usage in Python?

Monitor usage via the dashboard at /get-api-key/, which displays your balance, characters left, and usage. Since the API retains request metadata for billing, you can also track consumption programmatically. Costs are calculated at $0.01 per 1,000 characters, allowing you to estimate expenses based on your input text length and remaining credit.

Can I integrate this API with Jupyter Notebooks?

Yes. Use the OpenAI SDK or requests library to send POST requests to https://api.playvn500.com/v1. This workflow is ideal for experimenting with voice presets and testing dataset generation pipelines within notebook cells. Note that the API does not offer streaming, so you must handle the full audio response after each request completes.

How do I handle errors in batch requests?

Check the HTTP status code for each request. If synthesis fails, the charge is returned in full. Implement retry logic for transient errors. Ensure your text is under 4096 characters per request to avoid input errors. Log failures to review and reprocess specific chunks later.

Setting Up Your Python Environment

Sound wave illustration for: Setting Up Your Python Environment

To build synthetic speech datasets for machine learning, start by installing the OpenAI Python SDK. This library simplifies constructing requests and handling responses, ensuring your pipeline uses a standard HTTP client compatible with our API.

Install the OpenAI Python SDK

Install the library via pip. This tool handles request construction and response parsing, integrating seamlessly into your data ingestion workflows without requiring a custom HTTP client implementation.

Configure your API key in environment variables

Retrieve your key from the /get-api-key/ dashboard. Store it in an environment variable, such as OPENAI_API_KEY, to keep credentials secure while allowing your Python scripts to authenticate automatically with https://api.playvn500.com/v1.

Verify connectivity to the API endpoint

Send a minimal POST request to /v1/audio/speech with a short test string. A successful response confirms your environment is correctly configured and ready for large-scale dataset generation.

Making Your First TTS Request

Sound wave illustration for: Making Your First TTS Request

To generate synthetic speech for your ML datasets, you must construct a JSON payload specifying the model, input text, and voice. The API accepts standard TTS parameters, ensuring compatibility with existing Python workflows. You send this data to the speech endpoint, where the engine processes the request and returns the complete audio file.

Construct the JSON body with text and voice

Build your request object with the model (e.g., tts-1), input text (up to 4096 characters), and voice selection. Include optional parameters like response_format and speed. Ensure the text fits the character limit to avoid truncation.

  • Set model to tts-1 or tts-1-hd.
  • Limit input to 4096 characters per request.
  • Choose from 8 voice presets like aria or nova.

Send POST request to /v1/audio/speech

Use the OpenAI Python SDK or a standard HTTP library to send a POST request to https://api.playvn500.com/v1/audio/speech. Authenticate with your Bearer token in the header. The API processes the text and returns the audio file directly in the response body, not as a stream.

  • Endpoint: POST https://api.playvn500.com/v1/audio/speech.
  • Header: Authorization: Bearer tts-....
  • Response contains the complete audio file.

Parse the audio response in Python

Read the response content as binary data and save it to a file or load it into memory. Since the API returns the full file, you can immediately pipe this output into your data ingestion pipelines without waiting for partial chunks. This ensures consistent audio integrity for your training datasets.

  • Save as mp3, wav, opus, flac, or pcm.
  • Write binary data to disk or memory.
  • Verify file integrity before adding to dataset.
Making Your First TTS Request

Handling Long Texts for Datasets

Sound wave illustration for: Handling Long Texts for Datasets

For large-scale ML datasets, text exceeding 4096 characters must be split before synthesis. This API constraint requires processing multiple segments to ensure reliable audio generation without truncation errors.

Each chunk is sent as a separate POST request. Because requests are processed sequentially under load, longer texts may experience queue delays. You should account for this latency when designing your ingestion pipeline.

Split text into 4096-character chunks

Divide your source text into segments of up to 4096 characters. Spaces and punctuation count toward this limit. This ensures every request stays within the API’s boundary for a single synthesis job.

  • Count all characters, including spaces and punctuation.
  • Preserve word boundaries where possible to avoid unnatural pauses.

Generate audio for each chunk separately

Send each chunk to the /v1/audio/speech endpoint. The API returns a distinct audio file for each request. This allows you to handle failures per segment without losing the entire batch.

  • Use the same voice and language parameters for consistency.
  • Failed requests are free, so retry logic is cost-effective.

Concatenate audio files using libraries like pydub

Once all segments are generated, concatenate them into a single file. Libraries like pydub handle this efficiently for formats like MP3 or WAV. This creates a continuous audio track ready for your dataset.

  • Ensure all chunks use the same sample rate and format.
  • Verify silence gaps are minimal to preserve dataset quality.

Optimizing for Large-Scale Generation

Sound wave illustration for: Optimizing for Large-Scale Generation

Generating synthetic speech at scale requires careful management of API constraints. The SynthCode API enforces a limit of 60 requests per minute per key, which directly impacts throughput when building large datasets. Understanding this ceiling is critical for designing efficient pipelines that avoid unnecessary delays or errors during high-volume generation tasks.

Parallel processing allows you to maximize utility within these bounds. By distributing requests across multiple threads or processes, you can approach the per-minute limit more effectively while keeping your generation pipeline moving. This approach ensures consistent data production without overwhelming the server, maintaining stability for your ML workflows.

Batch requests to stay within rate limits

Each account is limited to 60 requests per minute. Before scaling up, ensure your code respects this constraint to prevent request failures. Since requests are processed sequentially under load, batching small segments efficiently helps maintain steady throughput without hitting bottlenecks.

For large texts, split the input into chunks of up to 4096 characters. Generate audio for each chunk separately and concatenate the resulting files later. This method keeps individual requests within size limits while preserving the integrity of the final audio dataset.

  • Limit concurrent requests to 60 per minute per API key
  • Split text into 4096-character segments before sending
  • Queue requests to maintain steady throughput

Use parallel processing for speed

Use Python’s concurrent.futures or asyncio to send multiple TTS requests simultaneously. This approach reduces idle time between requests, significantly accelerating dataset creation. Since each request is independent, parallelization scales linearly up to the rate limit.

Monitor your local queue depth to avoid exceeding the 60 requests per minute limit. Adjust concurrency based on real-time API response times. This ensures you utilize the full capacity of your allowance without triggering errors or excessive wait times.

  • Utilize concurrent.futures for multi-threaded requests
  • Adjust concurrency to match the 60 req/min limit
  • Reduce idle time between generation steps

Monitor character usage for cost control

Pricing is $0.01 per 1,000 characters, including spaces and punctuation. Track character counts before sending requests to predict costs accurately. Failed requests are free, so retrying errors does not incur additional charges, allowing safe experimentation with text inputs.

Check your balance and usage on the /get-api-key/ dashboard. This shows your current balance, trial status, and characters used. Regular monitoring helps prevent unexpected expenses and ensures your dataset generation stays within budget constraints.

  • Count characters including spaces and punctuation
  • Retry failed requests without extra cost
  • Check /get-api-key/ for balance and usage stats

Selecting the Right Voice and Language

Sound wave illustration for: Selecting the Right Voice and Language

Selecting the appropriate voice and language parameters is foundational for building coherent synthetic speech datasets. Your choice of voice preset directly influences the acoustic characteristics of the training data, whether you require the warm, clear narration of Aria or the neutral, news-style delivery of Atlas. Since every voice can speak any of the 23 supported languages, consistency depends on explicit configuration rather than assumption.

The API guesses the language from the script when the language field is omitted, defaulting Latin text to English. For mixed-script or non-English Latin text, you must explicitly set the ISO code to prevent unintended language assignment. This ensures uniform dataset quality across supported languages like Arabic, Chinese, and Swahili without requiring separate voice models for each language.

Choose voices based on dataset requirements

Map voice attributes to your model’s needs. Use Luna for soft, storytelling datasets or Felix for energetic, promotional content. Each of the eight presets offers distinct tonal qualities suitable for different synthetic speech applications.

Test multiple voices to determine which best matches your target domain. The API does not support emotion tags, so rely on the inherent tone of presets like Sage for instructional data or Orion for documentary-style audio.

  • 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

Set language ISO code for consistency

Always specify the language parameter in your Python requests. Relying on script detection can lead to inconsistencies, especially with Latin-script languages other than English. Explicit ISO codes guarantee the intended voice output.

The API supports 23 languages, from Turkish to Swahili. Any voice can speak any supported language, allowing you to maintain a single voice preset across diverse linguistic datasets.

Test different voices for audio quality

Generate short samples using the OpenAI Python SDK to evaluate clarity and naturalness. Check for artifacts in the audio files before committing to large-scale generation. Remember that generated files carry an inaudible watermark marking them as synthetic speech, which is useful for dataset identification.

Use the GET /v1/voices endpoint to review available options. Adjust the speed parameter between 0.25 and 4.0 if necessary, though typical generation speed is roughly real-time for long texts.

Error Handling and Retries

Sound wave illustration for: Error Handling and Retries

Robust error handling ensures your synthetic speech pipeline remains stable during large-scale data generation. By catching specific exceptions, you can distinguish between transient network issues and permanent failures, allowing your script to continue processing without manual intervention.

Proper logging provides the visibility needed to debug pipeline issues quickly. Tracking errors helps you identify patterns, such as consistent failures with specific voices or language codes, enabling proactive adjustments to your generation strategy.

Catch exceptions in Python requests

Use try-except blocks to capture HTTPError and ConnectionError exceptions. This allows your code to distinguish between server-side errors (like 500 or 429) and network timeouts. Handling these gracefully prevents your entire dataset generation job from crashing on a single failed request.

  • Import requests or use the OpenAI SDK's built-in error classes
  • Catch ConnectionError for network instability
  • Catch HTTPError for API status codes like 429 (Rate Limit) or 500 (Server Error)

Retry failed requests without penalty

Since failed synthesis requests are free, you can safely retry them without incurring extra costs. Implement a retry logic with exponential backoff to handle temporary rate limits or server hiccups. This ensures that no audio segment is lost due to transient issues, maintaining the integrity of your dataset.

  • Retry on 429 Too Many Requests after a short delay
  • Retry on 500 Internal Server Error
  • No extra charge for retried requests that ultimately fail

Log errors for debugging pipelines

Maintain a detailed log of all errors, including the text chunk, voice, and error type. This metadata is crucial for auditing your dataset quality and identifying systemic issues, such as a voice failing consistently with specific character combinations. Use these logs to refine your splitting logic or voice selection.

  • Log timestamp, text snippet, voice, and error code
  • Store logs in a structured format (JSON/CSV) for easy analysis
  • Monitor error rates per voice or language to detect issues early

Storing and Managing Generated Audio

Sound wave illustration for: Storing and Managing Generated Audio

Synthetic speech datasets require structured storage to maintain integrity during ML training. Save generated audio in formats like WAV or FLAC for lossless quality, or MP3 and Opus to reduce storage overhead while preserving sufficient fidelity for model ingestion.

Save audio files in supported formats

Choose your response format based on downstream needs. FLAC and WAV ensure no compression artifacts, ideal for high-fidelity training. MP3 and Opus offer significant space savings for large-scale datasets without compromising usable signal quality.

  • FLAC/WAV: Lossless, best for precise acoustic modeling.
  • MP3/Opus: Compressed, optimal for storage efficiency.
  • PCM: Raw data for low-level preprocessing.

Organize data by language and voice

Structure your directory hierarchy by language ISO codes and voice presets. This separation simplifies dataset splitting and ensures consistent acoustic characteristics across training and validation sets. Grouping by voice helps in ablation studies or domain-specific fine-tuning.

  • Create folders for each voice (e.g., 'aria', 'atlas').
  • Subdivide by language (e.g., 'en', 'de', 'fr').
  • Maintain consistent naming conventions for easy retrieval.

Track metadata for dataset labeling

Record request metadata including timestamp, character count, and voice ID. This information is crucial for dataset labeling and debugging. Since generated audio is not stored server-side, local metadata ensures you can reconstruct the generation context without relying on external logs.

  • Log voice preset used (e.g., 'nova', 'milo').
  • Record input text length and language code.
  • Store generation timestamp for reproducibility.
Storing and Managing Generated Audio

Scaling Your Data Generation Pipeline

Sound wave illustration for: Scaling Your Data Generation Pipeline

Scaling your data generation pipeline requires automating the repetitive nature of synthetic speech creation. By leveraging standard tools like cron jobs, you can schedule batch processing tasks that run at set intervals, ensuring a steady flow of audio files without manual intervention. This approach fits seamlessly into existing data ingestion pipelines, allowing your team to focus on model architecture rather than file management.

Automate generation with cron jobs

Use your operating system’s cron scheduler to trigger Python scripts that query your text corpus and send requests to the TTS API. Configure these jobs to run during off-peak hours to manage queue times effectively. Since requests are processed sequentially, staggering your cron jobs can help maintain consistent throughput without overwhelming the 60 requests per minute limit.

  • Use Linux cron or Windows Task Scheduler to trigger Python scripts at set intervals.
  • Stagger job start times to manage queue wait times during high load.
  • Script should handle text splitting and audio concatenation automatically.

Integrate with your ML training workflow

Once generated, the audio files can be directly fed into your data loader. Ensure your pipeline logs the metadata—such as voice, speed, and language—alongside the audio file. This metadata is crucial for labeling your dataset accurately, allowing you to train models on specific voice characteristics or language variants without manual sorting.

Store the generated WAV or MP3 files in your designated data bucket. Since the API returns audio directly in the response, your script should write the binary data to disk immediately after receiving the HTTP 200 response, minimizing memory usage during large-scale generation.

  • Log voice, speed, and language settings with each audio file for dataset labeling.
  • Write binary audio data to disk immediately after receiving the HTTP response.
  • Ensure filenames reflect the voice and language used for easy identification.

Monitor API usage and costs

Track your character consumption and balance directly from the /get-api-key/ dashboard. Since each request costs $0.01 per 1,000 characters, monitoring usage helps you predict costs for larger datasets. The dashboard provides real-time data on characters left, trial status, and total usage, allowing you to adjust batch sizes accordingly.

Unlike other services, there are no monthly plans or subscriptions, so you only pay for what you use. Regularly check your balance to ensure sufficient USDT credit is available via TRC-20 transfers to avoid interruptions in your automated pipeline.

  • Check balance and character usage on the /get-api-key/ dashboard.
  • Pay only for characters generated at $0.01 per 1,000 characters.
  • Top up with USDT (TRC-20) to maintain continuous operation.

Troubleshooting Common Issues

Sound wave illustration for: Troubleshooting Common Issues

Even robust pipelines encounter hiccups. Addressing API key misconfigurations, rate limit bottlenecks, and language detection failures early prevents silent data corruption in your synthetic speech datasets.

Fix API key errors

Ensure your Authorization: Bearer header matches the key issued on your dashboard. If you rotate keys, the old one stops immediately, so update your environment variables promptly.

  • Verify key format starts with tts-
  • Check for trailing whitespace in environment variables

Resolve rate limit issues

The API enforces 60 requests per minute per key. New accounts start with a 10 requests/minute limit until the first top-up. Use parallel processing carefully to avoid hitting these caps, which can delay dataset generation.

Failed requests do not consume your character balance, allowing safe retries without cost penalties.

  • Monitor usage via the dashboard
  • Implement exponential backoff for retries

Debug language detection problems

If language is omitted, the API guesses based on script, defaulting to English for Latin text. This causes errors for non-English Latin-script inputs.

Unsupported languages like Vietnamese, Thai, or Ukrainian will fail silently or produce poor results if not explicitly handled. Always set the ISO code for consistency.

  • Explicitly set language for Latin-script non-English text
  • Verify support list: 23 languages only

Best Practices for Synthetic Data

Sound wave illustration for: Best Practices for Synthetic Data

Synthetic speech for machine learning requires consistent acoustic properties. Our API generates files with an inaudible watermark to clearly identify them as synthetic, which is crucial for dataset labeling and preventing data leakage during model training.

Ensure audio quality matches ML requirements

Since the API processes requests sequentially, generation speed varies with load. For large-scale datasets, use parallel processing to maintain throughput. Generate audio in formats like WAV or FLAC to preserve fidelity for your models.

Use watermarked audio for identification

Every generated file carries an inaudible watermark marking it as synthetic speech. This allows you to filter synthetic data from human recordings during training or validation phases without altering the audio content.

Document voice and language settings

Record the voice preset and language ISO code for each audio file. Consistent metadata ensures reproducibility. Since voices can speak any of the 23 supported languages, explicit language setting prevents detection errors.

Integrating with Existing ML Frameworks

Sound wave illustration for: Integrating with Existing ML Frameworks

Once your synthetic speech dataset is generated, integrating it into machine learning pipelines requires standard preprocessing to match framework expectations. Tools like TensorFlow and PyTorch expect audio tensors with consistent sampling rates and channel configurations. Since SynthCode returns complete audio files rather than streaming partial chunks, you download the full response body into memory buffers before feeding them into your model’s data loaders.

Proper preprocessing ensures your model receives uniform inputs. Convert the returned formats (mp3, wav, opus, flac, or pcm) into the specific tensor shape required by your training script, handling sample rate normalization and normalization of audio amplitude values as needed for your architecture.

Use generated audio in TensorFlow or PyTorch

Integrate the generated audio files directly into your training loops. Load the binary audio data into tensors, ensuring the data pipeline handles the file formats returned by the API without loss of fidelity. Use standard audio libraries to decode the files into numerical arrays compatible with TensorFlow’s tf.data or PyTorch’s DataLoader.

  • Load audio bytes into memory buffers
  • Decode into numerical tensors
  • Integrate into tf.data or DataLoader pipelines

Preprocess audio for model input

Ensure all audio samples share consistent properties before training. Normalize volume levels and convert all files to a single format supported by your framework. While specific sample rates vary by format, standardize your preprocessing pipeline to handle the raw output from the API consistently.

  • Standardize audio formats (wav, pcm, etc.)
  • Normalize amplitude levels
  • Handle channel conversions (mono/stereo)

Validate dataset integrity

Verify that generated clips match their text inputs and metadata. Use the inaudible watermark present in every file to distinguish synthetic samples from real recordings in your dataset, ensuring accurate labeling during evaluation. Check that audio length correlates with text length to detect truncation errors.

  • Verify text-audio alignment
  • Use watermarks for synthetic identification
  • Check audio length vs. text length
Integrating with Existing ML Frameworks

Next Steps for Your Project

Sound wave illustration for: Next Steps for Your Project

With your pipeline running, you can refine your dataset structure and begin integration with your primary ML frameworks. Use the generated audio files directly in TensorFlow or PyTorch, ensuring your preprocessing steps align with the specific voice and language settings documented during generation.

Leverage the non-expiring balance to iterate on your model training without worrying about temporary credits. The character-based pricing ensures predictable costs as you scale from prototype to production-grade synthetic speech datasets.

Explore advanced voice options

Test all eight voices to find the best fit for your model’s tonal requirements. Each voice offers distinct characteristics, from warm narrators to energetic promo styles, allowing you to diversify your training data and improve model robustness.

  • Try Aria for clear narration
  • Use Felix for energetic segments
  • Test Atlas for neutral news tone

Try different audio formats

Switch between MP3, WAV, Opus, FLAC, or PCM based on your model’s input needs. FLAC offers lossless quality for high-fidelity training, while MP3 reduces storage costs for large-scale datasets without significant quality loss.

  • Use FLAC for lossless training
  • Choose MP3 for storage efficiency
  • Select WAV for broad compatibility

Scale up your data generation

With a balance that does not expire and pricing at $0.01 per 1,000 characters, you can generate millions of characters efficiently. Automate your workflow using cron jobs or CI/CD pipelines to continuously feed your ML models with fresh synthetic data.

  • Automate with cron jobs
  • Monitor usage via the dashboard
  • Integrate directly into training loops

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.

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. MDN: Web Speech API
  3. IETF RFC 7845: Ogg Opus
  4. openai-node on GitHub
  5. Python documentation
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. W3C WAI: making audio and video accessible
  8. Creative Commons Attribution 4.0
  9. FFmpeg documentation
  10. openai-python on GitHub
  11. Tether (USDT)
  12. Node.js documentation

More on this site