Frequently asked questions
How do I get an API key?
Sign up on our /get-api-key/ page using Google or email. Your account receives one active key, visible immediately. You can issue a new key anytime; the old one stops instantly. This key authenticates your requests via the Authorization header.
What is the base URL for the API?
The API base URL is https://api.twelve99.info/v1. Use this for all requests, including the speech endpoint at /audio/speech. The voices and models endpoints are also available at this base path for checking available options and formats.
Can I use OpenAI SDKs?
Yes. Our endpoint shape matches the OpenAI speech endpoint. Simply change the SDK’s base_url to https://api.twelve99.info/v1 and use your SageVoice key. This allows you to use official OpenAI SDKs without rewriting your integration logic.
What audio formats are supported?
We support mp3, wav, opus, flac, and pcm. Specify your preferred format in the response_format field. These formats cover most use cases, from web playback to high-quality archival storage, ensuring compatibility with various assistive devices and applications.
How do I handle errors?
Failed requests are free, and charges are returned in full. If synthesis fails, you receive a response indicating the error. Check your input text length (max 4096 characters) and ensure your API key is valid and active.
What are the rate limits?
You have 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up. Requests are processed sequentially, so under load a request may wait in a queue. Monitor your usage via the dashboard to stay within limits.
How do I split long texts?
Split input text into parts of up to 4096 characters. Send each part as a separate request, then join the resulting audio files. This ensures reliable synthesis for longer content, maintaining audio quality and respecting the character limit per request.
How do I select a voice and language?
Choose from 8 presets like aria or atlas. Set the language parameter to an ISO code (e.g., 'en', 'de') for non-English Latin text. If omitted, the system guesses the language, defaulting to English for Latin scripts. Use GET /v1/voices to list options.
First request
curl
curl https://api.twelve99.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.twelve99.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.twelve99.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 |
Get Your API Key
Access the /get-api-key/ page to create your SageVoice account. You can sign in instantly using your Google account or register with an email and password. Each account is tied to this specific site and provides a single active API key for all your generation needs.
Sign Up via Google or Email
Signing up with Google grants you a $0.50 free trial credit valid for seven days, allowing you to generate about 50,000 characters. If you prefer email registration, your account starts without trial credit, but you can top up later using USDT on the TRON network.
Find Your Key in Dashboard
Once logged in, your dashboard displays your API key, current balance, and character usage. You can copy this key directly into your applications or view a ready-to-use curl example to test your connection immediately.
Secure Your Key
Each account holds one active key. If you suspect it is compromised, you can issue a new key from the dashboard. The old key stops working immediately, ensuring your elderly care or accessibility tools remain secure without complex rotation procedures.
Make Your First Request
Send your first audio file by posting text to the speech endpoint. The API accepts standard JSON bodies, making it easy to integrate into any workflow without complex setup.
Use the provided curl example to verify your key and balance. This quick test confirms your account is active and ready for production use.
Use the curl Example
Copy the command below, replacing YOUR_API_KEY with your secret key from the dashboard. This command requests a short audio clip using the default voice.
Run this in your terminal to receive an audio file directly in your response. It confirms connectivity and authenticates your request instantly.
- Replace
tts-1withtts-1-hdfor a different model (same engine, different price). - Change
novato any of the 8 supported voices.
Send Text and Receive Audio
The endpoint accepts text up to 4096 characters per request. You specify the voice, language, and desired audio format (mp3, wav, opus, flac, or pcm) in the JSON body.
Upon success, you receive the binary audio data. Failed requests incur no charge, ensuring you only pay for delivered speech.
Test with Short Phrases
Start with simple sentences like "Hello, how are you?" to verify voice tone and speed settings. Short phrases generate in a few seconds, allowing quick iteration.
Adjust the speed parameter between 0.25 and 4.0 to find the optimal pace for your elderly care or accessibility application.
Using OpenAI SDK
The SageVoice API is fully compatible with the official OpenAI SDKs. By simply updating the base URL, you can leverage your existing code to generate speech without learning a new library. This makes integration straightforward for developers who already use OpenAI tools.
You do not need our own SDK. The same request structure used for OpenAI’s speech endpoint works here, ensuring a smooth transition. This approach keeps your code clean and reduces the learning curve for your development team.
Change Base URL
Update your SDK configuration to point to the SageVoice API endpoint. Set the base URL to https://api.twelve99.info/v1. This directs all API calls to the correct server while maintaining the standard request format.
Use Official SDKs
Use the official OpenAI SDK for your preferred language (Python, Node.js, etc.). The SDK handles authentication and request formatting automatically. This ensures reliability and keeps your integration up-to-date with standard practices.
- Python SDK
- Node.js SDK
- cURL support
Simple Configuration
Configure your API key in the standard environment variable or initialization parameter. Pass your text, voice, and model parameters as usual. The SDK manages the JSON body, so you focus on the logic.
This simplicity allows non-technical users to understand the flow quickly. You just send text, and the API returns audio. No complex setup is required to start generating speech for your assistive devices.
Supported Audio Formats
Choose the output format that best suits your accessibility tool. MP3 offers small file sizes for easy sharing, while WAV and FLAC provide high-fidelity audio for professional assistive devices.
MP3
MP3 is the default format, providing compressed audio that reduces bandwidth usage. It is ideal for mobile applications or web-based readers where storage and speed are priorities.
- Compressed, smaller file size
- Default response format
- Ideal for web and mobile
WAV
WAV delivers high-quality audio. This format is best for local playback on assistive hardware or when you need lossless audio for precise editing.
- Uncompressed, high fidelity
- Best for local playback
- Lossless quality
FLAC
FLAC offers lossless compression, maintaining original audio quality. It is suitable for archival purposes or high-end audio systems.
- Lossless compression
- Smaller than WAV
- Suitable for archival use
Handling Errors
When synthesizing speech for assistive devices or elderly care tools, reliable error handling ensures your application remains responsive. SageVoice provides clear status codes and detailed messages to help you diagnose issues quickly, keeping your audio generation pipeline stable.
Check Status Codes
The API returns standard HTTP status codes. A 200 OK means your audio is ready. Use 400 for bad requests (e.g., text too long) and 401 for authentication issues.
Review Error Messages
Each error response includes a descriptive message explaining the cause. This helps you adjust parameters like character count or voice selection without guessing.
Retry Failed Requests
If a request fails due to temporary server issues, retry it. Failed requests are free, so you can safely retry without worrying about extra charges.
- Implement exponential backoff for robustness.
- Retry only on 5xx server errors.

