Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.play3n3.com/v1. You send POST requests to https://api.play3n3.com/v1/audio/speech to generate audio. Other endpoints like /v1/voices and /v1/models are also available at this base path for retrieving voice details and model information.
How do I authenticate requests?
Include your API key in the request header as Authorization: Bearer tts-<your_key>. Each account has one active key. You can issue a new key at any time, which immediately invalidates the previous one, ensuring secure access to the TTS service.
Which models are available?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing. You can select either model in your request body to generate audio. The choice does not affect the cost.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.play3n3.com/v1 and using your site-specific key. The request shape matches the OpenAI speech endpoint, allowing you to integrate our API into existing workflows without rewriting your client code.
What is the character limit per request?
Each request supports up to 4096 characters in the input field. Spaces and punctuation count toward this limit. For texts longer than 4096 characters, you must split the text into parts, generate audio for each, and join the resulting audio files.
How do I change the voice speed?
Adjust the speed parameter in your request body. Valid values range from 0.25 to 4.0. The default speed is 1.0. This allows you to slow down narration for clarity or speed up content for concise notifications and IVR systems.
What happens if I exceed the rate limit?
The rate limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a 10 requests per minute limit until the first top-up. Exceeding limits results in immediate rejection until the window resets.
Are failed requests charged?
No, failed requests are free. If synthesis fails, the charge is returned in full. You only pay for successful audio generation. This ensures you are not billed for errors or network issues during the text-to-speech conversion process.
How do I handle long texts?
Split your text into chunks of up to 4096 characters. Send each chunk as a separate request to the /v1/audio/speech endpoint. Then, join the returned audio files to create a continuous audio track. This approach handles texts of any length.
What formats are supported?
You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the desired format using the response_format field in your request body. This flexibility allows integration with various players and systems, from web browsers to telephony interfaces.
Can I stream the audio?
No, streaming is not supported. The API returns the complete audio file in the response after synthesis is finished. Requests are processed sequentially, so longer texts may take time. You must wait for the full response before playing or storing the audio.
Is SSML supported?
No, SSML is not supported. You can only pass plain text in the input field. There are no emotion tags, phoneme dictionaries, or custom pronunciation lexicons available. The system guesses the language from the script if not explicitly set.
How do I rotate my API key?
Issue a new key from your account dashboard at /get-api-key/. The new key becomes active immediately, and the old one stops working at once. This allows you to revoke access to compromised keys without downtime for your applications.
What is the response structure for errors?
Errors return a standard HTTP error code and a JSON body with an error message. The specific structure follows standard API error conventions. Failed requests are free: if synthesis fails, the charge is returned in full.
First request
curl
curl https://api.play3n3.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.play3n3.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.play3n3.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 API by generating a key on the /get-api-key/ page. Authenticate every request using a Bearer token in the Authorization header.
Maintain a single active key per account. You can rotate keys at any time, ensuring the previous key stops immediately.
Generating your API key
Create your key via the /get-api-key/ page using Google or email. The dashboard displays your key, balance, and usage stats.
Bearer token authorization header
Include Authorization: Bearer tts-... in every request header. The key grants access to your account's quota and billing.
Rotating keys and invalidation
Issue a new key anytime from the dashboard. The old key becomes invalid instantly, providing immediate security control.
Endpoints Overview
The API provides three core endpoints for generating speech and managing resources. The primary endpoint handles audio synthesis, while the other two provide metadata about available voices and model configurations.
POST /v1/audio/speech
This is the main endpoint for converting text into audio files. Send a JSON body with the text, voice selection, and format preference to receive a binary audio response.
GET /v1/voices
Retrieve a list of all available voice presets, their associated languages, and supported audio formats. This helps you select the right voice for your SaaS notifications or IVR systems.
GET /v1/models
Fetch the current model versions and their specifications. Use this to ensure compatibility with your integration setup before sending synthesis requests.
Request Parameters
Configure the synthesis engine and input constraints for each TTS request. The API accepts a fixed set of parameters that define voice, language, and output structure. Understanding these limits ensures consistent audio generation without unexpected failures.
Model selection: tts-1 vs tts-1-hd
Both "tts-1" and "tts-1-hd" use the same underlying engine and incur identical pricing. The choice does not affect voice quality or character count billing, allowing you to switch models without changing your integration logic or cost expectations.
Input text limit: 4096 characters
Each API call accepts a maximum of 4096 characters, including spaces and punctuation. For longer texts, split the input into chunks and join the resulting audio files client-side. This approach keeps individual requests lightweight and predictable.
Voice presets and language codes
Select one of eight voice presets (e.g., aria, nova, atlas) and optionally specify an ISO language code. If omitted, the system guesses the language, defaulting to English for Latin script. Explicitly setting the language ensures correct pronunciation for non-English texts.
Available languages include Arabic, Chinese, English, German, Japanese, Spanish, and others. All voices can speak any supported language, providing flexibility for international SaaS notifications and IVR systems.
- 8 voice presets: aria, nova, luna, sage, felix, milo, atlas, orion
- Supports 23 languages including English, Spanish, German, Japanese, and Hindi
- Language detection defaults to English if not specified for Latin script
Response Formats
The API returns audio data as a binary response in the requested format. Supported output types include MP3, WAV, OPUS, FLAC, and PCM. You select the desired format using the response_format parameter in your request body.
Supported formats: MP3, WAV, OPUS, FLAC, PCM
Choose MP3 for standard web delivery or WAV for high-quality archival. OPUS offers efficient compression, while FLAC provides lossless quality. PCM returns raw uncompressed audio data.
Audio binary response
The response body contains the raw audio bytes directly. There is no JSON wrapper around the audio data. Your client must handle the binary stream appropriately based on the selected format.
Error response structure
Errors return a JSON object with an error field containing type, message, and code. Failed synthesis requests incur no charge, and the cost is returned to your balance automatically.
Rate Limits and Quotas
LinguaPulse enforces a hard limit of 60 requests per minute per API key. This quota applies to all synthesis endpoints and ensures stable performance for your SaaS notifications or IVR systems. Exceeding this limit results in immediate rejection until the window resets.
60 requests per minute per key
The 60 RPM limit applies per key. Requests are processed one after another, so under load a request may wait in a queue. Plan your integration to handle standard HTTP 429 responses gracefully during brief spikes.
- Limit: 60 requests/minute/key
- Applies to POST /v1/audio/speech
- Sequential processing may cause minor latency
10 requests per minute before first top-up
New accounts start with a reduced quota of 10 requests per minute. This applies immediately upon key creation, regardless of whether you have a free trial balance. You must perform a top-up to increase this to the standard 60 RPM.
- Initial quota: 10 RPM
- Requires a top-up to upgrade
- Applies immediately after key generation
Handling rate limit errors
When you exceed the limit, the API returns an HTTP 429 status code. Implement exponential backoff in your client code to retry requests automatically. Failed requests are free: if synthesis fails, the charge is returned in full.
- HTTP 429 status code
- Use exponential backoff for retries
- No charge for rate-limited requests

