Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or email and password. Your account is specific to playbk3.com. The dashboard displays your active Bearer key, balance, and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one.
What is the maximum input text length?
The input field supports up to 4096 characters per request. For texts exceeding this limit, you must split the content into chunks of 4096 characters or fewer. Generate each chunk separately and join the resulting audio files to create the final output.
Can I change the voice mid-sentence?
No, you cannot change the voice mid-sentence within a single request. Each POST call accepts one voice parameter. To switch voices, you must split the text, generate separate audio files for each segment, and concatenate them in your application.
Does the API support streaming audio?
The API does not support streaming, WebSocket, or real-time partial audio. You send a POST request and receive the complete audio file in the response. This ensures deterministic results suitable for smart home notifications and voice assistant responses.
How do I set the language explicitly?
Pass the optional language parameter with an ISO code in the JSON body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language is recommended for non-English Latin-script content.
What is the speed range for voice modulation?
You can adjust the speech speed using the speed parameter, which accepts values between 0.25 and 4.0. This allows you to slow down or speed up the audio output to fit your device's notification style or user preference.
Is the response format always audio?
The response returns an audio file in the format you specified: mp3, wav, opus, flac, or pcm. Failed requests return no charge and typically provide error details. The audio contains an inaudible watermark marking it as synthetic speech.
How do I handle rate limit errors?
The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Implement retry logic with exponential backoff in your IoT devices or backend services to handle temporary rate limit errors gracefully.
Can I use the same key for multiple projects?
Yes, one active key per account can be used across multiple projects. The key authenticates all requests to the API. You can generate a new key at any time, which immediately stops the old one from being used.
Do I need to install a specific SDK?
No specific SDK is required. The API endpoint matches the OpenAI speech endpoint shape. You can use the official OpenAI SDKs by changing the base URL to https://api.playbk3.com/v1 or use plain HTTP requests directly from your code.
Is the API endpoint HTTPS only?
The API endpoint is https://api.playbk3.com/v1. All requests must be made over HTTPS. Authentication is handled via the Authorization header with your Bearer token.
What happens if the server is overloaded?
Requests are processed sequentially. Under load, a request may wait in a queue. Typical speed is roughly real time, but short phrases may take a few seconds. Ensure your IoT devices handle potential delays with appropriate timeout settings.
Can I request a specific sample rate?
The generated audio is deterministic and consistent for the same input text and voice parameters.
Is there a limit to concurrent requests?
Requests are processed one after another, so under load a request may wait in a queue. Monitor your usage and implement queuing logic in your application to manage request timing effectively.
First request
curl
curl https://api.playbk3.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.playbk3.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.playbk3.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 for the HomeEcho TTS API relies on a single active Bearer token per account. Include the header Authorization: Bearer tts-... in every request to https://api.playbk3.com/v1. This token authorizes your smart home or IoT device integrations for voice synthesis.
Bearer Token Usage
Pass the token in the Authorization header of each HTTP request. The API validates the key against your account balance and rate limits before processing the text-to-speech job.
- Header format:
Authorization: Bearer tts-<your_key> - Valid for all endpoints:
/v1/audio/speech,/v1/voices,/v1/models
Key Management
Each account maintains one active API key. You can view your current key, balance, and usage statistics on the /get-api-key/ dashboard page.
- One active key per account
- View key and usage on /get-api-key/
Key Rotation Policy
Issuing a new key invalidates the previous one immediately. This ensures secure deployment in IoT environments where key leakage is a risk, without requiring manual deactivation.
- New key issuance revokes the old key instantly
- No grace period for the previous key
Speech Endpoint
The core synthesis function is exposed via a single POST endpoint. Developers send text payloads to receive synthesized audio files directly. This endpoint handles all voice rendering logic, ensuring deterministic output suitable for IoT device notifications and voice assistant responses.
POST /v1/audio/speech
Send a POST request to https://api.playbk3.com/v1/audio/speech. The endpoint accepts standard JSON bodies compatible with the OpenAI speech schema. This allows existing OpenAI SDK implementations to work by simply adjusting the base URL configuration.
- Endpoint: POST /v1/audio/speech
- Content-Type: application/json
JSON Request Body
The request body must include the model ("tts-1" or "tts-1-hd"), input text (max 4096 characters), and voice preset. Optional fields include response_format, speed (0.25–4.0), and language ISO code. Authentication requires a Bearer token in the header.
Response Format
Upon successful synthesis, the API returns the raw audio file in the requested format (mp3, wav, opus, flac, or pcm). Failed requests return a JSON error object with a full refund of any consumed credit, ensuring no cost for failed operations.
Voice and Model Details
HomeEcho provides deterministic voice synthesis for IoT devices. The API returns eight distinct voice presets and two model engines. All voices support 23 languages, allowing consistent audio generation across smart home ecosystems without external dependencies.
GET /v1/voices
Retrieve available voices, languages, formats, and pricing via GET /v1/voices. The endpoint lists eight presets: four female (aria, nova, luna, sage) and four male (felix, milo, atlas, orion). Each voice can speak any of the 23 supported languages.
GET /v1/models
List available models via GET /v1/models. The API supports two models: tts-1 and tts-1-hd. Both use the same engine and price structure. The model field determines the synthesis engine used for audio generation.
Model Selection
Select tts-1 for standard generation or tts-1-hd for higher fidelity. Both models process text up to 4096 characters per request. Audio files include an inaudible watermark indicating synthetic speech. Model choice does not affect pricing or rate limits.
Request Parameters
The API accepts plain text input with a strict maximum of 4,096 characters per request. All characters, including spaces and punctuation, are counted toward the usage limit. For texts exceeding this length, clients must split the input into multiple requests and concatenate the resulting audio files to ensure continuous playback.
Input Text Limit
Each request processes up to 4,096 characters of input text. The system does not support SSML or custom pronunciation lexicons, so text must be provided as raw strings. Characters are billed at $0.01 per 1,000 characters, so precise character counting is essential for cost estimation.
- Maximum input length: 4,096 characters per request.
- All spaces and punctuation count toward the character total.
- Split longer texts into multiple requests for continuous audio.
Voice Selection
Select one of eight preset voices using the voice parameter. Each voice is optimized for specific use cases, such as narration, instruction, or conversational tone. The available voices include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion, each based on licensed recordings.
- Aria: warm, clear narrator.
- Nova: bright, upbeat.
- Luna: soft, storytelling.
- Sage: calm, instructional.
- Felix: energetic, promo.
- Milo: friendly, conversational.
Speed Adjustment
Adjust the playback speed between 0.25 and 4.0 using the speed parameter. This allows developers to optimize audio duration for device notifications or voice assistants without re-generating the audio. Default speed is 1.0. Speed adjustments do not affect the character count or billing.
- Speed range: 0.25 to 4.0.
- Default speed: 1.0.
- No impact on character billing.
Response Formats
The HomeEcho API returns audio data in the format specified by the response_format parameter. Supported formats include MP3, WAV, OPUS, and FLAC, allowing developers to balance file size and quality according to their device constraints.
MP3 Output
MP3 is the default and most widely supported format for web and mobile applications. It provides a compressed audio file suitable for general playback on smart home displays and voice assistants.
WAV Output
WAV provides uncompressed audio data, ensuring lossless quality for device notifications or local processing. This format is ideal when bandwidth is less critical than preserving exact audio fidelity for IoT devices.
OPUS and FLAC Support
OPUS and FLAC are supported output formats for audio files. Both formats are returned as standard audio files with no additional encoding required.

