Frequently asked questions
What is the best audio format for IoT devices?
Choose MP3 for balanced quality and file size, or PCM for uncompressed raw audio. MP3 is widely supported by media libraries. If bandwidth is critical, Opus offers efficient compression. FLAC provides lossless compression. Select the format that your device’s audio decoder supports natively to minimize CPU usage during playback.
How do I store the API key securely in firmware?
Store your single active Bearer token in secure hardware storage or the device’s keychain. Since you can issue a new key at any time, rotate it regularly by generating a fresh key in the dashboard. The old key stops immediately, ensuring that compromised keys from older firmware builds cannot access your account.
Can IoT devices handle MP3 playback natively?
Most modern IoT microcontrollers and Linux-based gateways support MP3 decoding via lightweight libraries like libmad or FFmpeg. For bare-metal systems, ensure your build environment includes an MP3 decoder. If your hardware lacks hardware acceleration, consider using PCM for lower CPU overhead, though file sizes will be larger.
How does latency affect user experience in smart speakers?
Latency depends on network speed and server queue depth. Short phrases take a few seconds to generate. Longer texts process at roughly real-time speed. Under load, requests may wait in a queue, increasing delay. Design your UI to show a loading state during this generation phase to manage user expectations effectively.
What is the maximum payload size for a request?
Each API request supports up to 4096 characters of input text. If your notification exceeds this limit, split the text into chunks of 4096 characters or fewer. Generate audio for each part separately and join the resulting audio files on the device or backend before playback to ensure seamless delivery.
How do I handle network drops during generation?
Since the API returns the full audio file, a network drop after generation completes does not affect the audio. If the connection fails during transfer, simply retry the request. Failed synthesis requests are free, so retrying is cost-effective. Ensure your firmware handles HTTP errors gracefully and implements exponential backoff for retries.
Is WebSocket supported for real-time audio?
No, WebSocket is not supported. The API uses standard HTTP POST requests to return complete audio files. You cannot receive partial audio chunks in real-time. Design your firmware to buffer the entire response before starting playback.
Can I play multiple voices sequentially?
Yes, you can generate audio files for different voices like Aria, Nova, or Felix and play them in sequence. Each request produces a separate audio file. Your firmware can queue these files and play them one after another, allowing for dynamic voice changes within a single notification or announcement sequence.
How do I calculate costs for batch notifications?
Cost is $0.01 per 1,000 characters, including spaces and punctuation. Multiply your total character count by this rate. Failed requests are free, so only successful generations incur charges. Monitor your usage dashboard to track characters consumed and ensure your budget aligns with your notification volume and frequency requirements.
What is the difference between PCM and MP3?
PCM is an uncompressed, raw audio format resulting in larger file sizes but simpler decoding. MP3 is a compressed format that reduces file size significantly, saving bandwidth and storage, but requires more CPU power to decode. Choose PCM for low-power devices with ample storage, and MP3 for bandwidth-constrained environments.
Do I need a specific library for decoding audio?
You need a library compatible with your chosen format. For MP3, use a compatible decoder. For Opus, use a compatible decoder. For PCM, no decoding library is needed; you can write raw bytes directly to the DAC. Ensure your firmware includes these libraries in the build process to handle the selected audio format correctly.
How do I test my integration before production?
Use the free trial credit of $0.50 (50,000 characters) provided upon Google sign-in. Test various voices, languages, and formats. Verify latency and file integrity. Use the provided curl example to validate your HTTP client implementation. Monitor the usage dashboard to ensure charges are applied correctly and to check for any request errors.
What happens if the device has no internet?
The device cannot generate new audio or fetch files. It must rely on pre-downloaded audio files stored locally. Since the API does not store generated audio, you must handle caching and storage management in your firmware or backend. Ensure your device can operate in offline mode using previously generated audio assets.
Can I use this API for voice commands?
This is a text-to-speech API, not speech-to-text. It converts text into audio. You can use it to generate audio responses to voice commands, but you need a separate speech recognition service to convert user speech into text. Combine this TTS API with a STT service for a complete voice interaction loop.
Prerequisites for IoT Devices
Ensure your IoT device maintains a stable internet connection, as the API requires consistent connectivity for POST requests. The endpoint https://api.play8055.com/v1/audio/speech must be reachable from your device’s network environment without excessive latency.
Network Connectivity
A reliable connection is essential since requests are processed sequentially. Ensure your device can sustain the connection long enough to receive the full audio file without dropping, which would result in a failed request and no charge.
- Stable Wi-Fi or cellular connection
- Minimal packet loss for reliable transfers
API Key Storage
Store your Bearer token securely within your firmware or backend. Since each account has one active key, ensure it is protected from unauthorized access. You can issue a new key at any time via the dashboard if needed.
- Use secure storage for the
tts-...key - Rotate keys via /get-api-key/ if compromised
Audio Codec Support
Your device must support the requested response_format. Common choices include mp3 for broad compatibility or pcm for raw, uncompressed audio. Ensure your audio library can decode the selected format before sending the request.
- Support for mp3, wav, opus, flac, or pcm
- Verify codec compatibility in your firmware
Making the First Request
To generate speech, send a POST request to https://api.play8055.com/v1/audio/speech with a JSON body. The payload requires model ("tts-1" or "tts-1-hd"), input (text under 4096 characters), voice (one of 8 presets), and response_format.
Constructing the JSON Body
Include optional parameters like speed (0.25–4.0) and language (ISO code) if needed. Ensure input does not exceed 4096 characters to avoid truncation. The API accepts standard formats like mp3, wav, opus, flac, or pcm.
- Use
tts-1for standard quality ortts-1-hdfor higher fidelity. - Specify
languagefor non-English Latin scripts to prevent incorrect voice selection. - Set
speedbetween 0.25 and 4.0 to adjust playback rate.
Sending POST Request
Include the Authorization: Bearer tts-... header with your API key. The endpoint processes requests sequentially, so under load, expect queuing delays. Typical generation speed is roughly 25 characters per second.
- Use HTTPS for secure transmission of your bearer token.
- Keep requests under the 60 requests-per-minute rate limit.
Receiving Audio Data
The response returns the audio file directly in the body. Failed requests return an error code without charge. For IoT firmware, handle the binary stream efficiently to minimize memory usage during download.
- Check HTTP 200 for successful synthesis.
- Verify the
Content-Typematches your requested format.

