Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or email plus password. Your account page displays your unique API key, current balance, trial credit, characters left, usage, and a ready curl example immediately after registration. You can issue a new key at any time, which stops the old one instantly.
What is the base URL for the API?
The API base URL is https://api.tk971.info/v1. You send POST requests to https://api.tk971.info/v1/audio/speech for synthesis. Other endpoints like /v1/voices and /v1/models are also available at this base path for retrieving voice details and model information.
Which SDK should I use?
Use the official OpenAI SDKs by setting base_url to https://api.tk971.info/v1. We do not provide our own official SDK. The request shape matches the OpenAI speech endpoint exactly, ensuring easy integration. You can also use plain HTTP requests. This approach works seamlessly with Node.js, allowing you to add voice to your IoT projects without heavy coding.
How do I handle errors?
If synthesis fails, the charge is returned in full. Failed requests incur no cost. You should implement standard HTTP error handling in your Node.js code to catch failures and retry if necessary, as requests are processed sequentially and may queue under load.
What is the rate limit?
You are limited to 60 requests per minute per API key. Before your first top-up, the limit is 10 requests per minute. Requests are processed one after another, so heavy load may cause queuing delays. Monitor your usage via the account dashboard.
How do I split long texts?
The API accepts up to 4096 characters per request. For longer texts, split the input into chunks of this size. Generate audio for each chunk individually, then join the resulting audio files. This ensures all text is synthesized without truncation errors.
Can I change the voice speed?
Yes, you can adjust the speed between 0.25 and 4.0. This parameter is part of the JSON request body sent to the speech endpoint. Adjusting speed allows you to match the audio output to your specific IoT device playback requirements or user preferences.
What languages are supported?
We support 23 languages, including English, Spanish, German, French, Chinese, Japanese, and Arabic. Any voice can speak any supported language. If you omit the language code, it is guessed from the script, defaulting to English for Latin text. Set it explicitly for non-English Latin scripts.
How do I install the npm package?
Install the OpenAI npm package using your terminal: npm install openai. Then configure the client with base_url: 'https://api.tk971.info/v1' and your API key. This allows you to use the standard OpenAI methods for generating speech directly within your Node.js environment.
Is the API compatible with OpenAI SDK?
Yes, the API is fully compatible with the official OpenAI SDKs. You only need to change the base_url to https://api.tk971.info/v1. The request shape for the speech endpoint is identical, allowing you to use existing OpenAI code with minimal configuration changes.
What happens if the request fails?
If a synthesis request fails, the charge is returned in full. You are not billed for failed attempts. This ensures you only pay for successfully generated audio files. You can safely retry failed requests without worrying about double-charging your account balance.
How do I authenticate my requests?
Include your API key in the Authorization header as a Bearer token: Authorization: Bearer tts-... . One active key is issued per account. You can generate a new key anytime from your account page, which immediately invalidates the previous key.
Can I use custom voices?
No, we do not offer custom voice cloning or uploading your own voice. You must choose from the 8 available presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices are based on licensed recordings from LibriTTS-R (CC BY 4.0), derived from LibriVox public-domain audiobook readings.
Is there documentation for Python?
Yes. Since our API uses the same request shape as OpenAI, the official OpenAI Python SDK works seamlessly. Simply configure your base_url to https://api.tk971.info/v1 and provide your API key. You can use the standard SDK methods to send text and receive audio files, making integration straightforward for your IoT projects without needing custom code.
First request
curl
curl https://api.tk971.info/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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.tk971.info/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.tk971.info/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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Getting Your API Key
To start generating speech for your IoT devices, head to https://tk971.info/get-api-key/. You can sign up using your Google account or an email and password. This creates a unique account for our site, giving you access to the API key and usage dashboard immediately after registration.
Once logged in, you will see your active API key, current balance, and character usage. You can generate a new key at any time, which instantly invalidates the previous one, ensuring your credentials stay secure as you integrate the API into your smart home projects.
Sign Up on the Site
Visit the /get-api-key/ page to create your account. You have two options: sign in with Google for instant access or use a standard email and password setup. This step establishes your independent storefront account, separate from other sites in our network.
After signing up, you are directed to your account page where your API key and initial details are displayed. If you used Google, you receive a $0.50 trial credit valid for 7 days, giving you about 50,000 characters to test your first voice outputs.
- Google Sign-In: Instant access with trial credit.
- Email/Password: Standard registration without trial credit.
- Independent Account: Created specifically for tk971.info
Generate Your Key
Your API key appears on the account page alongside your balance and usage stats. This key is the only one active at any given time. If you need to rotate credentials, simply generate a new key from the same page; the old one stops working immediately.
Keep your key handy for your Node.js integration. It starts with 'tts-' and is used in the Authorization header of every request. You can regenerate it anytime if you suspect it has been exposed, without losing your balance or settings.
- One active key per account.
- New keys invalidate old ones instantly.
- Key format: tts-...
Secure Your Key
Treat your API key like a password. Include it in the Authorization header as 'Bearer tts-...'. Since you pay per character, ensure your key is not publicly exposed in client-side code or version control. Store it in environment variables in your Node.js application.
You can issue a new key at any time from your account page. The moment you generate a new key, the previous one becomes invalid. This allows you to quickly revoke access if needed without waiting for a support response.
- Use environment variables.
- Regenerate anytime to revoke old keys.
- Key invalidates instantly upon generation.
First API Request with cURL
Make your first API call using cURL to generate speech instantly. This method requires no extra dependencies and works directly from your terminal, making it ideal for quick IoT device prototypes.
Replace YOUR_API_KEY with your actual key from the dashboard. The request sends a JSON payload to the API endpoint, instructing the service to convert your text into an audio file.
Basic Request Structure
Send a POST request to the speech endpoint. Include your Bearer token in the Authorization header. The body contains the model, text input, voice selection, and desired audio format.
This structure mirrors the standard OpenAI speech endpoint, ensuring compatibility with existing Node.js workflows that expect this specific JSON shape.
- Endpoint: POST /v1/audio/speech
- Auth: Bearer tts-...
JSON Body Explanation
The model field accepts 'tts-1' or 'tts-1-hd'. The input field holds your text, limited to 4096 characters. Choose a voice from the eight presets and set response_format to mp3, wav, opus, flac, or pcm.
You can optionally specify a language ISO code or let the system guess it based on the script. The speed parameter allows adjustment from 0.25 to 4.0.
Response Format
On success, the API returns the audio file directly in the response body. The content type matches your requested format, such as audio/mpeg for MP3.
If the request fails, you receive an error JSON object explaining the issue, such as invalid input or rate limits, without any audio data.

