How to Integrate Our TTS API into IoT Devices?

By SmartSay editorial team · Updated 2026-11-18

This guide details how to integrate the SmartSay text-to-speech API into smart home and IoT devices. We cover practical steps for selecting audio formats, managing API keys, and handling rate limits to ensure reliable audio responses. You will learn how to split long texts, optimize generation speed, and debug common issues without managing complex cloud dependencies.

Designed for IoT startups, this page provides concrete examples for voice-enabled devices, dashboards, and automation hubs. You will find specific advice on security, scaling for multiple devices, and cost optimization, ensuring your voice features remain reliable and efficient. No hype, just the technical facts you need to build a seamless audio experience.

How to Integrate Our TTS API into IoT Devices?

Frequently asked questions

What is the best audio format for IoT?

Choose MP3 for balanced file size and compatibility, or Opus for efficient bandwidth usage. WAV, FLAC, and PCM are also supported. Select the format that best fits your device’s decoding capabilities and network constraints.

How do I secure my API key?

Include the key in the Authorization header as Bearer tts-.... You can issue a new key at any time via the dashboard; the old key stops immediately. This ensures that if a key is compromised, you can revoke it instantly without waiting for a renewal cycle.

What happens if I hit the rate limit?

The limit is 60 requests per minute per key (10 before the first top-up). Exceeding this will result in failed requests. Failed requests are free, so you will not be charged for attempts that do not complete, but you may need to retry after the window resets.

Can I use the API on embedded devices?

Yes, the API is accessed via standard HTTP POST requests. Any embedded device capable of making JSON requests can use it. You do not need a proprietary SDK; simply send the text payload to the endpoint and receive the audio file directly in your application logic.

How do I handle long texts?

Split your input text into parts of up to 4096 characters per request. Generate audio for each part individually, then join the resulting audio files. This ensures compliance with the character limit while allowing you to synthesize longer content for your IoT applications effectively.

Is the API real-time?

No, it is not real-time streaming. Requests are processed sequentially, so under load, a request may wait in a queue. Typical speed is roughly real-time on long texts, but short phrases take a few seconds. You receive the complete audio file after synthesis finishes.

What SDKs are supported?

Use the official OpenAI SDKs by changing the base_url to https://api.playae77.com/v1. No proprietary SDK is provided. You can also use plain HTTP requests. The request shape matches the OpenAI speech endpoint, making integration straightforward for existing OpenAI-compatible codebases.

How do I debug integration errors?

Check the HTTP response status code and body for error details. Ensure your Authorization header is correct and the text input is under 4096 characters. Failed requests are free, so you can retry without cost. Verify your voice ID and language codes match the supported list.

Can I use multiple keys for one account?

Yes, you can issue a new key at any time. When you do, the old key stops immediately. This allows you to rotate keys for security or use different keys for different IoT devices while maintaining a single account balance and usage history.

How do I estimate costs?

The price is $10 per 1 million characters, or $0.01 per 1,000 characters. Spaces and punctuation count. Failed requests are free. You can monitor your balance and characters left on the dashboard to track usage and ensure you have sufficient funds for your IoT deployment.

What is the latency like?

Typical speed is roughly real-time for long texts, about 25 characters per second. Short phrases take a few seconds. Requests are processed one after another, so under load, a request may wait in a queue. Plan your IoT responses accordingly to avoid user-perceived delays.

Do I need a specific library?

No, you do not need a specific library. Any HTTP client can send the POST request to the endpoint. You can use standard libraries in your preferred language. The API accepts JSON bodies and returns audio files, requiring only basic network connectivity and JSON parsing.

How do I test the API?

Use the ready curl example provided on the /get-api-key/ page. You can also use the OpenAI SDKs with the adjusted base URL. Test with short texts first to verify audio quality and format. Check your balance and key validity before integrating into your production IoT devices.

Can I use this for voice assistants?

