Frequently asked questions
What is the base URL for the API?
The base URL is https://api.play8055.com/v1. Use this endpoint for all requests, including POST /v1/audio/speech for generation and GET /v1/voices for metadata. This structure allows standard HTTP clients to interact with the service efficiently without requiring proprietary connection logic.
How do I generate an API key?
Sign up on the /get-api-key/ page using Google or an email and password. Your account page displays your active Bearer token immediately. You can issue a new key at any time, which instantly invalidates the previous one, ensuring secure access control.
Can I use the OpenAI SDK with this API?
Yes. The request shape matches the OpenAI speech endpoint exactly. Configure your SDK’s base_url to https://api.play8055.com/v1 and provide your TTS API key. This allows you to use official OpenAI SDKs seamlessly without modifying your existing integration code structure.
What is the maximum character limit?
Each request supports up to 4096 characters in the input field. For longer texts, split the content into chunks of this size and join the resulting audio files. Spaces and punctuation count toward this limit, so plan your text segmentation accordingly.
How do I set the voice speed?
Include the speed parameter in your JSON body with a value between 0.25 and 4.0. The default speed is 1.0. Adjusting this value scales the playback rate of the generated audio, allowing for faster or slower delivery of the spoken text.
Which audio formats are available?
You can request audio in mp3, wav, opus, flac, or pcm formats via the response_format field. Choose the format that best fits your IoT device’s playback capabilities or your backend’s storage requirements.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key (10 per minute before the first top-up). Exceeding this will likely result in delayed processing or errors. Requests are processed sequentially, so under load, additional requests may wait in a queue before synthesis begins.
Are there SDKs for other languages?
We do not provide an official SDK. However, because our API follows the standard OpenAI request shape, you can use any HTTP client or the OpenAI SDK in your preferred language. Simply configure the base URL to https://api.play8055.com/v1 and include your Bearer token in the headers to integrate seamlessly with your existing stack.
How do I handle long texts?
Split your text into parts of up to 4096 characters. Send each part as a separate request and join the returned audio files. This approach ensures compliance with the character limit while allowing you to generate audio for documents or lengthy instructions.
What is the difference between tts-1 and tts-1-hd?
Both models use the same engine and have the same price. The difference is purely in the model identifier string you send in the request body. Functionally, they produce identical audio output, so you can use either model for your synthesis tasks.
Does the API support streaming?
No, the API does not support streaming, WebSocket, or real-time partial audio. It returns the complete audio file in the response body. This synchronous approach is reliable for IoT applications where you need the full audio asset before proceeding with playback.
How do I detect the language automatically?
If you do not set the language field, the system guesses it from the script. Latin text defaults to English. For non-English Latin-script text, explicitly set the language parameter to ensure accurate pronunciation, as automatic detection may not always be precise for mixed scripts.
What is the default response format?
The API supports mp3, wav, opus, flac, and pcm formats. To ensure consistent behavior, explicitly include the response_format parameter in your JSON body to receive the audio data in your preferred encoding.
Can I use the same key for multiple projects?
Yes, you can use the same API key across multiple projects or devices. However, each account has only one active key. If you issue a new key, the old one stops immediately, so ensure all your projects are updated to use the current key.
First request
curl
curl https://api.play8055.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.play8055.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.play8055.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
Authentication relies on a single bearer token included in the Authorization header. This token is generated during account creation and grants access to all API endpoints. Ensure the key is transmitted securely to prevent unauthorized usage of your character balance.
Bearer Token Format
Include your API key as a Bearer token in every request header: Authorization: Bearer tts-<your_key>. The key string begins with the prefix tts- followed by alphanumeric characters. This format is compatible with standard HTTP libraries and the OpenAI SDK.
Key Management
Each account maintains one active API key visible on the dashboard. You can regenerate the key at any time via the /get-api-key/ page. The system displays your current key, usage statistics, and remaining balance for easy monitoring.
- Key is visible in the account dashboard.
- Regenerate key immediately if compromised.
Single Active Key
Only one key is active per account. When you issue a new key, the previous one becomes invalid immediately. This ensures that any device or service using an old key will stop working instantly, simplifying security management for IoT deployments.
Speech Endpoint
The speech synthesis endpoint converts text input into audio files via a standard REST call. It accepts JSON payloads containing the desired voice, language, and audio format, returning the complete audio file in the response body.
POST /v1/audio/speech
Send a POST request to /v1/audio/speech with your JSON body. The endpoint processes requests sequentially; under load, your request may wait in a queue before synthesis begins. Ensure your text input does not exceed 4096 characters.
- Base URL: https://api.play8055.com/v1
- Method: POST
- Content-Type: application/json
Request Body Schema
Provide the model (tts-1 or tts-1-hd), input text, and voice preset. Optional fields include response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0), and language (ISO code). If language is omitted, the system guesses the language based on the script, defaulting to English for Latin text.
- input: String, max 4096 characters
- voice: String, one of 8 presets
- model: String, tts-1 or tts-1-hd
- speed: Number, 0.25 to 4.0
- response_format: String, mp3/wav/opus/flac/pcm
Response Audio Stream
The API returns the complete audio file in the requested format. It does not support streaming, WebSocket, or real-time partial audio. For short phrases, generation takes a few seconds. For long texts, the average processing speed is roughly 25 characters per second, though queue wait times may apply.

