Getting Started with SageVoice Text-to-Speech API

By SageVoice editorial team · Updated 2026-11-19

This guide helps you generate natural speech for elderly care and accessibility tools using our simple text-to-speech API. You will learn how to sign up, create your first audio file, and integrate SageVoice into your workflows without complex code or our own SDK.

We focus on clear, reliable audio generation with transparent pricing. Whether you are building assistive devices or creating content for non-technical users, this page provides concrete steps to get started quickly. You will find ready-to-use examples for testing voices, handling errors, and managing your API key securely.

Getting Started with SageVoice Text-to-Speech API

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

Python (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
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

Get Your API Key

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

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

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

Sound wave illustration for: 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-1 with tts-1-hd for a different model (same engine, different price).
  • Change nova to 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

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

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

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

Rate Limits

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

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

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

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. openai-node on GitHub
  3. OpenAI API reference: create speech
  4. Creative Commons Attribution 4.0
  5. Tether (USDT)
  6. TRON developer hub: TRC-20
  7. MDN: Web Speech API
  8. ISO 639 language codes
  9. Node.js documentation
  10. W3C WAI: making audio and video accessible
  11. curl documentation
  12. FFmpeg documentation

More on this site