Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or email. Accounts are per site. The dashboard displays your active key, balance, and usage. You can issue a new key at any time; the old one stops immediately. Failed requests are free, and a $0.50 trial credit is available for Google sign-ins.
Can I use the OpenAI Python SDK?
Yes. The API uses the same request shape as the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base URL to https://api.vd89.info/v1 and providing your VoxyData key. This allows seamless integration into existing Python workflows without needing a custom client library.
What is the base URL for the API?
The API base URL is https://api.vd89.info/v1. You send POST requests to https://api.vd89.info/v1/audio/speech for generation. Other endpoints like /v1/voices and /v1/models are also accessible under this base path. Ensure your SDK or HTTP client points to this domain for correct routing.
How do I specify the voice in the request?
Include the voice field in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. You can also optionally set the language field using an ISO code to ensure correct pronunciation, especially for non-English Latin-script text.
What happens if the text is too long?
The API accepts up to 4096 characters per request. For longer texts, split the input into parts of this size. You must then join the resulting audio files client-side. This ensures consistent quality and avoids truncation, allowing you to generate full-length content efficiently.
Can I request multiple audio formats?
Yes. Specify the response_format field in your request body. Supported formats include mp3, wav, opus, flac, and pcm. You can choose the format that best suits your dataset needs, whether for compression or high-fidelity storage, directly within the same API call.
Is the API key reused or rotated?
You have one active key per account. You can issue a new key at any time via the dashboard. When you do, the old key stops working immediately. This allows you to rotate credentials without downtime, ensuring secure access to your synthetic audio generation services.
How do I handle rate limit errors?
The limit is 60 requests per minute per key (10 before the first top-up). Requests are processed sequentially, so under load, they may queue. Implement exponential backoff in your client to handle 429 errors gracefully. Monitor your usage dashboard to stay within limits.
What is the maximum characters per request?
The maximum input size is 4096 characters per request. Spaces and punctuation count toward this limit. If your text exceeds this, split it into smaller chunks. Each chunk generates a separate audio file that you can concatenate later to form the complete audio asset.
Do I need to install a specific SDK?
No. You can use plain HTTP requests or the official OpenAI SDKs. There is no proprietary VoxyData SDK. Simply configure your HTTP client or SDK to point to our base URL and use standard JSON bodies. This keeps your dependencies minimal and flexible.
How do I verify the API is working?
Send a simple POST request to /v1/audio/speech with a short text and a valid voice. Check the response for the audio file or status code. You can also use the ready curl example provided on the /get-api-key/ dashboard to test connectivity and authentication quickly.
Can I use the API with JavaScript?
Yes. Use the fetch API or any HTTP library to send POST requests to the speech endpoint. Provide the JSON body with model, input, voice, and response_format. The OpenAI JavaScript SDK also works by setting the base URL to our API domain.
What is the response format for errors?
Errors return standard HTTP status codes (e.g., 400, 401, 429, 500) with a JSON body detailing the issue. Failed synthesis requests are free. Check the response body for specific error messages to debug issues with your request parameters.
Is the audio returned as a file or base64?
The response contains the audio file directly in the body. The format matches the response_format you requested (mp3, wav, etc.). Your client should handle the binary data or stream it directly to storage or playback.
First request
curl
curl https://api.vd89.info/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.vd89.info/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.vd89.info/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
Access the VoxyData TTS API using a single active API key issued to your account. This key authenticates all requests and tracks your usage against your character-based billing. You can generate a new key at any time via the dashboard, which immediately invalidates the previous one.
Secure your key and treat it like a password. It provides full access to your account’s balance and generation capabilities.
API key usage
Include your API key in the HTTP header of every request. The API validates the key before processing synthesis, ensuring only authorized accounts can generate audio files.
Keys are tied to your specific account on vd89.info. If you create multiple accounts, each has its own independent key and balance.
- Use one key per account for simplicity.
- Keys do not expire automatically.
- One active key allows up to 60 requests per minute.
Bearer token format
Format your authentication header as Authorization: Bearer tts-<your-key>. Replace <your-key> with the string provided in your dashboard.
Ensure there are no extra spaces or line breaks in the token value to avoid 401 Unauthorized errors.
- Prefix:
Bearer - Starts with
tts- - Case-sensitive
Key management
Rotate your key anytime from the /get-api-key/ page. The old key stops working immediately upon generation of the new one.
If you suspect a leak, revoke and regenerate without losing your existing balance or usage history.
- Instant invalidation of old keys.
- No downtime during rotation.
- Support via email only.
Endpoints
VoxyData provides a straightforward REST API for generating synthetic audio datasets. The core endpoint handles text-to-speech conversion, while auxiliary endpoints allow you to inspect available voices and model details programmatically.
Speech generation
Send a POST request to /v1/audio/speech with your input text and voice selection. The API returns an audio file directly in the response body, optimized for immediate ingestion into your ML pipelines.
Voice listing
Use GET /v1/voices to retrieve a list of all 8 available voice presets, their associated languages, and supported audio formats. This helps you programmatically select the right voice for each dataset category.
Model info
Query GET /v1/models to confirm the available model IDs (tts-1 and tts-1-hd). Both models use the same engine and pricing, allowing you to standardize your requests without managing separate model configurations.
Request parameters
The API accepts plain text strings up to 4096 characters per request. Spaces, punctuation, and special characters all count toward this limit. For longer content, split your text into chunks and join the resulting audio files afterward.
You can adjust the playback speed between 0.25x and 4.0x. This allows you to fine-tune the pacing of synthetic speech for dataset consistency without re-generating audio.
Input text limits
Send up to 4096 characters per request. Every space and punctuation mark counts. For longer texts, split into parts and join the audio files. Short phrases take a few seconds; long texts generate at roughly real-time speed.
- Maximum 4096 characters per request
- Spaces and punctuation count as characters
- Split and join for longer texts
Voice selection
Choose from 8 presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narration to energetic promo. All voices support all 23 languages.
Select the voice ID in the voice field. The system does not support custom voice cloning or emotion tags.
- 8 presets: aria, nova, luna, sage, felix, milo, atlas, orion
- Consistent quality for dataset generation
- No custom voice cloning
Language codes
Pass an ISO language code (e.g., en, de, ja) to the language field. If omitted, the system guesses the language from the script. Latin text defaults to English.
Set language explicitly for non-English Latin-script text to ensure correct pronunciation. Supported languages include Arabic, Chinese, French, German, Hindi, Japanese, Korean, Spanish, and more.
- Use ISO codes like
en,de,ja - Defaults to English for Latin script
- Set explicitly for non-English Latin text
Response formats
The API returns synthesized audio as the primary response body, with the format determined by your response_format parameter. This design allows ML engineers to seamlessly integrate generated speech into dataset pipelines without additional conversion steps.
For dataset generation, you can choose from mp3, wav, opus, flac, or pcm. Each generated file includes an inaudible watermark to identify it as synthetic speech, ensuring transparency for downstream model training and copyright verification.
Audio formats
Select your preferred output format via the response_format field. We support mp3, wav, opus, flac, and pcm to suit various storage and processing needs.
All outputs are single-file responses containing the complete audio segment for the processed text chunk.
- mp3: Compressed, widely compatible
- wav: Lossless, standard for ML training
- opus: High efficiency, small file size
- flac: Lossless compression
- pcm: Raw uncompressed audio
JSON responses
Standard endpoints like /v1/voices and /v1/models return JSON objects detailing available voices, languages, and supported formats.
The speech endpoint returns the audio binary directly, so JSON metadata is not included in the body for speech requests.
Error handling
Errors return standard HTTP status codes with a JSON body describing the issue, such as invalid characters or rate limits.
Failed synthesis requests are free, but the API returns standard HTTP error codes (e.g., 4xx or 5xx) rather than a 2xx status.
OpenAI SDK integration
VoxyData’s API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI client libraries with minimal changes. By simply updating the base URL, you can integrate synthetic voice generation directly into your ML data pipelines without writing custom HTTP parsers.
This compatibility ensures that teams already familiar with OpenAI’s SDK can start generating datasets immediately, reducing integration friction and accelerating prototyping cycles.
Base URL configuration
Point your OpenAI SDK client to https://api.vd89.info/v1 instead of the default OpenAI endpoint. Pass your VoxyData API key in the Authorization header as Bearer <key>. This single configuration change redirects all standard speech requests to VoxyData’s infrastructure.
Ensure your SDK version supports the audio/speech endpoint structure. The request body remains identical to the OpenAI format, using fields like model, input, voice, and response_format.
SDK compatibility
The official OpenAI Python and Node.js SDKs work out-of-the-box. No custom wrappers or proprietary libraries are required. This leverages the exact JSON schema VoxyData expects, ensuring consistent parameter handling.
Since the API follows the same shape, you can swap between OpenAI and VoxyData endpoints seamlessly. This is ideal for A/B testing voice quality or scaling dataset generation without rewriting core logic.
Code examples
```python import openai client = openai.OpenAI( base_url="https://api.vd89.info/v1", api_key="tts-your-api-key" ) audio = client.audio.speech.create( model="tts-1", voice="nova", input="Generate synthetic data for voice models.", response_format="mp3" ) with open("output.mp3", "wb") as f: f.write(audio.content) ```
This snippet demonstrates how to generate an MP3 file using the Python SDK. The base_url change directs requests to VoxyData. The response content is written directly to a file, ready for dataset ingestion.

