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.mp3Python (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 | |
|---|---|
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 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
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.

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

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

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
requestsoropenailibrary - Save outputs as
.mp3or.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.
23 languages
Any voice speaks any of these languages.