Yes, the API is suitable for voice assistants. Choose voices like nova for upbeat responses or atlas for neutral news. Ensure you handle the audio format correctly on your device. The deterministic nature of the API makes it reliable for triggering audio responses in smart home environments.

Choosing the right audio format

Sound wave illustration for: Choosing the right audio format

Selecting the correct audio format is critical for IoT devices with constrained memory and processing power. The API supports MP3, WAV, Opus, FLAC, and PCM, allowing you to balance quality against computational overhead. For most general playback scenarios, MP3 offers a good balance of file size and compatibility with standard media players found in smart displays and dashboards.

WAV provides uncompressed audio, ideal for low-level signal processing or devices that require raw data without decoding latency. Opus is optimal for bandwidth efficiency in voice-only interactions, reducing data transfer costs while maintaining clear speech quality over unstable networks.

MP3 for general playback

MP3 is the standard choice for most IoT applications, including voice assistants and notification speakers. It provides a good balance between audio fidelity and file size, ensuring smooth playback on devices with limited RAM. Most modern IoT frameworks have built-in support for MP3 decoding, making integration straightforward.

  • Compatible with most media players and IoT frameworks
  • Smaller file sizes reduce storage requirements
  • Good balance between quality and processing load

WAV for low-level processing

WAV files contain uncompressed audio data, which eliminates the need for complex decoding algorithms on the device. This makes WAV ideal for devices that need to analyze audio features in real-time or perform basic signal processing. It is also useful when the device has sufficient processing power and memory to handle larger files.

  • Uncompressed audio for immediate playback
  • Ideal for real-time audio analysis
  • Higher bandwidth and storage usage

Opus for bandwidth efficiency

Opus is highly efficient for voice transmission, making it perfect for devices connected via low-bandwidth networks like LoRaWAN or NB-IoT. It provides clear speech quality with significantly smaller file sizes compared to MP3 or WAV. This reduces data transfer costs and speeds up transmission times for remote IoT deployments.

  • Best for low-bandwidth connections
  • Highly efficient voice compression
  • Reduces data transfer costs

Managing API keys securely

Sound wave illustration for: Managing API keys securely

Securing your API key is the first step in a reliable IoT deployment. Since SmartSay issues one active key per account, protecting it prevents unauthorized audio generation and ensures accurate billing for your smart home devices.

The most robust method is storing the key in environment variables on your device or edge gateway. This keeps credentials out of your source code and version control history, reducing exposure risks during updates or deployments.

Store keys in environment variables

Embed the key in your device’s configuration layer rather than hardcoding it. This allows different devices to share a single account key securely while isolating credentials from the application logic.

Use your device’s secure storage or a dedicated secrets manager to inject the variable at runtime. This approach simplifies debugging and ensures the key is available for every POST request to the API endpoint.

  • Never commit keys to Git repositories.
  • Use environment variables for all device configurations.
  • Refresh variables during OTA updates if needed.

Rotate keys if compromised

If you suspect your key has been exposed, generate a new one immediately via the dashboard. The old key stops working at once, instantly revoking access for any compromised device or service.

Update your devices with the new key via your existing configuration management system. This immediate invalidation prevents further misuse without needing to wait for session timeouts.

  • Generate new key from dashboard.
  • Old key stops working instantly.
  • Update devices via OTA or config push.

Single key per account model

SmartSay operates on a single-key model per account, meaning all devices share the same credential. This simplifies management but requires careful monitoring of usage across your entire IoT fleet.

Since all devices draw from one balance, monitor your usage dashboard closely. If one device generates excessive audio, it affects the entire account’s availability and cost efficiency.

  • One key controls all devices.
  • Share balance across fleet.
  • Monitor total usage per account.

Handling rate limits in production

Sound wave illustration for: Handling rate limits in production

Rate limits cap your API key at 60 requests per minute, dropping to 10 per minute for new accounts before the first top-up. For IoT devices sending frequent status updates, exceeding this limit results in immediate request failures, though failed requests remain free of charge. Monitoring your usage dashboard helps you stay within these bounds without unexpected service interruptions.

