API Documentation: Voices, Endpoints, and Integration

By IoT Voice API editorial team · Updated 2026-11-18

This page provides the technical reference for the IoT Voice API, designed for engineering teams building smart home and industrial applications. You will find precise details on authentication, request schemas, and the eight voice presets available for synthetic audio generation. All endpoints follow standard REST conventions, ensuring seamless integration into your existing firmware or backend infrastructure.

Use this documentation to understand rate limits, supported response formats, and error handling procedures. The guide includes ready-to-use cURL commands and Python examples, helping you generate audio from text with minimal overhead. Whether you are prototyping a voice interface or scaling to thousands of devices, this reference covers the essential parameters needed for reliable deployment.

API Documentation: Voices, Endpoints, and Integration

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

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

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

Speech Endpoint

Voices Endpoint

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

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

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

Request Parameters

Rate Limits

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

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

Integration Examples

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

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. TRON developer hub: TRC-20
  3. Tether (USDT)
  4. ISO 639 language codes
  5. curl documentation
  6. LibriVox public-domain audiobooks
  7. openai-node on GitHub
  8. Node.js documentation
  9. openai-python on GitHub
  10. MDN: Web Speech API
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. Creative Commons Attribution 4.0

More on this site