SDK Integration
Integrate LinguaPulse into your SaaS notifications or IVR systems using existing tools. The API mirrors the OpenAI speech endpoint structure, allowing you to reuse familiar SDKs with minimal configuration changes.
Use the OpenAI SDK by overriding the base_url to https://api.play3n3.com/v1. Alternatively, send standard JSON payloads via plain HTTP or use the provided curl command for immediate testing.
Using the OpenAI SDK with custom base_url
Configure your client to point to our API base URL. Pass your API key in the Authorization header. The request body shape matches OpenAI's speech endpoint, ensuring compatibility with official SDKs.
Set model to tts-1 or tts-1-hd. Define the voice preset and input text. The SDK handles serialization automatically, returning the audio binary directly.
- Base URL: https://api.play3n3.com/v1
- Auth Header: Authorization: Bearer tts-...
- Supported SDKs: Official OpenAI SDKs
Plain HTTP requests example
Send a POST request to /v1/audio/speech with a JSON body. Include the model, voice, input, and response_format fields. The API returns the audio file in the requested format.
Ensure the Authorization header contains your active Bearer token. If the synthesis fails, the response indicates the error without charging your balance.
- Content-Type: application/json
- Authorization: Bearer YOUR_API_KEY
- Body: {"model": "tts-1", "voice": "nova", "input": "Hello", "response_format": "mp3"}
Ready curl command example
Use this command to test integration immediately. Replace YOUR_API_KEY with your key from the dashboard. Replace nova with any of the 8 available voices.
The command sends the text "Welcome to LinguaPulse" and saves the resulting MP3 file. Adjust --data fields for different voices or formats like WAV or OPUS.
- curl -X POST https://api.play3n3.com/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- --data '{"model":"tts-1","voice":"nova","input":"Welcome to LinguaPulse","response_format":"mp3"}'
Handling Long Texts
The API accepts up to 4,096 characters per request. For longer texts, split your input into chunks of this size and send each as a separate POST request to /v1/audio/speech. Each call returns a distinct audio file.
Collect the returned audio files in order and join them client-side. Split into parts of up to 4096 characters and join the audio files.
Splitting text into chunks
Divide your text into segments not exceeding 4,096 characters. Count spaces and punctuation as characters. Send each segment individually to the speech endpoint.
Joining audio files client-side
Receive multiple audio files from separate requests. Concatenate them in the correct order using your preferred audio library or tool. This method keeps the workflow transparent and avoids server-side formatting issues.
Managing queue delays
Requests are processed sequentially. Under load, you may experience delays. Short phrases take a few seconds; longer texts take roughly real-time duration. Plan your integration to handle asynchronous responses gracefully.
Troubleshooting Common Errors
Even with correct setup, integration hiccups occur. This section covers three frequent issues: authentication failures, input limits, and voice selection errors, with immediate remediation steps.
Invalid API key
A 401 error indicates the provided key is missing, expired, or incorrect. Verify the Authorization: Bearer tts-... header matches your key from /get-api-key/. If you issued a new key, the old one stops immediately.
- Check for trailing spaces in the key string.
- Ensure no
https://prefix is included in the token.
Text too long
The API rejects inputs exceeding 4096 characters. Split your text into smaller chunks client-side, process each request, and join the resulting audio files. Short phrases may also take a few seconds due to queue processing under load.
- Count spaces and punctuation as characters.
- Monitor queue delays if sending many requests concurrently.
Voice not found
A 400 error occurs if the voice parameter is not one of the eight presets (e.g., aria, nova, felix). Fetch the valid list via GET /v1/voices before synthesis. Any voice can speak any of these languages.
- Verify ISO language codes match the voice capabilities.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Accurate language detection prevents unnatural accents and improves user experience.
23 languages
Any voice speaks any of these languages.