Rate Limits
Rate limits are enforced per API key. Standard accounts process 60 requests per minute. This ensures consistent throughput for smart home devices generating notifications or voice assistant responses without overwhelming the synthesis engine.
60 Requests Per Minute
Each active key is limited to 60 requests per minute. This limit applies globally to your key, covering all voice and model combinations. Exceeding this threshold triggers a 429 status code.
Initial 10 RPM Limit
New accounts without a top-up start with a 10 requests per minute limit. This ensures stability during initial integration testing. You can increase this limit immediately by adding USDT via the TRON network.
Queue Behavior
Queue Behavior
Requests are processed sequentially under load. If you exceed the limit, subsequent requests wait in a queue. Longer texts take more time, potentially affecting throughput. Short phrases may still process within seconds if capacity is available.
Error Handling
API errors are returned as JSON objects with standard HTTP status codes. Failed synthesis requests incur no charge, and the cost is returned to your account balance automatically.
Errors occur during validation, rate limiting, or synthesis failure. Always check the response body for detailed error messages to resolve issues quickly.
HTTP Status Codes
Use standard HTTP codes to determine request status. 200 indicates success. 400 denotes invalid input or parameters. 401 signals an invalid or expired API key. 429 indicates rate limit exceeded. 500 represents internal server errors.
- 200: Success
- 400: Bad Request
- 401: Unauthorized
- 429: Too Many Requests
- 500: Internal Server Error
JSON Error Responses
All error responses include a JSON object with an error field. This object contains a code string and a message string describing the specific issue. Parse this structure to identify the root cause.
Invalid characters, unsupported languages, or missing required fields trigger 400 errors. Authentication failures trigger 401 errors. These details help you adjust your integration logic.
Retry Logic
Implement exponential backoff for 429 and 500 errors. Wait briefly before retrying to avoid overwhelming the queue. Failed synthesis requests are free, so retries do not incur additional costs.
For rate limits, wait until the minute window resets. Do not retry immediately upon a 429 error. Monitor your usage dashboard to stay within the 60 requests per minute limit.
SDK Integration
HomeEcho’s API mirrors the OpenAI speech endpoint structure, allowing seamless integration with existing OpenAI SDKs. By adjusting the base URL and providing your Bearer token, you can generate audio files without rewriting core logic.
OpenAI SDK Compatibility
Use the official OpenAI SDK or plain HTTP requests. Set the base_url to https://api.playbk3.com/v1 and inject your tts-... key. The request shape remains identical, ensuring deterministic audio output for your IoT devices.
- Supports standard OpenAI client libraries
- Identical JSON request body structure
- No custom wrapper code required
Base URL Configuration
Point your SDK client to https://api.playbk3.com/v1. This directs all POST /v1/audio/speech requests to the HomeEcho infrastructure. Ensure your authentication header uses the Bearer scheme with your unique API key.
Direct HTTP Requests
For environments without an SDK, send a standard POST request to the speech endpoint. Include the JSON body with model, input, voice, and response_format fields. The API returns the audio file directly in the response body.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This allows you to test voice presets like Aria or Felix without managing complex billing setups.
23 languages
Any voice speaks any of these languages.
