API Documentation for IoT Text to Speech Integration

By SmartSay editorial team · Updated 2026-11-18

This guide helps IoT developers integrate SmartSay’s text-to-speech API into smart home devices and automation hubs. You will learn how to send text and receive audio files using standard HTTP requests, ensuring deterministic, low-latency responses for voice-enabled dashboards without managing complex cloud dependencies.

We cover authentication, voice presets, language detection, and rate limits specific to your use case. You will find ready-to-use curl examples, OpenAI SDK compatibility notes, and strategies for handling long texts within the 4096-character limit. This page focuses on practical integration steps for startups building voice interfaces.

API Documentation for IoT Text to Speech Integration

Frequently asked questions

What is the API endpoint URL?

Send requests to POST https://api.playae77.com/v1/audio/speech. This endpoint accepts JSON bodies containing your text, voice selection, and format preferences. It follows the standard OpenAI speech endpoint structure, ensuring seamless integration for existing IoT workflows without requiring custom endpoint logic.

How do I authenticate?

Include your API key in the request header as Authorization: Bearer tts-... . Each account holds one active key; issuing a new key immediately invalidates the previous one. Ensure your key is securely stored in your device’s environment variables to prevent unauthorized usage.

What languages are supported?

We support 23 languages, including English, German, Spanish, Japanese, and Arabic. Any voice can speak any supported language. If the language parameter is omitted, the system guesses from the script, defaulting to English for Latin text. Specify the ISO code for non-English Latin scripts.

What audio formats can I use?

You can request audio in mp3, wav, opus, flac, or pcm formats. These options allow flexibility for different IoT device capabilities. Choose mp3 for efficient storage or wav for uncompressed quality. The format is specified in the response_format field of your JSON request body.

What is the rate limit?

The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Exceeding this may cause delays as requests are processed sequentially. Monitor your usage via the dashboard to ensure your smart home automations remain responsive during peak times.

Can I change the speed?

Yes, adjust the speed between 0.25 and 4.0. This allows you to optimize audio length for bandwidth-constrained IoT devices. Faster speeds reduce generation time, while slower speeds may improve clarity for complex instructions. The speed parameter is part of the standard JSON request body.

Is the SDK compatible with OpenAI?

Yes, the request shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playae77.com/v1 and using your site’s key. This ensures compatibility with existing codebases without requiring significant refactoring for your IoT applications.

How do I handle errors?

Failed requests are free: if synthesis fails, the charge is returned in full. Monitor the response status code to determine success or failure. If synthesis fails, no characters are deducted from your balance. Implement retry logic in your IoT firmware to handle transient network or processing issues gracefully.

What happens if the text is too long?

Split text into parts of up to 4096 characters per request. Join the resulting audio files to create a continuous output. This allows you to generate longer announcements or instructions for your smart home devices without hitting the single-request character limit imposed by the API.

Do I need to install a library?

No, you can use plain HTTP requests. Alternatively, use the OpenAI SDK by adjusting the base URL. This flexibility allows you to integrate the TTS API into any IoT platform, whether it uses Python, JavaScript, or C++, without being tied to a specific proprietary library.

Can I use the API in Python?

Yes, use the OpenAI Python SDK with the base_url set to https://api.playae77.com/v1. Pass your tts-... key for authentication. This approach leverages existing Python libraries familiar to many IoT developers, simplifying integration into your smart home backend services or edge device scripts.

What is the input limit?

Each request supports up to 4096 characters of text. Spaces and punctuation count toward this limit. For longer texts, split them into multiple requests and concatenate the audio outputs. This ensures efficient processing and maintains the deterministic latency required for responsive voice-enabled IoT devices.

Are voices gender-specific?

Voices are categorized as female (Aria, Nova, Luna, Sage) or male (Felix, Milo, Atlas, Orion). However, any voice can speak any of the 23 supported languages. Choose the voice that best fits your device’s persona, such as Atlas for news or Luna for storytelling.

How do I get my API key?

Sign up at /get-api-key/ using Google or email. The page displays your API key, balance, and usage stats. Keys are issued per site. You can generate a new key at any time, which immediately invalidates the old one, ensuring secure access for your IoT deployments.

First request

curl

curl https://api.playae77.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.playae77.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.playae77.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 and keys

Sound wave illustration for: Authentication and keys

Access the SmartSay API using a standard Bearer token in your Authorization header. This key authenticates your requests and tracks your character usage against your account balance.

Each account maintains a single active API key. When you issue a new key, the previous one becomes invalid immediately, ensuring precise control over your device integrations and preventing unauthorized usage.

Bearer token format

Bearer token format

Include your key in the HTTP header as Authorization: Bearer tts-.... The prefix tts- identifies SmartSay tokens and distinguishes them from other service credentials.

Single active key per account

Single active key per account

Your account is tied to one active key at any time. This simplifies management for IoT deployments where you need a single source of truth for authentication across all devices.

Regenerate key instantly

Generate a new key via your dashboard at any time. The old key stops working immediately, allowing you to rotate credentials without downtime or waiting for expiration.