Voices Endpoint
The /v1/voices endpoint returns available presets, supported languages, and formats. It provides the metadata needed to configure your API calls correctly.
Voices are derived from licensed LibriTTS-R recordings and public-domain LibriVox audiobook readings. Every generated audio file includes an inaudible watermark identifying it as synthetic speech.
GET /v1/voices
Send a GET request to retrieve the current list of voice presets, available languages, and supported response formats. This endpoint allows you to verify which voices are active and compatible with your target language settings before making synthesis requests.
List of 8 Presets
We provide eight distinct voice presets to suit different audio profiles. Select from female voices (aria, nova, luna, sage) or male voices (felix, milo, atlas, orion). Each voice offers a specific tonal quality, from warm and clear to deep and documentary-style, suitable for various IoT notification and feedback scenarios.
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
- felix: energetic, promo
- milo: friendly, conversational
- atlas: neutral, news
- orion: deep, documentary
Language Support Details
Each of the eight voices can speak any of the 23 supported languages. If the language parameter is omitted, the system guesses the language from the text script (defaulting to English for Latin script). For non-English Latin-script text, explicitly set the language code to ensure accurate pronunciation.
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. Languages such as Vietnamese, Thai, Ukrainian, and Romanian are not supported.
Models Endpoint
The models endpoint provides metadata about available synthesis engines. It confirms that both tts-1 and tts-1-hd are active and ready for integration into your IoT firmware or backend services.
GET /v1/models
Call this endpoint to retrieve the current list of available model identifiers. The response confirms the available model identifiers for subsequent speech requests.
tts-1 vs tts-1-hd
Both model strings, "tts-1" and "tts-1-hd", route to the exact same synthesis engine. There is no quality or latency difference between them; they are functionally identical for your use case.
- Use either identifier in the request body.
- No price difference between the two strings.
- Same processing queue and generation speed.
Engine Parity
The engine handles all voice presets and languages uniformly regardless of the model string used. This simplifies integration logic, allowing you to switch model strings without adjusting your audio processing pipeline.
Request Parameters
The API accepts text input up to 4096 characters per request, including spaces and punctuation. For texts exceeding this limit, split the input into multiple requests and join the resulting audio files. Typical generation speed is approximately 25 characters of text per second of audio.
Input Text Limit
Send up to 4096 characters in a single POST request. If your content exceeds this length, divide the text into chunks, process each chunk individually, and concatenate the audio outputs.
Speed Range
Adjust playback speed between 0.25 and 4.0. Values below 1.0 slow the voice, while values above 1.0 accelerate it. This allows precise timing control for firmware playback cycles.
Response Formats
Choose from mp3, wav, opus, flac, or pcm formats. Select the format that best fits your device’s decoding capabilities and network constraints.

Rate Limits
API calls are rate-limited per authentication key to ensure stable generation. New keys start with a lower throughput to prevent abuse, which increases upon your first top-up.
60 Requests Per Minute
Once your account is active with a funded balance, the limit is 60 requests per minute. This allows batch processing for smart home devices or industrial audio pipelines.
10 RPM for New Keys
Accounts created with email/password or new Google sign-ins start with 10 requests per minute. This limit persists until you complete your first USDT (TRC-20) top-up of at least $5. After the transfer is confirmed, the limit automatically increases to 60 RPM.
Queue Behavior
Requests are processed sequentially. If you exceed the per-minute limit or the server is under load, new requests wait in a queue. You will receive the audio file once the queue processes your turn. There is no SLA guaranteeing specific queue wait times.
Error Handling
Errors return standard HTTP codes (400, 401, 429, 500). Any request that fails synthesis is free. The charge is returned in full, so you are not billed for incomplete audio generation.
HTTP Status Codes
400 Bad Request indicates invalid JSON or missing fields. 401 Unauthorized means your Bearer token is missing or incorrect. 429 Too Many Requests signals you have exceeded the 60 requests per minute limit. 500 Internal Server Error denotes a transient processing failure.
Failed Request Refund
Synthesis failures trigger a full refund automatically. If the API cannot produce audio from your input, the charge is returned in full. This applies to all failure types, ensuring you only pay for successfully delivered audio files.
Debugging Common Issues
Ensure your text input is under 4096 characters. Verify the voice ID matches one of the eight supported presets. Check that your API key is active and not expired.
- Text exceeds 4096 characters
- Invalid voice ID
- Expired or inactive API key
- Network timeout during generation

Integration Examples
Integrate IoT Voice API into your smart home or industrial backend with minimal overhead. The API follows the standard OpenAI speech endpoint shape, allowing you to leverage existing client libraries or simple HTTP requests for reliable audio generation.
cURL Command
Use this command to generate speech directly from your terminal or build scripts. Replace YOUR_API_KEY with your credential and adjust the voice and language parameters as needed.
- curl -X POST https://api.play8055.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "System ready.", "voice": "atlas", "response_format": "mp3"}' \ -o output.mp3
OpenAI SDK Setup
Leverage the official OpenAI SDK by pointing it to our base URL. This allows you to use familiar methods while accessing our specific voice presets and engine capabilities.
- from openai import OpenAI client = OpenAI( base_url="https://api.play8055.com/v1", api_key="YOUR_API_KEY" ) # Use client.audio.speech.create()
Python Integration
For lightweight firmware or backend services, use the requests library to handle POST responses. Ensure you handle the binary audio data correctly and manage character limits under 4096 per request.
- import requests resp = requests.post( "https://api.play8055.com/v1/audio/speech", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={"model": "tts-1", "input": "Alert triggered", "voice": "nova"} ) with open("alert.wav", "wb") as f: f.write(resp.content)
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Transform your residential devices into an intuitive, connected ecosystem that delights modern homeowners.
23 languages
Any voice speaks any of these languages.
