API Documentation for Text to Speech Synthesis

By SynthEval editorial team · Updated 2026-11-18

This documentation provides the technical specifications for SynthEval’s text-to-speech API, designed for engineering teams building synthetic audio datasets. You will find precise details on integration methods, including OpenAI SDK compatibility and direct HTTP requests, enabling you to generate labeled audio files programmatically.

Targeted at startups developing machine learning pipelines, this guide covers authentication, parameter constraints, and rate limits. We detail how to handle character splitting, language detection, and error handling to ensure reliable, high-volume synthesis without licensing overhead.

API Documentation for Text to Speech Synthesis

Frequently asked questions

How do I authenticate with the API?

Include your API key in the request header as Authorization: Bearer tts-.... Each account holds one active key. If you issue a new key, the previous one stops immediately. You can generate your key on the /get-api-key/ page after signing up with Google or email and password.

What is the base URL for the OpenAI SDK?

The base URL is https://api.play98f.com/v1. Configure your OpenAI SDK client to use this base URL instead of the default OpenAI endpoint. This allows you to use the official SDKs seamlessly by simply changing the configuration parameter for the API base path.

Can I use the official OpenAI SDKs?

Yes. The API endpoint matches the OpenAI speech endpoint shape. By setting your SDK’s base_url to https://api.play98f.com/v1, you can use the official OpenAI SDKs directly. This ensures compatibility without requiring you to write custom HTTP clients or handle complex request formatting.

What are the rate limits for the API?

The limit is 60 requests per minute per key. Before your first top-up, the limit is lower at 10 requests per minute. Requests are processed sequentially, so under load, your request may wait in a queue. Monitor your usage via the dashboard to stay within limits.

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. Each voice has a distinct tone, from warm narrators to deep documentary styles. The voice selection determines the audio character of the generated speech.

What happens if I exceed the character limit?

Each request supports up to 4096 characters. If your text is longer, you must split it into parts of this size. Generate audio for each part separately, then join the resulting audio files. This ensures all text is processed correctly without truncation or errors due to length.

Is the API compatible with Python?

Yes. Since the API uses the same request shape as OpenAI’s speech endpoint, you can use the official OpenAI Python SDK. Just configure the base_url to https://api.play98f.com/v1. This allows you to leverage existing Python code and libraries for seamless integration into your applications.

How do I handle long texts in the API?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate POST request to the /v1/audio/speech endpoint. Once you receive the audio files for each part, join them sequentially. This workflow ensures that all your text is synthesized without hitting character limits.

What error codes might I receive?

Standard HTTP status codes indicate success or failure. Failed requests are free, with the charge returned in full if synthesis fails. Common issues include rate limits or invalid keys. Check the response body for details on authentication or parameter errors during your API interactions.

Can I change the response format?

Yes. Use the response_format field in your request to choose between mp3, wav, opus, flac, or pcm. This allows you to select the format that best fits your pipeline. The API returns the audio file in the specified format directly in the response body.

How do I set the language explicitly?

Include the language field with an ISO code in your request body. This is recommended for non-English Latin-script text, as the API guesses English by default. 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.

Is there a WebSocket endpoint for streaming?

No. The API does not support streaming, WebSockets, or real-time partial audio. You must send a full text request and wait for the complete audio file to be generated and returned. This synchronous approach ensures consistent processing but does not allow for real-time audio playback.

Do I need to install a specific SDK?

No. You can use the official OpenAI SDKs or plain HTTP requests. There is no proprietary SDK required. Simply configure your HTTP client or SDK to point to https://api.play98f.com/v1. This flexibility allows you to use the tools and libraries already familiar to your development team.

How do I test the API with a sample voice?

Send a POST request to https://api.play98f.com/v1/audio/speech with a short text and a voice preset like nova or aria. Use your API key in the Authorization header. The response will contain the audio file, allowing you to verify quality and integration before processing larger datasets.

First request

curl

curl https://api.play98f.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.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.play98f.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.play98f.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
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 and Keys

Sound wave illustration for: Authentication and Keys

Access the SynthEval API using a Bearer token included in the request header. Each account maintains a single active key, ensuring straightforward authentication for your ML pipelines without complex credential management.

Bearer token authorization format

Include your key as Authorization: Bearer tts-... in every HTTP request. This standard format allows immediate compatibility with existing OpenAI SDKs by simply adjusting the base_url.

Single active key per account