Speech endpoint details

Sound wave illustration for: Speech endpoint details

The core synthesis engine is exposed via a single POST endpoint. Your IoT device or backend service sends a JSON payload containing the text, selected voice, and audio format preferences. The API processes the request and returns the generated audio file directly in the response body, allowing seamless integration into voice-enabled dashboards and automation hubs.

Each request is processed sequentially. Typical generation speed is roughly real-time (about 25 characters per second); short phrases may take a few seconds. If the synthesis engine is under load, requests may queue briefly before processing begins. Failed requests are free: if synthesis fails, the charge is returned in full.

POST /v1/audio/speech

Send your text payload to this endpoint. The endpoint accepts standard JSON bodies and returns audio data in the requested format. Ensure your IoT firmware or backend service handles binary audio responses correctly, as the payload size varies based on text length and format.

The endpoint enforces a strict 4,096 character limit per request. Longer narratives must be split by your application logic before sending, then reassembled client-side or via a server-side join service to maintain audio continuity.

  • Endpoint: POST https://api.playae77.com/v1/audio/speech
  • Max input: 4,096 characters
  • Rate limit: 60 requests/minute per key

JSON body structure

The request body requires four essential fields: model, input, voice, and response_format. The model field accepts either tts-1 or tts-1-hd, both using the same engine and pricing tier. The input field contains your text string, while voice selects one of the eight available presets.

Optional fields include speed (0.25–4.0) for adjusting playback rate and language for specifying an ISO code. If language is omitted, the system guesses it from the script, defaulting to English for Latin text. Explicitly setting the language ensures accuracy for non-English inputs.

  • Required: model, input, voice, response_format
  • Optional: speed, language
  • Model options: tts-1, tts-1-hd

Response format options

You can request audio in mp3, wav, opus, flac, or pcm formats. Choose mp3 for efficient bandwidth usage in IoT networks, or wav/flac for high-fidelity playback in smart home devices. The pcm format provides raw linear audio, suitable for low-level audio processing pipelines.

The response includes the audio data directly in the body. Ensure your IoT device’s audio decoder supports the selected format. Generated files include an inaudible watermark to identify synthetic speech, though this does not affect playback compatibility.

  • Supported formats: mp3, wav, opus, flac, pcm
  • Audio returned in response body
  • Inaudible watermark applied to all outputs

Voice parameters and presets

Sound wave illustration for: Voice parameters and presets

SmartSay’s API offers eight distinct voice presets tailored for smart home and IoT applications, ensuring deterministic audio responses. These voices are derived from licensed LibriTTS-R recordings, providing a consistent and professional tone for voice-enabled devices and automation hubs without the need for complex cloud dependencies.

Each voice is engineered for specific use cases, from warm narrators to energetic promo voices, allowing IoT startups to select the optimal audio profile for their specific interface requirements.

8 voice presets available

The API provides eight preset voices, categorized by gender and tone, suitable for various IoT interactions. Female voices include aria (warm narrator), nova (bright and upbeat), luna (soft storyteller), and sage (calm instructor). Male options feature felix (energetic promo), milo (friendly conversational), atlas (neutral news), and orion (deep documentary).

These presets are based on licensed recordings from LibriTTS-R (CC BY 4.0) and LibriVox public-domain audiobooks. Every generated audio file includes an inaudible watermark to identify synthetic speech, ensuring transparency in voice-enabled devices.

  • 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

Speed control 0.25-4.0

Adjust the speed parameter between 0.25 and 4.0 to control the playback rate of the generated audio. This allows IoT devices to deliver faster responses for quick commands or slower, more deliberate speech for instructions.

Typical generation speed is roughly real-time (about 25 characters per second). Requests are processed sequentially, so under heavy load, a request may wait in a queue.

Model selection tts-1/tts-1-hd

Select between tts-1 and tts-1-hd models. Both use the same underlying engine and pricing structure, offering flexibility without affecting cost or performance characteristics for standard IoT use cases.

Language and format options

Sound wave illustration for: Language and format options

The API supports 23 languages, from Arabic to Turkish. You can specify an ISO code via the language parameter for precise control, or let the system detect the language automatically from the text script.

ISO language codes

Set the language field to any of the 23 supported codes. This ensures consistent output for non-English Latin text, which defaults to English without explicit instruction.

  • Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

Auto-detection logic

If the language field is omitted, the API infers the language from the character script. Latin script text defaults to English; non-Latin scripts are mapped to their respective supported languages.

Supported audio formats

Choose mp3, wav, opus, flac, or pcm via the response_format field. MP3 offers small file sizes for IoT storage, while WAV and FLAC provide lossless quality for high-fidelity playback.

Rate limits and errors

Sound wave illustration for: Rate limits and errors

SmartSay’s API enforces strict rate limits to ensure deterministic performance for IoT devices. Each API key supports up to 60 requests per minute during normal operation. This ceiling prevents burst traffic from overwhelming the synthesis queue, which processes requests sequentially. For startups integrating voice responses into dashboards or automation hubs, understanding these limits is critical to avoiding latency spikes during peak usage.