To maintain reliability, you must implement robust retry logic and queue management. Since requests are processed sequentially, under load a request may wait in a queue, so your device should handle temporary 429 errors gracefully. Avoid hammering the API with parallel requests from a single key; instead, batch or throttle outgoing synthesis jobs to match the 60 req/min ceiling.

Monitor requests per minute

Track your character usage and request count via the /v1/voices and account dashboard. This data helps you predict when you might hit the 60 requests per minute limit, especially during peak hours when multiple smart home hubs are active simultaneously.

For startups managing dozens of devices, consider aggregating text requests or reducing frequency to stay well under the 10 req/min initial threshold until your account is funded.

  • Check balance and usage stats on /get-api-key/.
  • Use the official OpenAI SDK with a custom base_url for easy integration.

Implement retry logic

When a 429 Too Many Requests error occurs, implement exponential backoff. Retry after a short delay, ensuring you do not exceed the 60 requests per minute limit per key. Since failed requests are free, you can retry without incurring extra costs if the synthesis fails for other reasons.

Remember that requests are processed one after another. If the queue is long, your retry might still fail. Set a reasonable timeout to avoid blocking your device’s UI.

  • Retry on 429 with exponential backoff.
  • Failed requests incur no charge.

Queue management strategies

For IoT devices, pre-generate audio for common responses (e.g., 'Door locked', 'Temperature adjusted') and store them locally. This reduces the load on the API and ensures instant playback. For dynamic text, queue requests in memory and process them sequentially to stay within the 60 req/min limit.

If you need higher throughput, issue a new API key via the dashboard. The old key stops immediately, allowing you to run parallel services with separate rate limits, though you’ll need to manage key rotation in your device firmware.

  • Pre-generate common phrases.
  • Use new keys for parallel services.

Processing long text responses

Sound wave illustration for: Processing long text responses

IoT devices often receive lengthy status updates or narrative instructions that exceed the 4096-character limit per API request. To handle these, you must split the input text into manageable chunks before sending them to the endpoint.

Each chunk is processed independently, ensuring that a single large response does not block the device’s audio buffer. This approach allows for seamless playback even when the source text is extensive.

Split text into chunks

Divide the input string at logical boundaries, such as sentence ends, ensuring no chunk exceeds 4096 characters. Spaces and punctuation count toward this limit.

If a single sentence is too long, split it by character count to guarantee valid requests. This prevents partial audio generation errors.

  • Maximum 4096 characters per request
  • Count spaces and punctuation
  • Split at sentence boundaries where possible

Generate audio segments

Send each chunk to the POST https://api.playae77.com/v1/audio/speech endpoint. The API returns an audio file for each request.

Since requests are processed sequentially, longer texts may queue. Monitor the response time to adjust your device’s buffering strategy accordingly.

  • Use tts-1 or tts-1-hd models
  • Receive audio file in response
  • Respect the 60 requests/minute limit

Concatenate audio files

Once all segments are generated, combine them into a single continuous audio file. Most IoT frameworks support standard concatenation for formats like WAV or MP3.

Ensure the audio format is consistent across all segments to avoid playback glitches during the join process.

  • Maintain consistent response_format
  • Use standard concatenation libraries
  • Verify seamless playback

Testing latency and performance

Sound wave illustration for: Testing latency and performance

To understand performance limits, recognize that synthesis is not instantaneous. Short phrases take a few seconds, while long texts generate at roughly real-time speed (25 characters per second). This predictability suits smart home dashboards where users expect audio after a brief, predictable delay rather than live streaming.

Under load, requests are processed sequentially. If your IoT hub sends multiple simultaneous commands, a request may wait in a queue. Monitoring this latency ensures your device UI reflects the actual processing state, preventing user frustration during high-traffic automation events.

Real-time generation speed