Your account is linked to one active key at any given time. This simplifies tracking usage and billing across your synthetic speech generation workflows.

Instant key revocation on reissue

Issuing a new key instantly invalidates the previous one. This ensures that only your current credentials are valid, providing immediate security control if a key is compromised.

Endpoint: Audio Speech Generation

Sound wave illustration for: Endpoint: Audio Speech Generation

The core synthesis endpoint is POST https://api.play98f.com/v1/audio/speech. This endpoint accepts a JSON payload containing the text, voice selection, and formatting parameters, then returns the synthesized audio file directly in the response body. It follows the standard OpenAI speech endpoint structure, allowing you to use existing OpenAI SDKs by simply adjusting the base_url.

POST /v1/v1/audio/speech endpoint details

Send your text input here to generate audio. The endpoint processes requests sequentially, so under heavy load, synthesis may experience queue delays. Typical generation speed approximates real-time for long texts, processing roughly 25 characters per second. Short phrases may take a few seconds to synthesize.

JSON body structure for requests

Include the model ("tts-1" or "tts-1-hd"), input (text up to 4096 characters), voice (one of 8 presets), response_format (mp3, wav, opus, flac, pcm), and optional speed (0.25–4.0). The input field accepts plain text; SSML is not supported.

  • model: "tts-1" or "tts-1-hd"
  • input: string, max 4096 chars
  • voice: string (e.g., "aria", "nova")
  • response_format: mp3, wav, opus, flac, or pcm
  • speed: float, range 0.25 to 4.0

Response format for audio files

The API returns the audio file directly in the HTTP response body with the corresponding Content-Type header (e.g., audio/mpeg). Failed requests return a JSON error object but incur no charge, with the credit fully returned to your balance.

Endpoint: Audio Speech Generation

Supported Models and Parameters

Sound wave illustration for: Supported Models and Parameters

The API supports two model variants, tts-1 and tts-1-hd, which utilize the same underlying engine and pricing tier. Both models process input text up to 4096 characters per request, returning synthesized audio files in the specified format. The choice between models does not affect cost or voice availability, allowing developers to switch based on latency or quality preferences without changing the base configuration.

tts-1 and tts-1-hd model options

Both tts-1 and tts-1-hd models share identical infrastructure, voice pools, and pricing at $10 per million characters. The primary distinction lies in the audio fidelity and processing characteristics, though both deliver high-quality synthetic speech suitable for ML dataset generation. Developers can select either model in the model field of the POST request without impacting the character count billing.

Voice selection from 8 presets

Select from eight licensed voice presets based on LibriTTS-R and LibriVox recordings. Each voice is tagged with a specific persona, such as aria for warm narration or atlas for neutral news delivery. These voices are consistent across all supported languages, ensuring uniform quality for training data pipelines.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion
  • All voices support 23 languages
  • Inaudible watermark marks synthetic output

Speed control between 0.25 and 4.0

Adjust the speed parameter between 0.25 and 4.0 to modify the playback rate of the generated audio. This allows for precise timing control when generating labeled audio datasets, ensuring that audio segments align correctly with text labels for machine learning models. The default speed is 1.0, representing natural speech pacing.

Audio Formats and Output

Sound wave illustration for: Audio Formats and Output

The API accepts MP3, WAV, OPUS, FLAC, and PCM as output formats. The choice depends on your storage needs and downstream processing requirements. Each generated file carries an inaudible watermark, marking it as synthetic speech for ML dataset labeling.

Supported formats: mp3, wav, opus, flac, pcm

Select your preferred format in the response_format field. MP3 offers compressed efficiency, while WAV and FLAC provide lossless quality. PCM is available for raw data pipelines. OPUS balances quality and file size effectively for large-scale dataset generation.

Character limit of 4096 per request

Each API call supports a maximum of 4,096 characters in the input field. This limit applies to the total text length, including spaces and punctuation. Requests exceeding this character count will be rejected.

Handling longer texts via splitting

For texts longer than 4,096 characters, you must split the input into chunks of the maximum length. Generate audio for each chunk independently, then join the resulting audio files in your pipeline. This ensures stable processing and accurate billing per segment.

Language Detection and Codes

Sound wave illustration for: Language Detection and Codes

Specify the language using a standard ISO code in the language field to ensure accurate synthesis. This is critical for non-English texts using Latin script, as the API guesses the language based on the script otherwise.

ISO language code specification

