Frequently asked questions
What hardware do I need for IoT TTS?
Any device capable of running HTTP requests and playing audio files is sufficient. You need a network connection to reach https://api.k665.info/v1 and a speaker or audio output interface. No specialized voice hardware or proprietary chips are required, as the API returns standard audio formats like MP3 or WAV.
How do I store API keys securely?
Store your single active Bearer key in your device’s secure environment variables or secure storage. Since one new key immediately invalidates the old one, you can rotate keys remotely if needed. Avoid hardcoding the key in plain text within your application binary or configuration files accessible to users.
Can I play audio directly from the API?
The API returns the audio file in the response body, not a stream. You must download the complete file to your device’s memory or storage, then play it using your local audio player. There is no WebSocket or streaming endpoint, so you handle the file locally after retrieval.
What is the best format for IoT devices?
MP3 is generally recommended for balancing quality and file size, while PCM offers uncompressed quality for simple players. WAV and OPUS are also supported. Choose based on your device’s decoder capabilities and storage constraints. FLAC is available for lossless needs, but MP3 remains a universally compatible choice.
How do I handle network drops?
Since the API returns complete files, a drop during download means you have an incomplete file. Implement retry logic to re-fetch the audio. For long texts, split them into parts under 4096 characters, download each part, and join them locally. This ensures partial failures do not corrupt the entire output.
Can I cache audio files?
Yes, you can store generated audio files locally on your device to avoid repeated API calls for identical text. Since the API does not store generated audio, caching is entirely up to your implementation. This reduces latency and API usage costs, especially for repetitive prompts or system sounds.
How do I switch languages dynamically?
Include the optional language field in your JSON request body with the ISO code (e.g.,
What if the API goes down?
The API has no SLA or uptime guarantee. If it is down, your device must handle the error gracefully, perhaps by playing a local fallback sound or retrying later. Request metadata is kept for billing, but availability is not guaranteed. Plan for intermittent connectivity in your IoT design.
How do I monitor usage costs?
Check your balance and character usage on the /get-api-key/ page. The API charges $0.01 per 1,000 characters. Failed requests are free. Monitor your usage via the dashboard to ensure your USDT top-up covers your volume, as there are no monthly plans or automatic subscription renewals.
Do I need a server for integration?
No, you can call the API directly from your IoT device if it has internet access. A server is only needed if you want to hide your API key or manage complex routing. The API accepts standard HTTP POST requests, so any device with network capability can interact with it.
Can I use this with Raspberry Pi?
Yes, Raspberry Pi devices can easily call the API using standard HTTP libraries. Send a POST request to the endpoint with your key and text, then play the returned audio file using local tools like aplay or mpv. The API works with standard Linux-based IoT environments.
How do I test the API locally?
Use the curl example provided on the /get-api-key/ page. Send a POST request to https://api.k665.info/v1/audio/speech with your Bearer key and text. You can also use the OpenAI SDK by setting the base URL to https://api.k665.info/v1. This allows quick verification of voice and format settings.
What is the latency like?
Typical speed is roughly real-time, generating about 25 characters of text per second of audio. Short phrases may take a few seconds due to processing. Requests are processed sequentially, so under load, a request may wait in a queue. Plan your device’s user experience accordingly.
Can I use custom voice models?
No, custom voice cloning or uploading your own voice is not offered. You must choose from the 8 available presets (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion). These voices are based on licensed recordings and cannot be customized or trained on new data by the user.
Prerequisites for IoT Integration
Before integrating the TTS API into your smart home assistant, you must generate an API key via the /get-api-key/ page. This single key authenticates all voice synthesis requests. Ensure your device has reliable internet access, as the API requires a stable connection to process text and return audio files efficiently.
API Key Generation
Sign in with Google or email on the get-api-key page to receive your unique key. This key is tied to your account balance and usage limits. Keep it secure, as it controls your spending and access to the service.
- One active key per account
- New keys invalidate the old one immediately
- Available via /get-api-key/ page
Network Connectivity Requirements
Your IoT device needs consistent internet access to send POST requests to https://api.k665.info/v1/audio/speech. Since the API processes requests sequentially, a stable connection prevents delays in audio delivery. Ensure your network supports the required bandwidth for small audio payloads.
- Requires stable internet connection
- Supports standard HTTP/HTTPS protocols
- Minimal bandwidth for audio files
Audio Playback Hardware
Select speakers compatible with MP3, WAV, Opus, FLAC, or PCM formats. Most embedded systems handle MP3 or WAV natively. Ensure your hardware can buffer the audio data received from the API response for smooth playback without interruptions.
- Supports MP3, WAV, Opus, FLAC, PCM
- Native codec support recommended
- Buffering capability for smooth playback
Step 1: Sending the Request
Before your IoT device speaks, it must send a structured request to the API. This involves defining the text, voice, and format in a simple JSON body. The API accepts standard OpenAI-shaped requests, making integration straightforward for developers already familiar with similar TTS services.
Authentication is handled via a single Bearer token. You only need one active key per account, which simplifies secure storage on embedded devices. Once authenticated, the API processes your text and returns the audio file.
Constructing the JSON Payload
Build a JSON object containing model, input, voice, and response_format. The input field holds your text (up to 4096 characters). Choose from eight voice presets like 'aria' or 'atlas' and select formats like MP3 or WAV. Optional fields include speed (0.25–4.0) and language.
Ensure your text does not exceed the character limit. If it does, split the text into parts, generate audio for each, and join the files on the device or server side.
model: "tts-1" or "tts-1-hd"input: Your text stringvoice: One of 8 presetsresponse_format: mp3, wav, opus, flac, or pcm
Setting Headers and Auth
Include the Content-Type: application/json header. For authentication, add an Authorization header with your API key in the format Bearer tts-.... This key is issued upon account creation and remains active until you generate a new one.
The API validates the key on every request. If the key is invalid or expired, the request fails immediately without charging your character balance.
Choosing the Endpoint
Send your POST request to https://api.k665.info/v1/audio/speech. This is the dedicated endpoint for speech synthesis. Ensure your IoT device has outbound HTTP/HTTPS access to this domain.
For quick testing, you can use the curl example provided on your dashboard. The endpoint accepts standard JSON bodies, so no proprietary SDKs are required.
Step 2: Handling the Response
Once the API returns a 200 status, you receive the raw audio binary. For IoT devices with limited RAM, prioritize MP3 or Opus formats to minimize memory footprint during playback. WAV files are supported but require significantly more buffer space, which may be critical for microcontrollers with small SRAM. Ensure your HTTP client streams the response directly to a file or audio buffer rather than loading the entire payload into memory at once.
When parsing the binary data, verify the response_format matches your device’s decoder. If using curl or a simple HTTP library, write the body bytes directly to a temporary file before passing it to the audio library. This avoids potential memory fragmentation issues common in embedded Linux or RTOS environments.
Receiving the Audio File
The API returns the audio as a binary stream in the response body. Set your HTTP client to handle the response body, allowing you to write data to disk or a buffer as it arrives. This is crucial for devices with limited RAM, as it prevents loading multi-megabyte WAV files entirely into memory. MP3 and Opus are recommended for their efficient compression ratios.
- Use streaming APIs to write data incrementally.
- Prefer MP3/Opus for memory-constrained devices.
- Avoid loading full payloads into RAM.
Parsing Binary Data
Ensure your device’s audio library supports the requested format. If you request wav, verify that your decoder handles 16-bit PCM or 24-bit formats correctly. For mp3 or opus, ensure the library is compiled with the necessary codecs. Always validate the content-type header before processing the binary stream to prevent decoding errors on malformed responses.
- Verify codec support in your audio library.
- Check Content-Type headers before decoding.
- Write to file before playback if memory is tight.
Error Handling Logic
Handle HTTP errors (4xx, 5xx) gracefully. A 401 error indicates an invalid or expired API key, while a 429 error means you’ve hit the 60 requests per minute limit. Implement exponential backoff for retrying failed requests. Failed synthesis requests are free, so you can safely retry without incurring extra costs, but ensure you do not exceed the rate limit repeatedly to avoid service degradation.
- Retry on 429 with exponential backoff.
- Check for 401 to refresh API keys.
- Failed requests incur no charge.
Step 3: Playback on the Device
Once the API returns the audio binary, your IoT device must handle playback efficiently. The API supports MP3, WAV, Opus, FLAC, and PCM formats, giving you flexibility based on your hardware’s capabilities. MP3 is generally the most efficient for storage and transmission, while WAV and PCM offer uncompressed quality with simpler decoding logic, which can be beneficial for resource-constrained microcontrollers.
Choosing the right format depends on your device’s processing power and memory constraints. We recommend starting with MP3 for its balance of compression and compatibility, ensuring smooth playback across various smart home assistants and voice-enabled gadgets.
Supporting MP3 and WAV Formats
MP3 provides excellent compression, reducing bandwidth usage and storage needs on your device. WAV and PCM are uncompressed, offering simpler decoding but larger file sizes. Choose based on your hardware’s capabilities.
For devices with limited processing power, PCM or WAV may be easier to decode. For battery-powered devices, MP3’s smaller size helps conserve energy during transmission and storage.
- MP3: Recommended for bandwidth efficiency and storage savings.
- WAV/PCM: Suitable for simple hardware with limited decoding capabilities.
- Opus/FLAC: Available for lossless or high-quality needs if supported by your device.
Buffering Considerations
Buffering audio data before playback ensures smooth playback without interruptions. For real-time streaming, buffer sizes should be optimized to balance latency and stability. Larger buffers reduce playback glitches but increase initial delay.
For IoT devices with intermittent connectivity, pre-buffering audio chunks can help mitigate network variability. Ensure your device can handle temporary pauses without dropping audio frames.
- Optimize buffer size for your device’s memory and connectivity.
- Pre-buffer audio chunks for intermittent networks.
- Monitor buffer levels to prevent underflow or overflow.
Memory Management for Embedded Systems
Embedded systems often have limited RAM. Efficient memory management is crucial when decoding and playing audio. Use memory-mapped files or stream audio directly to the DAC to minimize RAM usage.
For devices with severe memory constraints, consider streaming audio data directly to the audio output device without storing it entirely in RAM. This approach reduces memory overhead and improves performance.
Regularly monitor memory usage during audio playback to identify potential leaks or bottlenecks. Use tools like heap profiling to optimize memory allocation and deallocation.
- Stream audio directly to DAC to minimize RAM usage.
- Use memory-mapped files for efficient storage.
- Monitor memory usage to prevent leaks.
Step 4: Managing API Keys
API key management is critical for securing your IoT deployments. Unlike traditional web apps, embedded devices have limited secure storage options, making key handling a distinct challenge for indie developers building voice-enabled products.
Secure Key Storage
Store your API key in the device’s secure element or encrypted configuration file. Avoid hardcoding keys in plain text within the firmware binary, as this allows easy extraction via reverse engineering. Use environment variables if your device supports a secure boot process.
- Use hardware security modules (HSM) or trusted platform modules (TPM) if available.
- Encrypt keys at rest using AES-256.
- Never log the full key in debug output.
Key Rotation Strategy
One active key per account simplifies rotation. Issue a new key via the dashboard; the old one stops immediately. Update the device configuration to use the new key, ensuring no audio generation downtime. This one-key-per-account model prevents complex sync issues across multiple devices.
- Generate a new key in the /get-api-key/ dashboard.
- Push the new key to devices via OTA updates.
- Discard the old key immediately after verification.
Monitoring Usage
Track character usage and request counts via the dashboard to avoid unexpected charges. Since you pay per character, monitor usage to optimize text length. The dashboard shows characters left and balance, helping you set internal limits before hitting the 60 requests per minute rate limit.
- Check balance regularly in the account dashboard.
- Set up alerts for high character consumption.
- Monitor request rates to stay under the 60 req/min limit.
Step 5: Optimizing for Speed
Speed optimization is critical for responsive IoT devices where users expect immediate audio feedback. By reducing generation latency, you enhance the natural flow of voice interactions in smart home assistants and dashboards. Efficient caching and parameter tuning minimize the time between text input and audio playback.
Focus on reducing network round-trips and leveraging device-side storage for common phrases. Adjusting the synthesis speed can impact perceived responsiveness, ensuring your IoT product feels responsive even under varying network conditions.
Caching Frequent Phrases
Store audio files for common commands like "turn on lights" or "what's the weather" locally on the device. This eliminates API calls for repeated inputs, reducing latency to near-zero and conserving bandwidth.
Use a simple hash of the text as a cache key. Ensure the cache invalidates only if the voice or speed parameter changes, preventing stale audio from playing when settings are updated.
- Cache common phrases locally on the device.
- Use text hash as cache key.
- Invalidate cache on voice/speed change.
Pre-generating Static Content
Pre-render audio for static announcements like system startup sounds or daily greetings during device provisioning or idle periods. This ensures instant playback when needed, bypassing the typical few-second generation delay.
Store these pre-generated files in the device’s non-volatile memory. This is ideal for notifications that must play immediately upon an event trigger, such as a doorbell press or alarm activation.
- Pre-render static announcements during idle time.
- Store in non-volatile memory.
- Bypasses generation delay for instant playback.
Using Speed Parameters
Adjust the speed parameter (0.25–4.0) to optimize generation time. Faster speeds reduce the duration of audio files, which can decrease processing time on the server, especially for longer texts.
Balance speed with clarity. A speed of 1.0 is standard, but increasing it to 1.5–2.0 for simple alerts can make responses feel more immediate, provided the audio remains intelligible for the user.
Note that generation time is roughly real-time, so shorter audio files from faster speeds directly reduce the wait time for the user.
- Adjust speed parameter (0.25–4.0).
- Increase speed for simple alerts.
- Shorter audio files reduce wait time.
Step 6: Testing and Debugging
Testing your IoT TTS integration requires verifying that text payloads are correctly formatted and that audio responses are received without corruption. Use local development tools to simulate API calls before deploying to your target devices, ensuring that the request shape matches the expected JSON structure for the /v1/audio/speech endpoint.
Local Development Tools
Use standard HTTP clients like curl or Postman to construct test requests directly against the API base URL. This allows you to validate the JSON body, including model, voice, and input fields, ensuring the 4096-character limit is respected before committing to embedded device code.
- Use
curlwith a sample key to test basic synthesis. - Validate response headers for correct content-type (audio/mp3, audio/wav, etc.).
- Check that the returned binary data matches the expected format size.
Simulating Network Latency
IoT devices often operate on constrained networks. Introduce artificial delays in your test scripts to mimic high-latency connections, ensuring your device’s audio player can handle buffering delays without dropping playback. Since requests are processed sequentially, expect potential queueing during peak loads.
- Add 200–500ms delays to test buffer thresholds.
- Verify playback starts smoothly after the delay.
- Check for timeout errors in your device’s HTTP client.
Logging Request Data
Log request timestamps, character counts, and response status codes to diagnose issues. Since failed requests are free but still consume rate limits, track these errors to distinguish between network issues and API failures. Store logs locally on the device or send them to a central server for analysis.
- Record the exact input text and character count.
- Note the
modelused (tts-1 or tts-1-hd). - Log response time to identify queueing delays.

Step 7: Scaling the Integration
Scaling your IoT TTS integration requires managing the queue behavior of the API, where requests are processed sequentially. Under load, a single request may wait in line, so your device logic should handle potential delays gracefully rather than timing out immediately.
Implementing robust retry logic with exponential backoff ensures that transient network issues or backend queueing do not result in silent failures or repeated redundant requests.
Handling Concurrent Requests
Since requests are processed one after another, sending multiple simultaneous synthesis jobs from a single key can cause queuing delays. For devices with multiple audio triggers, ensure your application layer queues requests sequentially to avoid overwhelming the endpoint and to maintain predictable latency.
If your smart home hub needs to announce multiple events quickly, batch them or space them out slightly to prevent the queue from backing up, which could delay critical notifications.
- Queue requests sequentially within your device firmware.
- Implement exponential backoff for retry logic.
- Avoid simultaneous POST requests from the same key.
Rate Limit Management
Each API key is limited to 60 requests per minute (or 10 per minute before the first top-up). Monitor your usage dashboard to ensure you stay within these bounds, especially when deploying to multiple devices that share a single key.
If you exceed the limit, the API will reject further requests until the window resets. Build your device to pause synthesis briefly when approaching the limit, using the usage metrics available in your account dashboard.
- Limit: 60 requests per minute per key.
- Initial limit: 10 requests per minute.
- Check dashboard for real-time usage stats.
Multi-Device Deployment
For large-scale deployments, consider issuing separate API keys for different device groups to distribute the 60 requests-per-minute limit. This prevents one busy device from throttling the entire network.
Each account supports one active key at a time, so rotate keys if you need to scale further or if a key becomes compromised. The old key stops working immediately upon issuing a new one.
- Use separate keys for different device groups.
- Rotate keys via the dashboard if needed.
- Old keys stop working immediately after rotation.
Step 8: Language Support in IoT
Language detection ensures your IoT device responds in the user’s native tongue. The API accepts an optional language ISO code parameter. If omitted, it guesses from the script, defaulting to English for Latin text. Explicitly setting this field prevents mispronunciation in mixed-script environments.
Detecting User Language
Send the language field in your JSON payload to enforce specific output. Supported languages include English, German, French, Spanish, and others listed in our documentation. This ensures consistent pronunciation regardless of the input text’s visual script.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
- Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali.
Switching Voices Dynamically
Each voice preset works across all 23 supported languages. You can switch voices dynamically based on user preference or context without changing the language code. For example, use aria for clear narration or atlas for neutral news updates in any supported language.
Fallback Strategies
If the API fails to detect the language or returns an error, default to English. Implement logic to retry with an explicit language parameter if the initial guess fails. Always handle errors gracefully to avoid silent failures in your device’s audio output.
- Default to English for Latin-script text if
languageis unset.
Step 9: Cost Management
Cost management is critical for IoT deployments where voice feedback is frequent but small. Our pricing is straightforward: $10 per 1 million characters, meaning every space and punctuation mark counts. Since requests are processed sequentially, inefficient text can increase latency and costs simultaneously.
You can monitor your exact usage, including characters left and balance, directly on the /get-api-key/ dashboard. This transparency helps you predict expenses based on your device's voice interaction volume without hidden fees.
Monitoring Character Usage
Track your consumption in real-time via the dashboard. Each request’s character count is logged, allowing you to correlate device triggers with API calls.
Failed requests are free, so you only pay for successful synthesis. This protects your budget during network instability common in IoT environments.
- View balance and characters remaining instantly.
- No minimum spend or monthly plans.
Setting Budget Alerts
Since billing is character-based, you can estimate costs before deployment. For example, a 50-character alert uses negligible credit.
Top-ups via USDT (TRC-20) are credited automatically, ensuring your devices never go silent due to payment delays.
Optimizing Text Length
Concise text reduces both cost and generation time. Aim for natural, short phrases rather than long paragraphs.
Split longer texts into chunks under 4,096 characters to ensure smooth playback on constrained devices.
Step 10: Security Best Practices
Securing your TTS integration starts with protecting the API key and ensuring data moves safely over the network. Since your IoT device communicates directly with the cloud, how you store credentials and transmit requests determines the integrity of your voice-enabled product.
This section covers practical steps for embedding devices to keep keys safe, use secure protocols, and respect user data privacy without adding unnecessary complexity to your firmware or backend logic.
Encrypting API Keys
Store your Bearer token in non-volatile memory, such as an EEPROM or secure element, rather than hardcoding it in plain text within your source code. This prevents extraction if the device firmware is read.
Use the key only for authentication requests. Avoid logging the full token in debug outputs where it might be exposed in plain view during troubleshooting.
- Store keys in EEPROM or secure elements
Secure Transmission Protocols
Always use HTTPS for all API calls to https://api.k665.info/v1. This encrypts the JSON payload and the returned audio stream, preventing eavesdropping on your local network.
Ensure your device’s certificate store is up to date to verify the server’s identity, protecting against man-in-the-middle attacks during speech generation.
- Use HTTPS for all API calls
Data Privacy Compliance
Input text is used solely for audio synthesis and is not stored for training. Generated audio is returned in the response and not retained on our servers.
Request metadata like time and character count is kept only for billing. You control what text is sent, so avoid transmitting personally identifiable information unless necessary for the voice output.
- Text is not used for training
- Audio is not stored
Common Pitfalls to Avoid
Even simple IoT setups can trip up when multiple devices hit the API simultaneously. Understanding the limits prevents your smart speaker from failing silently during peak usage.
Ignoring these operational details turns a reliable voice assistant into a frustrating experience. Focus on these three common pitfalls to ensure smooth deployment.
Ignoring Rate Limits
The API enforces a hard limit of 60 requests per minute per key. If your device or dashboard exceeds this, subsequent calls fail immediately. New accounts start with a stricter 10 requests per minute limit until the first top-up is processed.
- Implement exponential backoff in your firmware retry logic.
- Distribute load across multiple keys if scaling heavily.
Overlooking Audio Format Support
Not all IoT audio chips support every format. While MP3 is universally compatible, WAV files are larger. Ensure your device’s decoder matches the response_format you request to avoid playback errors or excessive memory usage.
- Prefer MP3 for general compatibility.
- Use WAV only if uncompressed quality is strictly required.
Neglecting Error States
Requests can fail due to network issues or service overload. Failed requests are free, but your app must handle HTTP errors gracefully. Do not assume every POST results in audio; always check the status code before playing.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Beginners can start generating speech in minutes using the provided curl examples or standard HTTP clients.
23 languages
Any voice speaks any of these languages.