Generation speed scales with text length. A 100-character response might take 4–5 seconds, while a 4000-character story takes about 160 seconds. This linear relationship allows you to set precise timeout values in your IoT firmware. Avoid expecting sub-second responses for complex sentences.

Note that short phrases do not benefit from the real-time speed advantage. They incur a fixed overhead of a few seconds. Design your voice responses to be concise to minimize perceived latency for quick status updates like 'door locked' or 'light on'.

  • Expect ~4 seconds for 100 characters.
  • Approx. 25 characters generated per second for long texts.
  • Short phrases have higher relative latency due to overhead.

Queue wait times

Requests are processed one after another. If you exceed the rate limit or send burst requests, subsequent calls wait in a queue. This can significantly increase total time-to-audio during peak hours. Monitor your queue depth to identify bottlenecks in your device fleet.

The 60 requests per minute limit per key is a hard constraint. If you deploy many devices sharing one key, queue times will rise. Distribute keys across device groups or stagger requests to keep queue waits under 10 seconds for consistent user experience.

  • Requests are processed sequentially.
  • Queue times increase under load.
  • 60 requests/minute limit per key.

Optimization tips

Pre-generate common responses for static commands like 'good morning' or 'weather report'. Store the MP3 files locally on your IoT device or edge server. This eliminates API latency entirely for frequent interactions, reserving the API for dynamic, variable content.

Use the speed parameter to adjust playback rate. Increasing speed to 1.5x reduces listening time but does not affect generation time. Test different speeds with your target audience to balance clarity and brevity for smart home announcements.

  • Cache static responses locally.
  • Use speed adjustment for playback control.
  • Monitor queue depth for scaling insights.

Debugging common integration issues

Sound wave illustration for: Debugging common integration issues

When integrating SmartSay’s TTS API into IoT devices, developers often encounter predictable hurdles. Most issues stem from misconfigured headers or incorrect parameter values. This section addresses the three most frequent debugging scenarios to help you restore audio playback quickly.

Ensure your device’s network stack handles HTTPS correctly and that the API key is transmitted without whitespace errors. A clean request structure prevents the majority of silent failures in embedded environments.

Authentication errors

Verify the Authorization: Bearer header contains only the key string, without quotes or extra spaces. If the key was rotated, ensure the old key is no longer in use. A 401 error indicates the key is invalid or expired.

  • Check for trailing newlines in the API key string.
  • Ensure the key starts with tts-.
  • Confirm the request is sent over HTTPS, not HTTP.

Invalid voice IDs

The API returns a 400 error if you use a voice name not in the official list. Ensure you are using one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Case sensitivity matters for some implementations.

  • Call GET /v1/voices to verify available voices.
  • Double-check spelling: atlas not atlas-1.
  • Ensure the voice supports the specified language.

Format mismatches

Specify response_format as mp3, wav, opus, flac, or pcm. If your device expects PCM but receives MP3, playback will fail. Ensure your device’s audio decoder matches the requested format. Mismatched formats cause silent audio errors or corrupted files.

  • Use wav for raw audio processing.
  • Use mp3 for general playback.
  • Use opus for bandwidth efficiency.

Scaling for multiple devices

Sound wave illustration for: Scaling for multiple devices

Scaling your TTS integration across multiple IoT devices requires a disciplined approach to API key management and cost forecasting. Since each account holds only one active key, rotating it ensures that compromised credentials do not disable your entire device fleet simultaneously. This single-key model simplifies billing but demands careful tracking of usage across all connected hardware.

Key rotation strategies

Rotate your API key immediately if security is compromised; the old key stops working at once. Issue a new key via your dashboard to restore service. Implement a staggered rotation schedule where devices update their keys in batches to avoid simultaneous network spikes during the transition period.

  • Rotate keys via the /get-api-key/ dashboard
  • Old key invalidates immediately upon new issuance
  • Stagger device updates to prevent network congestion

Monitoring usage

