API Documentation for Synthetic Speech Generation

By VoxyData editorial team · Updated 2026-11-19

This documentation covers the VoxyData REST API for generating synthetic speech datasets. You will find clear guides on authentication, endpoints, and parameters to integrate our TTS engine into your ML pipelines or product workflows. The API follows the OpenAI speech endpoint shape, allowing you to use official SDKs with minimal configuration changes.

Designed for product teams and engineers, this page details how to source high-quality, copyright-clean audio. Learn about voice selection, language support, and rate limits to ensure consistent dataset generation. You can also see ready-to-use cURL examples and error handling strategies to streamline your integration process.

API Documentation for Synthetic Speech Generation

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

Python (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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

OpenAI SDK integration

Curl example

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

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. curl documentation
  3. Python documentation
  4. TRON developer hub: TRC-20
  5. FFmpeg documentation
  6. LibriTTS-R corpus (OpenSLR 141)
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. openai-node on GitHub
  9. OpenAI API reference: create speech
  10. IETF RFC 7845: Ogg Opus
  11. ISO 639 language codes
  12. W3C WAI: making audio and video accessible

More on this site