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 active API key, current balance, and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one.
What is the base URL?
The API base URL is https://api.takaok.info/v1. You send POST requests to https://api.takaok.info/v1/audio/speech for synthesis. Other endpoints include GET /v1/voices and GET /v1/models for configuration details.
Can I use the OpenAI Python SDK?
Yes. The endpoint shape matches the OpenAI speech endpoint. Configure your OpenAI SDK client by setting the base_url to https://api.takaok.info/v1 and providing your Takaok Assist API key for authentication.
What is the maximum text length?
Each request supports up to 4,096 characters. Spaces and punctuation count toward this limit. For longer texts, split the input into multiple requests and join the resulting audio files.
How do I specify a voice?
Include the voice parameter in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Use GET /v1/voices to see available options.
What does the speed parameter do?
The speed parameter adjusts playback speed between 0.25 and 4.0. The default is 1.0. Adjusting this value scales the generation time proportionally without altering the voice characteristics.
Is the language parameter required?
No, it is optional. The system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly set the language to ensure correct pronunciation.
How are errors returned?
Errors are returned as standard HTTP status codes with a JSON body describing the issue. Failed synthesis requests are free, and any charges are returned in full if the request fails.
What happens if I exceed the rate limit?
You are limited to 60 requests per minute per key (10 before the first top-up). Exceeding this limit results in HTTP 429 Too Many Requests responses until the window resets.
How do I handle long texts?
Split your text into chunks of up to 4,096 characters. Send each chunk as a separate request. Then, programmatically join the returned audio files to create the final output.
What audio formats are best for mobile?
You can choose between mp3, wav, opus, flac, or pcm. MP3 and Opus are suitable for mobile due to smaller file sizes and broad compatibility, while WAV offers uncompressed quality.
Can I regenerate a failed request?
Failed requests are free, so you can retry them without incurring additional costs. The API returns the error details, allowing you to adjust parameters or retry the request.
How do I rotate my API key?
You can issue a new API key at any time from your account page. The new key becomes active immediately, and the old key stops working at once.
Is the API synchronous or asynchronous?
The API is synchronous. You send a POST request and receive the audio file in the response. Requests are processed sequentially, so under load, you may experience queueing delays.
First request
curl
curl https://api.takaok.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.takaok.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.takaok.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 |
Authentication and Keys
Takaok Assist provides a simple, single-key authentication model designed for straightforward integration into assistive device workflows. Each account generates one active key that secures all API requests, eliminating the complexity of managing multiple service tokens for different endpoints.
Generate Your API Key
Access the /get-api-key/ page to create your account via Google or email. The dashboard immediately displays your unique API key alongside your current balance and usage statistics. No complex setup or approval process is required before you can begin making requests.
Bearer Token Format
Include your key in the HTTP header as Authorization: Bearer tts-.... This format matches standard conventions used by major providers, allowing you to use existing HTTP clients or the OpenAI SDK with minimal configuration changes.
- Prefix: Bearer
- Token format: tts-...
Key Rotation Policy
If needed, you can issue a new key from the dashboard at any time. The old key stops working immediately upon issuance of the new one, ensuring secure access control without downtime or transition periods.
First Request with cURL
Send your first audio synthesis request using a simple cURL command. The API accepts standard JSON bodies, allowing you to generate speech files directly from your terminal or script without complex setup. This method works identically whether you are testing locally or integrating into an assistive device backend.
Configure the endpoint to point to the Takaok Assist API base URL. Ensure you replace the placeholder with your actual Bearer token from the dashboard. The request body defines the model, voice, and input text to be converted.
Basic POST Command
Use the standard POST method against the speech endpoint. Replace YOUR_API_KEY with your secret key and adjust the input text as needed. This command returns the audio file directly in the response body.
The command structure mirrors common industry standards, reducing the learning curve for teams already familiar with similar TTS services. It supports all formats and speed settings defined in the documentation.
curl -X POST https://api.takaok.info/v1/audio/speech-H "Authorization: Bearer YOUR_API_KEY"-H "Content-Type: application/json"
JSON Body Structure
The request body requires the model, input, and voice fields. You may optionally specify response_format, speed, and language. The input text must not exceed 4,096 characters per request.
Each field maps directly to the synthesis engine’s capabilities. For example, setting speed to 1.0 produces natural pacing, while 0.5 slows the output for clearer comprehension in elderly care applications.
model: "tts-1" or "tts-1-hd"`input: "Your text here"`voice: e.g., "nova", "atlas"`response_format: "mp3", "wav", "opus", "flac", "pcm"`speed: 0.25 to 4.0`language: ISO code (optional)
Response Handling
A successful request returns the audio file directly in the response body with the appropriate content type. You can save this output to a file or play it on your device’s audio player. Failed requests return a JSON error object with details.
Note that short phrases may take a few seconds to generate, while longer texts take roughly one second per 25 characters of generation time. Ensure your client handles binary audio data correctly rather than parsing it as JSON.
OpenAI SDK Integration
Integrating Takaok Assist into your workflow is straightforward because the API mirrors the OpenAI speech endpoint structure. By updating your base URL, you can leverage existing OpenAI SDKs without rewriting core logic.
Base URL Configuration
Set your client's base URL to https://api.takaok.info/v1. This simple change directs requests to our inference engine while maintaining the standard request shape.
Client Initialization
Initialize the OpenAI SDK using your API key. Pass the custom base URL during initialization. The SDK handles authentication headers automatically, ensuring secure access to the TTS endpoint.
- Use
base_url=https://api.takaok.info/v1 - Pass your
tts-...key in the authorization header
SDK Compatibility Notes
The official OpenAI SDKs work directly with our API. Since the request shape matches the OpenAI speech endpoint, no custom parsing is needed. This reduces integration time for your product team.
Supported Parameters
Configure your synthesis requests using the model, voice, and speed parameters to tailor audio output for assistive devices. The model field accepts "tts-1" or "tts-1-hd", both using the same engine with identical pricing. Choose from eight voice presets, such as "sage" for clear instructional tones or "nova" for upbeat narration, ensuring the audio matches the user interface context.
Adjust the speed parameter within a range of 0.25 to 4.0 to accommodate different listening needs. Slower speeds may benefit elderly users with hearing impairments, while faster settings can reduce latency for quick status updates. All parameters are passed in the JSON body alongside your text input.
Model Selection
Both "tts-1" and "tts-1-hd" utilize the same underlying engine and incur the same rate of $0.01 per 1,000 characters. Both "tts-1" and "tts-1-hd" use the same engine and price; you may choose either.
Voice Presets
Eight licensed presets are available, derived from LibriTTS-R and LibriVox recordings. For elderly care applications, "sage" provides a calm, instructional tone, while "aria" offers a warm, clear narrator style. Male voices like "atlas" deliver neutral news-style updates, and "orion" suits documentary-style content.
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
- felix: energetic, promo
- milo: friendly, conversational
- atlas: neutral, news
- orion: deep, documentary
Speed Control Range
The speed parameter accepts values from 0.25 to 4.0. Default speed is 1.0. Reducing speed to 0.25 or 0.5 can improve comprehension for users with cognitive or hearing challenges, while increasing speed accelerates response times for less complex interactions.
Audio Formats
The API supports five audio formats, allowing you to choose the best balance between file size and fidelity for your assistive device or elderly care application. All formats are generated synchronously upon request completion.
Selecting the right format depends on your playback infrastructure and storage constraints. We provide transparent options for both compressed and lossless scenarios.
MP3 Output
MP3 is the default and most widely supported format. It offers small file sizes suitable for network transmission to mobile apps or web players.
Use this format when bandwidth efficiency is prioritized over studio-grade audio fidelity.
- Default format for most integrations
- Optimized for low-latency playback
WAV and FLAC Options
WAV provides uncompressed audio, ideal for local storage or high-fidelity playback systems that handle larger files easily.
FLAC offers lossless compression, reducing storage needs while preserving audio detail.
- WAV: Uncompressed, maximum compatibility
- FLAC: Lossless, smaller than WAV
PCM and Opus Support
PCM provides raw audio data, useful for direct hardware integration or custom DSP pipelines.
Opus offers high-quality audio at very low bitrates, ideal for voice-centric applications.
- PCM: Raw binary data
- Opus: Efficient voice compression
Error Handling
Understanding error responses ensures your assistive device or elderly care application handles speech synthesis failures gracefully. Our API returns standard HTTP codes to indicate success or failure, allowing your team to implement robust retry mechanisms without guessing the cause.
Common Error Codes
A 400 Bad Request indicates invalid input, such as text exceeding the 4,096-character limit or an unsupported voice parameter. A 401 Unauthorized error occurs if your Bearer token is missing or invalid, requiring immediate key rotation. A 429 Too Many Requests signals you have exceeded the 60 requests per minute rate limit.
Retry Logic
Implement exponential backoff for 429 and 503 errors. For 500 Internal Server Errors during synthesis, retry once after a short delay, as these are often transient. Do not retry 400 errors, as they indicate a configuration issue in your payload that will persist until fixed.
Failed Request Billing
If synthesis fails entirely, the charge is returned in full. You are only billed for successfully generated audio files. This ensures your product team pays only for usable output, simplifying cost tracking for your elderly care applications.
Rate Limits and Queues
The API enforces a strict limit of 60 requests per minute per key, ensuring stable performance for batch processing in assistive device workflows. This cap applies uniformly to both the tts-1 and tts-1-hd models, allowing developers to plan throughput without worrying about model-specific restrictions.
60 Requests Per Minute
Each active API key can process up to 60 synthesis requests within a one-minute sliding window. This rate supports steady audio generation for elderly care applications, where consistent latency is critical for user experience during text-to-speech playback.
Initial Limit for New Keys
Newly created keys start with a reduced limit of 10 requests per minute. This applies until the first top-up is completed and credited to your account. Once the minimum $5 USDT transfer is confirmed, the limit increases to the full 60 requests per minute.
Processing Queue Behavior
Requests are processed sequentially rather than in parallel. Under normal load, most synthesis tasks complete within seconds, but during peak usage, requests may enter a processing queue. This linear processing ensures predictable billing and audio consistency, though it may increase latency if you exceed the per-minute limit.
Advanced Usage
For accurate synthesis, explicitly set the language parameter when using Latin-script text for languages other than English. While the API guesses the language from the script by default, this assumption fails for non-English Latin text, leading to incorrect pronunciation.
Use ISO language codes (e.g., fr, de, ja) to ensure the engine selects the correct phonetic rules. This is critical for assistive devices reading mixed-language content or localized interface prompts.
Text Splitting Strategy
The API accepts a maximum of 4096 characters per request. For longer texts, such as full chapters or extended instructions, split the input into chunks of this size before sending them sequentially.
- Count characters including spaces and punctuation.
- Ensure splits occur at logical boundaries (sentences) where possible to avoid audio glitches.
- Track the cumulative character count to stay within your billing balance.
Audio Joining Process
Receive each audio chunk as a separate response. Your application must concatenate these files in order to reconstruct the complete audio.
Use standard audio libraries to merge the files. Since each request is processed independently, ensure your implementation handles the sequential download and stitching reliably to maintain playback continuity.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Users can distinguish between different types of alerts based on voice alone.
23 languages
Any voice speaks any of these languages.