Pass the ISO code (e.g., de for German, fr for French) in your request body. This overrides automatic detection and ensures the engine selects the correct phonetic rules for your target language.

Automatic script-based detection

If you omit the language field, the system infers the language from the text script. Latin characters default to English. Cyrillic, Arabic, or CJK scripts trigger their respective language models automatically.

Default English behavior for Latin script

Latin-script text without a specified language is treated as English. To generate Spanish or Portuguese text using Latin letters, you must explicitly set language to es or pt to avoid English pronunciation artifacts.

Language Detection and Codes

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

The API enforces strict rate limits to ensure stable performance for ML training pipelines. Each API key is capped at 60 requests per minute once the account has completed its first top-up.

60 requests per minute per key

After completing the top-up process, your key allows up to 60 requests per minute. This limit applies per key, so generating multiple parallel requests requires separate keys.

10 requests per minute initially

New accounts or those without a current balance start with a reduced limit of 10 requests per minute. This ensures system stability before scaling up to the full 60 req/min capacity.

Queue behavior under load

Requests are processed sequentially within the limit. During high demand, additional requests may wait in a queue before processing begins. Expect slight delays for long texts, as synthesis takes roughly one second per 25 characters of text.

Error Handling and Status Codes

Sound wave illustration for: Error Handling and Status Codes

SynthEval’s API returns standard HTTP status codes to indicate request outcomes. Developers should monitor response headers and bodies to distinguish between client-side input errors and server-side processing issues, ensuring robust integration into ML training pipelines.

Handling 4xx and 5xx errors

Client errors (4xx) typically indicate invalid parameters, such as an expired key or exceeding the 4096-character limit. Server errors (5xx) suggest temporary infrastructure issues during synthesis.

Retry logic for transient failures

For 5xx responses, implement exponential backoff to handle queueing or temporary load. Since requests are processed sequentially, under heavy load, delays may occur before the audio is generated.

Billing adjustment on failed requests

If synthesis fails completely, the charge is returned in full. Only successful audio generations incur the standard rate of $10 per million characters, ensuring you pay only for usable datasets.

Error Handling and Status Codes

Integration Examples

Sound wave illustration for: Integration Examples

The API is compatible with standard OpenAI SDKs by simply updating the base URL. This allows teams to integrate SynthEval into existing pipelines with minimal code changes. You can test immediate generation or run batch jobs for dataset creation using your single active Bearer token.

For rapid verification, use the provided cURL command. For production datasets, the Python example demonstrates how to loop through text inputs, handle the 4096-character limit, and collect audio files efficiently without manual intervention.

cURL command for immediate testing

Send a POST request to the speech endpoint with your API key. The following command generates a 5-second audio clip in MP3 format using the 'nova' voice.

Replace YOUR_API_KEY with your actual key from the dashboard. The response returns the audio binary directly to your console for immediate playback or file saving.

  • Endpoint: https://api.play98f.com/v1/audio/speech
  • Method: POST
  • Header: Authorization: Bearer YOUR_API_KEY
  • Body: `{"model": "tts-1", "voice": "nova", "input": "Synthetic data for ML training."}`

OpenAI SDK configuration with base_url

Initialize the client with the SynthEval base URL. This ensures all requests route to the correct API instance while using standard SDK methods.

Set the API key in the environment or constructor. The SDK handles JSON serialization and response parsing automatically, reducing boilerplate code for your team.

  • base_url="https://api.play98f.com/v1`
  • api_key="YOUR_API_KEY"
  • model="tts-1-hd"
  • response_format="wav"

Python script example for batch processing

Loop through your text dataset, respecting the 4096-character limit per request. Save each generated audio file with a unique identifier to maintain dataset integrity.

Handle rate limits by implementing simple exponential backoff if you exceed 60 requests per minute. This ensures stable throughput for large-scale dataset generation.

  • Split texts >4096 chars manually
  • Use requests or openai library
  • Save outputs as .mp3 or .wav
  • Track character usage for billing

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Our synthetic speech datasets help startups train smarter AI models without expensive voice talent.

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. FFmpeg documentation
  3. openai-node on GitHub
  4. LibriTTS-R corpus (OpenSLR 141)
  5. MDN: Web Speech API
  6. LibriVox public-domain audiobooks
  7. openai-python on GitHub
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. ISO 639 language codes
  10. curl documentation
  11. Python documentation
  12. Tether (USDT)

More on this site