Curl example
The API accepts standard JSON payloads and returns binary audio data directly in the response body. This makes it easy to integrate into existing pipelines without complex parsing logic. You can test the endpoint immediately using any command-line tool that supports HTTP requests.
Below is a minimal example demonstrating how to send a text-to-speech request and save the resulting audio file to your local disk. This approach works for both quick tests and automated dataset generation workflows.
Basic request
Send a POST request to the speech endpoint with your authentication header and the desired text payload. The API processes the input and returns the audio file in the requested format.
```bash curl -X POST https://api.vd89.info/v1/audio/speech \ -H "Authorization: Bearer tts-your-api-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "nova"}' \ -o output.mp3 ```
Parameters included
The JSON body requires the model, input, and voice fields. You can optionally specify response_format, speed, and language. Ensure the text does not exceed 4096 characters.
The example above uses the nova voice with the tts-1 model. You can adjust the speed parameter between 0.25 and 4.0 to suit your dataset needs.
Output handling
The API returns the audio file directly in the response body. Use the -o flag with curl to save the output to a file. If the request fails, you will receive a JSON error object instead of audio data.
Check the HTTP status code to confirm success. A 200 OK status indicates the audio was generated successfully. Use tools like ffprobe to verify the file format and duration.
Rate limits
To ensure stable dataset generation pipelines, VoxyData enforces strict rate limits on API requests. Understanding these boundaries helps product teams and ML engineers avoid interruptions during high-volume synthetic audio production.
Requests per minute
Each API key is limited to 60 requests per minute. Before your first top-up, this limit is reduced to 10 requests per minute to prevent abuse during the trial phase.
Throttling behavior
Requests are processed one after another, so under load a request may wait in a queue. This ensures consistent voice quality but can introduce latency during peak usage periods.
Retry logic
Implement exponential backoff in your ingestion scripts. If you hit the rate limit, wait briefly before retrying. Failed synthesis requests do not consume your character credit, so retrying is safe.
- Use exponential backoff for robustness.
- Retry failed requests without character loss.
- Monitor response headers for limit info.
Error codes
Synthetic speech generation relies on clear input and valid parameters. When requests fail, the API returns specific JSON errors to help you adjust your payload or retry efficiently.
Common errors
Most failures stem from exceeding the 4,096-character limit per request or using an invalid voice ID. Ensure your text fits the constraint and your Authorization header contains a valid tts-... key.
- Input text exceeds 4,096 characters
- Invalid voice or model identifier
- Missing or malformed Authorization header
HTTP status codes
The API uses standard HTTP codes to indicate success or failure. A 200 OK means audio is ready. Use 400 for bad requests, 401 for auth issues, and 429 for rate limits.
- 200: Success
- 400: Bad Request
- 401: Unauthorized
- 429: Too Many Requests
Troubleshooting
If you hit the 60 requests/minute limit, implement exponential backoff. Failed requests are free, so retrying after a brief pause rarely incurs extra cost. Check the error field in the JSON response for details.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This helps prevent overfitting and improves model generalization.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- curl documentation
- Python documentation
- TRON developer hub: TRC-20
- FFmpeg documentation
- LibriTTS-R corpus (OpenSLR 141)
- LibriTTS-R paper (arXiv 2305.18802)
- openai-node on GitHub
- OpenAI API reference: create speech
- IETF RFC 7845: Ogg Opus
- ISO 639 language codes
- W3C WAI: making audio and video accessible