Track your character consumption and request count daily to stay within the 60 requests per minute limit. Use the usage data available in your account dashboard to identify high-frequency devices. This data helps you adjust retry logic or cache responses for common alerts before they hit the API.

  • Monitor requests per minute per key
  • Track character count against $0.01/1000 chars pricing
  • Identify high-frequency devices for caching opportunities

Cost estimation models

Calculate costs based on the total character count, including spaces and punctuation. With a rate of $10 per million characters, even small voice prompts accumulate over thousands of devices. Factor in the free trial credit if using new email accounts, but budget primarily for USDT top-ups on the TRON network.

  • Rate: $0.01 per 1,000 characters
  • Payment via USDT (TRC-20) on TRON
  • Minimum top-up: $5
Scaling for multiple devices

Security considerations

Sound wave illustration for: Security considerations

Security is foundational for IoT deployments where devices operate in untrusted networks. Ensuring secure communication and proper credential management protects both your infrastructure and user data from common exploitation vectors.

HTTPS only

All API requests must use HTTPS. Our endpoint https://api.playae77.com/v1 enforces this, ensuring encryption in transit for your voice commands and responses.

Key exposure risks

Your API key authenticates all requests. Store it in environment variables on your device, not in hardcoded source code. Since only one active key exists per account, rotate it immediately via the dashboard if exposed, rendering the old key invalid instantly.

  • Use environment variables, not hardcoded strings.
  • Rotate keys via dashboard to invalidate old ones immediately.
  • Monitor usage for unusual activity.

Data privacy basics

Input text is used solely to generate audio and is not used for training models. Generated audio is returned in the response and not stored by our servers, minimizing data retention risks for your smart home devices.

Choosing voices for user experience

Sound wave illustration for: Choosing voices for user experience

Selecting the right voice is critical for smart home devices where audio clarity and tone define the user experience. With eight distinct presets, you can align the synthetic voice with your brand’s personality, ensuring consistency across dashboards and automation hubs.

The API supports 23 languages, allowing each voice to speak any supported language. This flexibility ensures that your IoT ecosystem feels native to users globally, whether they are in Tokyo, Berlin, or São Paulo.

Matching voice to brand

Your device’s personality should match its function. Use Atlas for neutral, news-style updates or Orion for deep, documentary-style narration. For more energetic interactions, Felix or Nova provide bright, upbeat tones suitable for reminders and alerts.

Sage offers calm, instructional clarity ideal for step-by-step guides, while Luna’s soft storytelling voice suits ambient or entertainment modes. Aria provides a warm, clear narrator experience for general assistance tasks.

  • Use Atlas for neutral, factual responses.
  • Choose Orion for deep, documentary tones.
  • Select Felix or Nova for energetic alerts.

Neutral vs. expressive voices

Neutral voices like Atlas minimize distraction during critical information delivery, ensuring the content remains the focus. Expressive voices like Luna or Nova add emotional nuance, making repetitive tasks feel more engaging and less robotic.

Each voice is based on licensed recordings from LibriVox. The inaudible watermark marks each file as synthetic, maintaining transparency without affecting the auditory experience.

  • Neutral voices reduce cognitive load.
  • Expressive voices enhance engagement.
  • All voices use licensed source material.

Testing with users

Conduct A/B tests with different voices to see which resonates best with your target audience. Consider the context: a kitchen assistant might benefit from a warmer tone, while a security system might prefer a clear, authoritative voice.

Remember that voices can speak any of the 23 supported languages. Test language detection accuracy and explicit language settings to ensure consistent performance across diverse user groups without manual intervention.

  • A/B test voice preferences.
  • Consider context for tone selection.
  • Test language detection accuracy.

Handling language detection

Sound wave illustration for: Handling language detection

Determining the correct language is critical for accurate synthesis in smart home devices. Our API automatically infers the language from the text script, defaulting to English for Latin-script input if unspecified. This simplifies integration for single-language deployments but requires explicit configuration for mixed environments.

For precise control, you can pass the language parameter with an ISO code. This ensures consistent output regardless of the input text's dominant script, preventing unexpected voice behavior in devices supporting multiple regional variants.