Using the OpenAI SDK with Node.js
Using the official OpenAI SDK for Node.js simplifies integration with IoT Voice Labs. You only need to adjust the base_url to point to our API endpoint, allowing you to use familiar code structures without learning a new client library.
This approach ensures compatibility with existing Node.js workflows, making it easy to add voice capabilities to your smart home projects with minimal code changes.
Install the Package
Start by installing the OpenAI SDK for Node.js using your preferred package manager. This library provides the necessary tools to handle HTTP requests and JSON parsing efficiently.
- Run
npm install openaiin your project directory. - Ensure your Node.js environment is up to date.
Configure Base URL
Configure the SDK to point to the IoT Voice Labs API endpoint. Set the base_url to https://api.tk971.info/v1 and provide your API key in the Authorization header.
This configuration tells the SDK where to send your speech synthesis requests, ensuring they are routed correctly to our service.
- Set
baseURLtohttps://api.tk971.info/v1. - Include
Authorization: Bearer YOUR_API_KEYin the header.
Make the Request
Use the audio/speech endpoint to send your text and receive an audio file. Pass parameters like model, voice, and input as required by the API.
The SDK handles the request and returns the audio file, which you can then save or play directly on your IoT device.
- Specify
modelastts-1ortts-1-hd. - Choose a
voicefrom the available presets. - Provide the
inputtext up to 4096 characters.
Available Audio Formats
The API supports multiple audio formats to suit different hardware constraints. You can choose MP3, WAV, OPUS, FLAC, or PCM by setting the response_format parameter in your request body.
MP3 Support
MP3 is a standard choice for streaming audio to smart displays and web interfaces. It offers a good balance between file size and quality for general playback.
WAV Support
WAV provides uncompressed audio data. This format is ideal when you need raw audio fidelity without compression artifacts, such as for local playback on high-end devices.
OPUS and FLAC
OPUS provides efficient compression suitable for constrained network environments, while FLAC offers lossless compression for archival or high-fidelity needs. Both are available alongside MP3 and WAV.
Error Handling in Node.js
Handling errors correctly ensures your IoT devices receive audio without hanging. The API returns standard HTTP status codes to indicate success or failure, allowing your Node.js scripts to react appropriately to network issues or invalid requests.
Implementing robust error handling prevents wasted cycles on failed synthesis jobs. By checking response codes and handling transient network issues, you ensure that your smart home devices remain responsive and reliable even when the API experiences temporary load.
Common Error Codes
The API uses standard HTTP status codes. A 4xx error indicates a client-side issue, such as an invalid API key or request format. A 5xx error suggests a temporary server issue. Always check the response status before parsing the audio data.
Rate limit errors (429) occur when you exceed 60 requests per minute. Your application should handle this gracefully rather than crashing. Other errors may indicate invalid voice presets or missing required fields in the JSON body.
- 401 Unauthorized: Invalid or missing API key
- 429 Too Many Requests: Rate limit exceeded (60 req/min)
- 500–503 Server Error: Temporary service issues
Retry Logic
Implement exponential backoff for transient errors. If you receive a 5xx error or a network timeout, retry the request after a short delay. This helps handle temporary spikes in server load without overwhelming the system.
Retrying on 4xx errors is generally unnecessary unless the issue is temporary, such as a rate limit. For 429 errors, wait for the duration specified in the retry-after header before making another request.
Debugging Tips
Log the full response body and headers to diagnose issues. If a request fails, the response often includes a detailed error message explaining the cause, such as an invalid voice ID or unsupported language.
Ensure your Node.js environment correctly handles JSON responses. Use console.log to inspect the status code and error message. If audio is not generated, verify that the input text is under 4096 characters and that the voice preset exists.
- Check response status codes first
- Log error messages for details
- Verify input text length and voice validity