Rate Limits
Your API key allows 60 requests per minute once funded. This limit applies to all requests sent to the endpoint, ensuring fair usage across the network. If you exceed this rate, subsequent requests will be rejected until the window resets.
60 Requests Per Minute
The standard rate limit is 60 requests per minute per key. This allows you to generate audio for multiple assistive devices or elderly care applications simultaneously without significant delay.
10 Requests Before Top-Up
New accounts without a top-up are limited to 10 requests per minute. This ensures the free trial credit is not exhausted too quickly. Once you add USDT (TRC-20), the limit increases to 60 requests per minute.
- Start with 10 req/min if balance is zero.
- Top-up via USDT on TRON to unlock 60 req/min.
Monitor Usage
Track your request count and balance directly in the dashboard at /get-api-key/. The dashboard shows real-time usage, helping you plan audio generation for your accessibility tools without unexpected interruptions.
Splitting Long Texts
The API accepts up to 4096 characters per request. For longer texts, such as a full chapter for an elderly reader, you must split the input into smaller chunks before sending them to the endpoint.
Split into 4096 Character Chunks
Divide your text into segments of 4096 characters or less. Ensure you do not split mid-sentence if possible, to maintain natural audio flow. Each chunk generates a separate audio file.
Join Audio Files
After receiving the audio files for each chunk, concatenate them in the original order. Since the API returns standard audio formats, you can use any basic file merging tool to create a single continuous file, though the API does not provide built-in streaming or joining.
Handle Large Documents
This method works well for books, long articles, or detailed care instructions. Keep in mind that processing time adds up; long texts may take several seconds to generate per chunk due to queueing.
Language and Voice Selection
SageVoice offers eight distinct voice presets designed for clarity and natural flow, ideal for elderly care and assistive devices. You can choose from female voices like Aria for warm narration or Luna for soft storytelling, and male voices like Atlas for neutral news or Orion for deep documentary styles. Each voice is based on licensed recordings from LibriTTS-R (CC BY 4.0) and LibriVox public-domain audiobook readings.
Every voice supports all 23 available languages, allowing you to mix and match voices across different linguistic contexts without losing audio quality. This flexibility ensures your assistive tools sound natural for the 23 supported languages.
Choose from 8 Voices
Select a voice that matches your application's tone. Options include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Each voice has a distinct character, from energetic to calm, helping you tailor the audio experience for specific use cases like reading alarms or narrating stories.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
- All voices support 23 languages
Set Language Code
For best results, explicitly set the language parameter using ISO codes, especially for non-English texts. This ensures accurate pronunciation and intonation, preventing the engine from guessing incorrectly based on script alone.
The API supports Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
Automatic Detection
If you omit the language parameter, the system guesses the language from the text script. Latin script defaults to English. Explicitly setting the language is recommended for non-English Latin texts to avoid mispronunciation.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. The voice should sound warm and clear, avoiding harsh or monotone delivery that can cause listener fatigue over extended use.
23 languages
Any voice speaks any of these languages.
