Quick Start: Cloud Text-to-Speech API for Developers

By Takaok Assist editorial team · Updated 2026-11-19

This guide helps product teams integrating speech synthesis into assistive devices and elderly care applications. You will learn to generate audio files via a simple POST request, compatible with standard OpenAI SDK patterns. We provide concrete cURL examples and configuration steps to simplify your transition from legacy providers.

Readers will find clear documentation on authentication, supported voices, and audio formats. The guide covers essential details like rate limits, error handling, and text splitting for long inputs. Use this reference to build reliable, predictable speech features without complex infrastructure or unexpected billing surprises.

Quick Start: Cloud Text-to-Speech API for Developers

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.mp3

Python (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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication and Keys

Sound wave illustration for: 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

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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

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. LibriTTS-R corpus (OpenSLR 141)
  3. Node.js documentation
  4. openai-node on GitHub
  5. Creative Commons Attribution 4.0
  6. Tether (USDT)
  7. TRON developer hub: TRC-20
  8. FFmpeg documentation
  9. LibriVox public-domain audiobooks
  10. OpenAI API reference: create speech
  11. Python documentation
  12. ISO 639 language codes

More on this site