Rate Limits and Performance
Each API key supports a baseline of 10 requests per minute, which increases to 60 requests per minute after your first top-up. This structure ensures stability for your smart home automations while keeping costs predictable at $0.01 per 1,000 characters.
60 Requests Per Minute
Your limit is strictly enforced per key. Once you complete your first top-up, your quota jumps to 60 requests per minute. If you exceed this limit, requests will be rejected until the window resets.
Queue Processing
Requests are processed sequentially. For longer texts, generation takes roughly real time (25 characters per second). Under load, your request may wait in a queue before synthesis begins, causing slight delays for short phrases.
Optimizing Requests
Split texts into chunks of 4096 characters to avoid errors. Pre-generating common phrases like 'door locked' or 'lights on' reduces latency and API calls, ensuring your IoT devices respond instantly to triggers.
Text Length and Splitting
Each API call accepts up to 4096 characters of input text. This constraint simplifies request management, ensuring that every submission remains within a predictable size envelope for reliable processing.
4096 Character Limit
The 4096-character cap applies per request, not per voice or language. Short phrases often take a few seconds to generate, while longer texts approach real-time speed, processing roughly 25 characters per second.
Splitting Long Texts
When your script exceeds 4096 characters, split the text into smaller chunks before sending them. This ensures each request stays within the limit and avoids truncation or errors in synthesis.
- Split at natural boundaries like sentences or paragraphs.
- Keep each chunk under 4096 characters.
- Send chunks sequentially or in parallel if your hardware allows.
Joining Audio Files
After receiving individual audio files for each chunk, concatenate them in the correct order. This creates a single, continuous audio stream that plays seamlessly for your IoT device or smart home project.
- Maintain original chunk order during concatenation.
- Use standard audio libraries to merge files.
- Test playback to ensure no gaps or overlaps.

Voice and Language Parameters
Choose from eight preset voices like milo for friendly conversational prompts or atlas for neutral news updates. Each voice is based on licensed recordings and works across all supported languages, allowing you to pick the perfect tone for your smart home device without complex configuration.
Set the language parameter to an ISO code (e.g., es, de) for non-English Latin text, as the API guesses English by default. Adjust speed between 0.25 and 4.0 to match your device’s playback environment, ensuring clear audio for users.
Selecting a Voice
Select one of eight voices: aria, nova, luna, sage, felix, milo, atlas, or orion. These presets cover warm narration, upbeat energy, soft storytelling, and calm instruction. Every voice supports all 23 languages, so you can maintain consistent character branding across different regions.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Setting the Language
The API guesses the language from the script if you omit the language field, defaulting to English for Latin text. For languages like Greek, Hebrew, or Japanese, or for non-English Latin text, explicitly set the language parameter to the ISO code. Unsupported languages like Vietnamese or Thai are not available.
Adjusting Speed
Use the speed parameter to control playback rate from 0.25 to 4.0. This allows you to slow down instructions for clarity or speed up notifications. Faster speeds reduce generation time slightly, but requests are processed sequentially, so queueing may still occur under load.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Your devices work together to create a simple, comfortable home without any complex setup or coding knowledge required by you.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- FFmpeg documentation
- curl documentation
- TRON developer hub: TRC-20
- Python documentation
- W3C WAI: making audio and video accessible
- Creative Commons Attribution 4.0
- Node.js documentation
- LibriTTS-R paper (arXiv 2305.18802)
- ISO 639 language codes
- OpenAI API reference: create speech
- LibriTTS-R corpus (OpenSLR 141)