Auto-detection behavior

The system analyzes the input text to guess the language. If the language field is omitted, Latin characters default to English. This works well for monolingual devices but may misidentify mixed-language prompts common in multilingual households.

  • Defaults to English for Latin script
  • Analyzes script to infer language
  • No manual configuration needed for single languages

Explicit language setting

Specify the language parameter (e.g., es, fr, de) to force a specific language. This overrides auto-detection and ensures deterministic results, which is essential for devices in standardized automation hubs where voice consistency matters.

  • Pass ISO code in request body
  • Overrides automatic guessing
  • Ensures consistent voice output

Multi-language support

Supports 23 languages including Arabic, Chinese, Hindi, and Swahili. Any voice can speak any supported language, allowing you to use a single voice preset across different regions without managing multiple voice assets. Unsupported languages like Vietnamese or Thai are rejected.

  • 23 supported languages
  • Any voice speaks any supported language
  • Vietnamese, Thai, and Ukrainian are not supported

Error handling best practices

Sound wave illustration for: Error handling best practices

When an IoT device sends a text-to-speech request, transient network glitches or server-side congestion can cause failures. Implementing robust error handling ensures your smart home hub doesn’t stall when a voice response is delayed or lost.

By systematically logging error codes and designing user feedback loops, you maintain a seamless experience even when the API returns non-successful status codes. This approach allows devices to gracefully degrade or retry without confusing the end user.

Retry failed requests

Implement exponential backoff for transient errors like 429 (rate limit) or 503 (service unavailable). Since requests are processed sequentially, a brief pause often resolves queue congestion. Avoid immediate aggressive retries to prevent overwhelming the API during peak loads.

  • Retry on 429 with increasing delays
  • Retry on 503 or 500 errors
  • Stop retrying after 3 attempts on 4xx errors

Log error codes

Capture the HTTP status code, request ID, and timestamp for every failed synthesis attempt. This metadata is crucial for diagnosing whether the issue stems from your IoT device’s network, an invalid voice ID, or a temporary API outage. Store these logs locally if possible, as they aid in debugging without relying on external services.

  • Record HTTP status codes
  • Include request IDs for traceability
  • Log timestamp and voice parameter used

User feedback loops

When synthesis fails, provide immediate but non-intrusive feedback to the user. For example, a smart speaker might play a generic "unavailable" tone or display a small notification on a dashboard. This informs the user that the system is working, even if the specific voice response couldn’t be generated, maintaining trust in the device’s reliability.

  • Play a generic error tone
  • Show a status icon on the dashboard
  • Offer a manual retry option

Cost optimization strategies

Sound wave illustration for: Cost optimization strategies

Optimizing your IoT audio pipeline requires careful management of character usage and response handling. Since billing is based on character count, reducing redundant text generation can significantly lower operational costs for high-volume devices.

Caching common responses

Store frequently used audio files locally on devices or edge servers. For static phrases like "door locked" or "battery low," fetch once and play from local storage, avoiding repeated API calls and unnecessary character consumption.

Limiting character count

Each request supports up to 4096 characters. Keep input text concise to avoid unnecessary overhead. Since spaces and punctuation count as characters, trim whitespace carefully. Failed requests are free, so verify text validity before sending.

Efficient text formatting

Use simple, clear sentences to reduce processing time. Avoid complex structures that might require longer generation times. Since typical speed is roughly 25 characters per second, shorter texts complete faster, reducing queue wait times and improving user experience.

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. W3C WAI: making audio and video accessible
  3. LibriVox public-domain audiobooks
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. MDN: Web Speech API
  6. IETF RFC 7845: Ogg Opus
  7. Node.js documentation
  8. TRON developer hub: TRC-20
  9. LibriTTS-R corpus (OpenSLR 141)
  10. openai-python on GitHub
  11. openai-node on GitHub
  12. Python documentation

More on this site