HomeEcho TTS API: Pricing, Voices, and Integration Guide

By HomeEcho editorial team · Updated 2026-11-18

This guide provides the technical specifications for the HomeEcho text-to-speech API, designed for smart home and IoT developers requiring deterministic audio synthesis. You will find precise details on authentication, endpoint structures, and parameter constraints necessary for integrating voice generation into device notifications and voice assistants without external dependencies.

The documentation outlines the integration workflow using standard HTTP requests or the OpenAI SDK, covering voice selection, speed adjustment, and supported output formats. It also details rate limits, error handling, and pricing structures to ensure reliable scaling for independent developers managing consistent audio output in connected ecosystems.

HomeEcho TTS API: Pricing, Voices, and Integration Guide

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

Python (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
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

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

Response Formats

Rate Limits

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

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. openai-python on GitHub
  3. LibriVox public-domain audiobooks
  4. Node.js documentation
  5. Python documentation
  6. openai-node on GitHub
  7. Creative Commons Attribution 4.0
  8. IETF RFC 7845: Ogg Opus
  9. ISO 639 language codes
  10. TRON developer hub: TRC-20
  11. FFmpeg documentation
  12. LibriTTS-R paper (arXiv 2305.18802)

More on this site