New accounts start with a lower limit of 10 requests per minute. This constraint applies until the first top-up is processed. Once a minimum $5 USDT transfer is confirmed on the TRON network, the limit increases to 60 req/min. This structure ensures that new integrations remain stable while allowing rapid scaling as usage grows.

60 requests per minute

Standard accounts can send up to 60 requests per minute per key. Requests are processed sequentially, meaning under heavy load, synthesis may wait in a queue. Typical generation speed is roughly real-time (25 characters per second), but short phrases may take a few seconds. Plan your device triggers accordingly to avoid exceeding this window.

10 req/min for new accounts

New accounts begin with a 10 requests per minute limit. This applies immediately upon key creation. The limit increases to 60 req/min automatically within minutes after a successful top-up. This prevents new integrations from flooding the system before billing is established.

Common HTTP error codes

429 Too Many Requests: You have exceeded your current rate limit. Wait and retry with exponential backoff. 401 Unauthorized: Invalid or expired API key. Regenerate your key via the dashboard if unsure. 400 Bad Request: Missing required fields or invalid parameters. 500 Internal Server Error: Rare, but may occur if the synthesis service is temporarily unavailable. Failed requests are free, so no characters are deducted.

Rate limits and errors

Example request with curl

Sound wave illustration for: Example request with curl

The /v1/audio/speech endpoint accepts a JSON payload containing your text and voice selection. This example demonstrates a standard synchronous request for a smart home device alert, returning the audio file directly in the response body.

The response contains the binary audio data, which IoT devices can immediately pipe to their local speakers. For formats like MP3 or WAV, the Content-Type header indicates the media type, allowing seamless integration into existing audio pipelines without additional decoding steps.

Basic text input

Send a POST request to https://api.playae77.com/v1/audio/speech. The JSON body includes the model (e.g., "tts-1"), the voice preset (e.g., "atlas" for news-style alerts), and the input text string.

Ensure the input text stays within the 4096-character limit. The API processes the text and returns the synthesized audio file in the specified format, such as MP3 or WAV, ready for playback on your IoT hardware.

Audio file response

The response body contains the raw audio bytes. For MP3, the Content-Type is audio/mpeg. For WAV, it is audio/wav. Your IoT firmware should write these bytes directly to a file or stream them to the audio output driver.

If the request fails, the response will include a JSON error object with a code and message, allowing your device to retry or log the issue without consuming credits.

Headers configuration

Include Authorization: Bearer your-api-key in the request headers. Replace your-api-key with the key generated on your /get-api-key/ dashboard.

Set Content-Type: application/json to ensure the server correctly parses the text and voice parameters. Omitting this header may result in a 400 Bad Request error, halting the audio generation process.

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

SmartSay’s API mirrors the OpenAI speech endpoint structure, allowing IoT developers to leverage existing SDKs without rewriting client logic. By adjusting the base URL, teams can integrate deterministic TTS into smart home dashboards and voice-enabled devices using familiar patterns.

Set base_url parameter

Configure your SDK client to point to https://api.playae77.com/v1. This single change redirects requests to the SmartSay infrastructure while maintaining standard JSON request shapes for text-to-speech synthesis.

Standard client setup

Initialize the OpenAI client with your Bearer token (tts-...) and the custom base URL. Pass model, input, voice, and response_format as standard parameters. The SDK handles serialization automatically.

Compatibility notes

The official OpenAI SDKs work directly with this endpoint. However, SmartSay does not offer an official proprietary SDK, so you must use the OpenAI library or plain HTTP. Streaming and SSML are not supported.

Handling long texts

Sound wave illustration for: Handling long texts

Smart home devices often receive voice commands or status updates that exceed the 4096-character input limit. Your IoT backend must parse longer text strings into manageable chunks before sending them to the API to ensure successful synthesis.

4096 character limit

Each API request accepts a maximum of 4096 characters, including spaces and punctuation. If a status message or command history exceeds this threshold, the request will fail. You must split the input text into smaller segments, each staying within this limit, before invoking the speech endpoint.

  • Count characters precisely, as spaces and punctuation are included in the total.
  • Failures are free, so retrying split segments incurs no extra cost if done correctly.

Split and join strategy

Divide your long text into sequential parts, ensuring each part is under 4096 characters. Send these parts as separate POST requests to the speech endpoint. Since requests are processed sequentially, longer texts may experience slight delays due to queueing, but the system handles the load deterministically for IoT workflows.

Audio concatenation

After receiving the audio file for each segment, concatenate them in the original order. This creates a single, continuous audio stream for your device. The resulting file plays as a unified message, allowing your smart home hub to deliver long updates without interruption or loss of context.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence.

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. Node.js documentation
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. openai-node on GitHub
  5. Python documentation
  6. FFmpeg documentation
  7. LibriVox public-domain audiobooks
  8. IETF RFC 7845: Ogg Opus
  9. OpenAI API reference: create speech
  10. Creative Commons Attribution 4.0
  11. W3C WAI: making audio and video accessible
  12. MDN: Web Speech API

More on this site