Handling Audio Playback
Once your device receives the audio payload, the format determines how you handle playback. MP3 files require a decoder, adding CPU overhead, while PCM provides raw I2S-ready samples that bypass decoding entirely. Choose PCM for low-power microcontrollers and MP3 for higher-level processors with existing libraries.
MP3 vs PCM Streams
MP3 offers significant bandwidth savings but requires processing power to decode. PCM data is uncompressed and ready for direct output to your DAC or I2S peripheral, ideal for resource-constrained IoT nodes.
- MP3: Requires decoding library; saves ~90% bandwidth.
- PCM: Raw samples; immediate playback; higher bandwidth.
Buffer Management
Implement a circular buffer to decouple network reception from audio playback. This prevents buffer underruns if network latency spikes, ensuring smooth audio output even during temporary connectivity drops.
- Use double-buffering for seamless transitions.
- Pre-allocate memory to avoid heap fragmentation.
Playback Latency
Short phrases typically take a few seconds to generate. Account for this delay in your user experience design. Real-time generation on long texts maintains a 1:1 ratio, but queueing under load may add seconds.
Optimizing for Bandwidth
Reducing bandwidth consumption is critical for IoT devices with limited data plans or unstable connections. By selecting efficient audio formats, you can significantly decrease the payload size without compromising intelligibility, ensuring faster transmission and lower power usage during playback.
Using Opus Format
Opus provides superior compression compared to MP3 or WAV, often reducing file size by 50% or more while maintaining high audio quality. This is particularly useful for long-form text generation where storage and transfer costs add up.
Compressing Responses
Ensure your HTTP client supports gzip or deflate compression for both the request and response bodies. While the API returns raw audio, compressing metadata or additional JSON fields can further reduce network overhead.
Minimizing Payload Size
Limit the input field to the necessary characters, as each character counts toward the 4096 limit and billing. Use binary transfer modes (like PCM or Opus) directly into your audio buffer to avoid unnecessary base64 encoding/decoding steps in firmware.
Error Recovery in IoT
Network interruptions are common in IoT deployments. Your firmware should implement robust timeout handling to detect when the TTS API is unreachable. Use a reasonable timeout window (e.g., 5–10 seconds) to avoid hanging indefinitely on a silent failure.
When a request fails, do not immediately assume permanent error. Implement exponential backoff with jitter for retries. This prevents overwhelming the API’s 60 requests/minute limit during recovery periods and handles transient network blips effectively.
Network Timeout Handling
Set explicit socket timeouts in your HTTP client. If the API does not respond within the set duration, treat the request as failed. This prevents your device from waiting indefinitely for a response that will never arrive, freeing up resources for other tasks.
Use non-blocking I/O where possible. If the connection drops mid-request, ensure the buffer is cleared to avoid memory leaks or corrupted audio state in your playback engine.
- Set HTTP client timeout to 5-10 seconds.
- Use non-blocking I/O to prevent hanging.
- Clear buffers on connection drop to avoid memory leaks.
Retry Logic
Implement exponential backoff with jitter for retries. Start with a short delay (e.g., 1 second) and double it for subsequent attempts, up to a maximum retry count (e.g., 3 attempts). This respects the 60 requests/minute rate limit while ensuring eventual success.
Do not retry failed requests indefinitely. After exhausting retries, log the error and proceed to a fallback strategy. This ensures your device remains responsive even if the API is temporarily unavailable.
- Use exponential backoff with jitter.
- Limit retries to 3 attempts.
- Respect the 60 requests/minute rate limit.
Fallback Strategies
If retries fail, consider storing the text locally and playing a pre-downloaded alert tone. This ensures the user receives immediate feedback, even if the TTS service is down. Once connectivity is restored, you can optionally send the queued text for processing.
Alternatively, use a simpler, lower-bandwidth audio format like PCM for fallback playback if Opus decoding fails. This reduces CPU load and memory usage during error recovery, ensuring basic functionality is maintained.
- Store text locally and play a pre-downloaded alert tone.
- Use PCM for fallback playback if Opus fails.
- Reduce CPU load during error recovery.
Security Best Practices
Secure audio generation in IoT requires careful handling of credentials and transport. Since each account holds one active API key, protecting it from extraction is critical for preventing unauthorized usage and billing surprises.
All requests must use HTTPS to encrypt the bearer token and audio payloads in transit. This prevents network sniffing from exposing your credentials or generated speech content on untrusted networks.
Storing Bearer Tokens
Store the tts-... key in non-volatile memory or secure element, not in plain text config files. Avoid logging the key in debug output.
Use the key in the Authorization: Bearer header for every POST request. Do not embed the key in URL parameters where it may appear in logs.
- Keep the key in secure storage, not plain text
- Use the Authorization header for all requests
- Avoid logging the key in debug output
HTTPS Usage
Ensure your firmware enforces TLS 1.2 or higher for all API calls to api.play8055.com. This encrypts both the JSON request and the returned audio file.
Verify the server certificate to prevent man-in-the-middle attacks, especially if devices connect via public Wi-Fi or cellular networks.
- Enforce TLS 1.2 or higher
- Verify server certificates
- Encrypt request and response data
Key Rotation
Generate a new key via the dashboard whenever you suspect a leak. The old key stops working immediately, so update your firmware configuration promptly.
Since only one key is active per account, ensure all devices or backend services use the same updated key to maintain consistent access.
- Generate new keys via dashboard
- Old keys stop working immediately
- Update all devices with the new key
Scaling for Multiple Devices
Managing rate limits is critical when deploying IoT devices at scale. Each API key allows 60 requests per minute, which may bottleneck large fleets if every device requests audio independently. You must design your backend to distribute these 60 requests across your connected devices efficiently.
To handle this, implement local request queuing on your gateway or server. Group short status updates or batch multiple notifications into single requests where possible to reduce the total count. This ensures your devices stay within the 60 RPM limit without unnecessary delays.
Rate Limit Management
Monitor your usage dashboard to track requests per key. If you exceed 60 RPM, requests are queued and processed sequentially, increasing latency. Use the GET /v1/voices endpoint to understand available voices and optimize payload size.
If you need higher throughput, consider issuing multiple API keys. Since each key has its own 60 RPM limit, distributing devices across several keys allows linear scaling. Remember that a new key invalidates the old one immediately, so plan your rotation strategy carefully. Since each account has only one active key, you cannot use multiple keys simultaneously for the same account.
- Limit is 60 requests per minute per key
- Requests queue automatically if limit is exceeded
- Multiple keys enable higher aggregate throughput
Request Queuing
Implement a local queue in your device firmware or IoT gateway. Store TTS requests when the API is busy or rate-limited. Prioritize critical alerts over routine status reports to ensure important notifications are delivered first.
Use the speed parameter (0.25–4.0) to adjust generation time. Faster speeds reduce CPU load on the device and decrease the time the audio file is held in memory. This helps manage buffer constraints on low-power devices.
- Queue requests locally if API is slow
- Prioritize critical alerts over routine updates
- Use
speedparameter to reduce generation time
Load Distribution
Distribute load across your backend services or IoT gateways. Use round-robin or least-connections algorithms to spread requests across multiple API keys. This prevents any single key from hitting the rate limit too quickly.
Monitor character usage closely. Since pricing is based on character count ($0.01 per 1,000 characters), distributing load also helps manage costs. Ensure your devices send concise text to minimize bandwidth and processing time.
- Use round-robin across multiple API keys
- Monitor character usage for cost management
- Send concise text to reduce bandwidth
Debugging Integration Issues
Debugging integration issues often starts with inspecting the HTTP response codes returned by the API. A 400 error typically indicates a malformed request, such as an invalid model name or incorrect character encoding. A 429 response signals that you have exceeded the rate limit of 60 requests per minute, requiring you to implement backoff logic in your firmware.
Another common issue is character count validation. The API rejects inputs exceeding 4096 characters per request. Ensure your code splits long texts into valid chunks before sending them, as this prevents silent failures or truncated audio output during playback.
Checking Response Codes
Always log the HTTP status code alongside the request payload. Use 4xx codes to correct immediate input errors, such as invalid voice IDs or unsupported formats. Use 5xx codes to identify transient server issues that may require a retry.
For persistent failures, verify that your authorization header is correctly formatted as Authorization: Bearer tts-.... Missing or malformed tokens result in 401 errors, which are often mistaken for network connectivity issues.
- 400: Invalid input (e.g., text too long)
- 401: Unauthorized (check Bearer token)
- 429: Rate limit exceeded (60 req/min)
- 500-503: Server errors (retry with backoff)
Validating Character Count
The API enforces a strict 4096-character limit per request. Your firmware must split longer strings into smaller segments before submission. Remember that spaces and punctuation count toward this limit.
Ensure your splitting logic preserves word boundaries where possible to avoid awkward pauses in the generated audio. Validate the input length before sending to avoid wasting API credits on failed requests.
- Max 4096 characters per request
- Spaces and punctuation count
- Split strings at word boundaries
- Validate before sending
Verifying Voice IDs
Use the GET /v1/voices endpoint to confirm available voice IDs. Ensure your firmware uses one of the eight supported presets: aria, nova, luna, sage, felix, milo, atlas, or orion.
Incorrect voice IDs result in 400 errors. Double-check that the voice name matches the API's expected format exactly, including case sensitivity, to prevent integration failures during initial setup.
- Use GET /v1/voices
- 8 supported presets only
- Check case sensitivity
- Avoid typos in voice names
Testing in Development
Testing your integration locally ensures your firmware handles API responses correctly before field deployment. The free trial provides $0.50 in credit, allowing you to generate approximately 50,000 characters of audio without financial risk. This is sufficient to validate your endpoint configuration and audio parsing logic.
Simulate poor network conditions by introducing artificial latency or packet loss. This helps verify that your retry logic and buffer management handle interruptions gracefully, ensuring the device does not hang or corrupt audio data during playback.
Using the Free Trial
Sign in with Google to receive $0.50 in trial credit, valid for 7 days. This allows you to test the full range of 8 voices and 5 audio formats without immediate payment setup. Use this period to verify character counting and speed adjustments.
Note that email/password accounts do not receive trial credit. Ensure your development account is created via Google to access this testing budget. Failed requests remain free, so you can safely experiment with different parameters.
- Valid for 7 days after Google sign-in
- Approximately 50,000 characters of audio
- No payment method required initially
Simulating Network Conditions
Use tools like tc on Linux or network emulation on your router to introduce latency and packet loss. This mimics the unstable connections common in industrial IoT environments. Test how your firmware handles partial responses and timeouts.
Verify that your device correctly resumes playback or retries the request after a network drop. Ensure that audio buffers do not overflow or underflow during simulated interruptions.
- Introduce 500ms-2s latency
- Simulate 5% packet loss
- Test timeout handling at 10s
Automated Testing Scripts
Write scripts that send a sequence of texts with varying lengths and voices to the API. Parse the response headers to verify character counts and status codes. This ensures consistent behavior across different voice models and response formats.
Include checks for rate limits (60 requests per minute) to ensure your script does not exceed the quota during testing. Log all responses for later analysis of latency and error rates.
- Automate 100+ request cycles
- Validate JSON response structure
- Log latency and error rates
Production Deployment
Once your IoT devices are generating speech in the field, consistent monitoring ensures you stay within the 60 requests per minute rate limit. Track your API key usage via the dashboard to prevent unexpected throttling, especially as device fleets grow.
Monitoring Usage
Use the dashboard to track character consumption and request status. Since audio generation takes time, monitor queue delays during peak hours to ensure timely playback on your devices.
- Track character usage per device fleet
- Monitor request queue latency
- Verify balance remains sufficient for ongoing operations
Alerting on Limits
Set up alerts for when usage approaches the 60 requests/minute threshold. If a single device spikes, consider implementing local request queuing to smooth out bursts and avoid hitting the rate limit.
- Alert on approaching rate limits
- Implement local queuing for burst traffic
- Monitor balance expiration for trial accounts
Updating Firmware
Include voice ID and language code validation in your firmware updates to prevent errors from deprecated configurations. Ensure HTTPS is enforced for all API calls to maintain security as you scale.
- Validate voice IDs in firmware configs
- Enforce HTTPS for API calls
- Test updates with small device batches first
Common Firmware Challenges
IoT devices often run with tight memory budgets, making it difficult to buffer large audio files. You must manage input text splitting carefully, keeping payloads under 4096 characters to fit within your device’s RAM limits during synthesis and decoding.
Efficient memory management ensures your firmware remains stable even when processing multiple speech requests sequentially without crashing due to heap exhaustion.
Memory Constraints
Limit each request to 4096 characters to minimize payload size. Use chunked transfer if your hardware supports it, though our API returns complete files.
Pre-allocate fixed buffers for MP3 or PCM data to avoid dynamic memory fragmentation during high-frequency TTS operations.
- Keep input text under 4096 characters per request.
- Pre-allocate fixed-size buffers for audio data.
- Avoid dynamic memory allocation during playback.
CPU Usage for Decoding
Decoding MP3 or Opus formats can be CPU-intensive on low-end microcontrollers. Consider using PCM for simpler decoding if your bandwidth allows, or ensure your CPU supports hardware-accelerated audio decoding.
Plan for queue wait times, as requests are processed sequentially, which may increase CPU load if you poll frequently.
- Use PCM for low-CPU decoding if bandwidth permits.
- Leverage hardware audio decoders if available.
- Minimize polling frequency to reduce CPU overhead.
Power Consumption
Continuous network activity and audio decoding drain battery life quickly. Optimize by batching requests or reducing speech frequency during idle periods.
Select lower bitrate formats like Opus to reduce transmission time and radio on-time, indirectly saving power.
- Batch requests to reduce radio on-time.
- Use Opus to minimize transmission duration.
- Reduce speech frequency during idle states.

Support and Resources
Access the full API reference, including request schemas and error codes, via our dedicated documentation page. This resource covers all endpoints and provides ready-to-use code snippets for common languages.
For technical issues or billing questions, our support team is available via email only. We do not offer live chat or phone support, so please include your API key and device logs in your message for faster resolution.
Documentation Links
The /docs/ page contains the complete API specification, including voice parameters, supported formats, and rate limit details. Use this as your primary reference for integration.
- Full API Reference
- Voice Parameter Guide
- Error Code List
Email Support
Send inquiries to [email protected]. Include your API key and relevant logs to help us diagnose issues quickly. Response times vary based on queue volume.
Community Examples
Check the /about/ page for links to community-shared firmware libraries and integration guides contributed by other IoT developers.
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.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- Creative Commons Attribution 4.0
- openai-node on GitHub
- FFmpeg documentation
- LibriVox public-domain audiobooks
- LibriTTS-R corpus (OpenSLR 141)
- openai-python on GitHub
- TRON developer hub: TRC-20
- ISO 639 language codes
- OpenAI API reference: create speech
- IETF RFC 7845: Ogg Opus
- LibriTTS-R paper (arXiv 2305.18802)
