Frequently asked questions
How do I get an API key?
Sign up at https://123h.info/get-api-key/ using Google or email. Accounts are per site. Google sign-ups receive a $0.50 trial credit valid for 7 days. Email-based accounts start without trial credit. Your key appears on the dashboard alongside your balance and usage statistics.
What is the base URL?
The API base URL is https://api.123h.info/v1. You use this endpoint for all requests. The standard endpoint is POST https://api.123h.info/v1/audio/speech. Use this base URL when configuring your HTTP client or SDK to ensure requests reach the correct service.
Does the API support streaming?
No, the API does not support streaming or WebSocket connections. Audio is returned as a complete file in the response. You receive the full audio data only after synthesis finishes. This means you cannot process partial audio chunks in real-time during generation.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work perfectly. Change the base_url to https://api.123h.info/v1 and use your FableSonic key. The request shape matches the OpenAI speech endpoint exactly. This allows you to use familiar code structures without learning a new library interface.
What is the character limit?
Each request supports up to 4096 characters of input text. For longer stories, split your text into parts of this size and join the resulting audio files. Spaces and punctuation count toward the character limit. This ensures consistent processing performance for each individual request.
How do I handle rate limits?
You are limited to 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so under load, they may wait in a queue. Monitor your usage to avoid delays in generation.
What formats are available?
You can choose from mp3, wav, opus, flac, and pcm formats. Specify the desired format using the response_format field in your request. These options allow you to select the best balance between file size and quality for your specific children's story distribution needs.
Is SSML supported?
No, the API does not support SSML. You cannot use phoneme dictionaries or custom pronunciation lexicons. Voice control is limited to the eight preset voices and speed adjustments. For specific pronunciation needs, you must adjust the input text directly before sending it to the API.
How do I change my API key?
Issue a new key from your account dashboard at any time. The new key becomes active immediately, and the old one stops working at once. You can generate a fresh key if the previous one is compromised or if you want to rotate credentials for security.
What happens if I exceed the limit?
Requests are processed one after another, so exceeding the limit causes your request to wait in a queue. Failed requests are free.
Can I generate audio in parallel?
Requests are processed one after another, so under load a request may wait in a queue. This means under load, a request may experience delays. You can split long texts into parts, but each part is still processed in order. Plan your generation workflow accordingly to manage timing.
How do I specify a language?
Set the optional language parameter to an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly setting the language ensures accurate synthesis. Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
What is the speed range?
The speed parameter accepts values between 0.25 and 4.0. This allows you to adjust the narration pace for your stories. Faster speeds reduce generation time, while slower speeds may provide clearer articulation for young listeners. Adjust this value to match the tone of your narrative.
Are there version numbers for the API?
The API uses model identifiers tts-1 and tts-1-hd to denote engine quality. These models share the same engine and price. There are no explicit API version numbers like v2 or v3. The endpoint path remains /v1/audio/speech, ensuring consistent access to the current service version.
First request
curl
curl https://api.123h.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.123h.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.123h.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
The API requires a Bearer token for authentication. Include the header Authorization: Bearer tts-... in every request to verify your identity and charge your account correctly.
Bearer token usage
Send your key as a Bearer token in the Authorization header. The API validates this token to process your text-to-speech requests and deduct characters from your balance.
Key management
You receive one active key per account. You can issue a new key at any time via the dashboard. The previous key stops working immediately upon generation, ensuring seamless rotation without service interruption.
Security best practices
Treat your key like a password. Store it securely in your application’s environment variables rather than hardcoding it in client-side scripts or version control systems to prevent unauthorized usage of your credit.
Endpoints
The API exposes three primary endpoints to manage your TTS generation workflow. The core speech endpoint accepts your story text and voice preferences, while the voices and models endpoints provide the metadata needed to select the right narrator and format.
POST /v1/audio/speech
This is the main endpoint for generating audio. Send a JSON body with your text (up to 4096 characters), a voice preset, and desired format. The API returns the audio file directly in the response.
- Endpoint: POST https://api.123h.info/v1/audio/speech
- Body: JSON with
model,input,voice,response_format
GET /v1/voices
Retrieve the full list of available voices, their associated languages, and supported audio formats. This helps you choose between options like Aria for warm narration or Felix for energetic promos.
- Endpoint: GET https://api.123h.info/v1/voices
- Returns: Voice ID, name, gender, and supported languages
GET /v1/models
Check the available models, such as tts-1 and tts-1-hd. Both use the same engine and price, allowing you to switch between standard and high-definition outputs without changing your code structure.
- Endpoint: GET https://api.123h.info/v1/models
- Models:
tts-1,tts-1-hd
Request Parameters
Configure your synthesis requests with precision using the available parameters. The API accepts a concise JSON body, allowing you to define the voice model, input text, and audio settings in a single call.
Model selection
Choose between "tts-1" or "tts-1-hd" for your audio generation. Both models use the same engine and pricing, but they produce different audio quality levels.
Input text limit
Send up to 4,096 characters per request. Longer narratives should be split into chunks and joined after generation to ensure consistent audio quality and manageable processing times.
- Spaces and punctuation count toward the 4,096 character limit.
- Split long texts into smaller segments for better queue management.
Voice and speed settings
Select one of eight preset voices, such as Luna for soft storytelling or Felix for energetic promos. Adjust the speed between 0.25 and 4.0 to match the pacing of your narrative.
- Voice presets include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion.
- Speed range: 0.25x to 4.0x.
Response Formats
Each synthesis request returns the generated audio file directly in the response body, allowing you to save or stream the content immediately. The format you receive is determined by the response_format field in your request, ensuring compatibility with your specific playback environment or editing software.
MP3 support
MP3 is the default format, offering a balance of quality and file size suitable for web players and most audiobook platforms. It efficiently compresses the audio while maintaining clear voice reproduction for children's stories.
WAV and FLAC options
WAV provides uncompressed, high-fidelity audio ideal for professional editing or archival purposes. FLAC offers lossless compression, reducing file size without sacrificing any audio quality, making it perfect for storing master recordings of animated stories.
OPUS and PCM
OPUS is a supported audio format for the response. PCM returns raw, uncompressed audio data, useful for direct processing or specific hardware integrations that require raw audio streams.
Rate Limits
Requests are processed one after another, so under load a request may wait in a queue. This linear processing ensures stability but requires careful pacing when producing longer stories or batches of narration assets.
60 requests per minute
Once your account is funded, the API allows up to 60 requests per minute. This limit applies per API key, so ensure you are monitoring your usage dashboard to stay within bounds during heavy production days.
10 requests before top-up
New accounts starting with the free trial credit are restricted to 10 requests per minute. This lower limit helps manage server load during the trial phase and ensures reliable service as you evaluate the voice quality.
Queue handling
Under load, requests may wait in a queue. Typical speed is roughly real-time (25 characters per second), but short phrases take a few seconds. Longer texts are split into 4096-character parts and joined, which can increase total generation time significantly.

OpenAI SDK Integration
The FableSonic API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing client libraries with minimal configuration. By simply pointing your SDK’s base URL to https://api.123h.info/v1, you can generate audio using the same tts-1 or tts-1-hd models.
Base URL configuration
Update your client’s base URL to https://api.123h.info/v1 and inject your API key via the Authorization: Bearer header. This single change enables full compatibility with the official OpenAI SDKs, treating FableSonic as a drop-in replacement for the standard speech endpoint.
- Base URL:
https://api.123h.info/v1 - Auth Header:
Authorization: Bearer tts-...
SDK compatibility
Since the request shape matches the OpenAI standard, any SDK supporting the speech endpoint works directly. You can manage voices, adjust speed, and select formats like MP3 or WAV without writing custom HTTP clients, streamlining integration for story creators.
Code examples
Use the standard client.audio.speech.create() method, passing your text, desired voice (e.g., aria or atlas), and output format. The SDK handles the JSON payload and returns the audio file ready for embedding in your children’s content.
Ensure your text input respects the 4096-character limit per request. For longer stories, split the text programmatically before passing it to the SDK to maintain audio quality and avoid truncation.
Error Handling
The API returns standard HTTP status codes to indicate success or failure. Understanding these responses helps you debug issues quickly without unnecessary delays in your narration workflow.
Most errors are transient. Implementing exponential backoff for temporary failures ensures your audiobook generation pipeline remains stable even during peak usage hours.
Common error codes
400 Bad Request: The input text exceeds 4096 characters or the voice ID is invalid. Review your payload structure.
429 Too Many Requests: You have exceeded the rate limit. See the Rate Limits section for details on queue handling.
500 Server Error: A temporary issue on our side. Retry after a short delay.
- Always check the
errorobject in the JSON response for specific details. - Ensure your input text is UTF-8 encoded to avoid encoding errors.
Retry logic
For 429 and 5xx errors, implement exponential backoff with jitter. Start with a 1-second delay and double it for each subsequent attempt, up to a maximum of 30 seconds.
Do not retry 400 errors as they will likely fail again. Instead, log the error and notify the content creator to correct the input text.
- Maximum retry attempts: 5.
- Log all retry attempts for debugging purposes.
Billing errors
402 Payment Required: Your account balance is insufficient to cover the request. Top up via USDT on TRON to resume service.
401 Unauthorized: Your API key is invalid or expired. Generate a new key from your dashboard.
- Failed requests are free.
- Check your balance regularly to avoid interruptions during long storytelling sessions.
Quick Start Example
This section provides immediate, copy-pasteable examples to generate your first audio file. You can use a simple command line or integrate directly into your preferred programming language. Each example targets the tts-1 model with the nova voice, suitable for upbeat children’s stories.
Ensure your API key is active and your account has sufficient balance. The examples assume a standard text length under 4,096 characters, which is the limit for a single request. For longer stories, you will need to split the text and join the resulting audio files.
Curl command
Use this command to send a POST request to the speech endpoint. Replace YOUR_API_KEY with your actual key from the dashboard.
The response returns the audio file directly. Save it to your local drive with the .mp3 extension for immediate playback.
curl -X POST https://api.123h.info/v1/audio/speech-H 'Authorization: Bearer YOUR_API_KEY'-H 'Content-Type: application/json'- `-d '{"model": "tts-1", "input": "Once upon a time...", "voice": "nova", "response_format": "mp3"}'`
Python script
Install the OpenAI Python package via pip. Configure the base URL to point to our API instead of OpenAI’s. This allows you to use the familiar SDK methods for authentication and request handling.
Pass your text and desired voice parameters. The SDK handles the JSON serialization and returns the audio content as bytes, which you can write to a file.
import openaiclient = OpenAI(base_url='https://api.123h.info/v1', api_key='YOUR_API_KEY')response = client.audio.speech.create(...)
JavaScript example
Use the openai npm package in your Node.js environment. Set the baseURL to our API endpoint. This ensures that all subsequent calls use your credentials and our infrastructure.
Call the audio.speech.create method with your story text. Handle the response to save the generated audio file to your project directory.
const { OpenAI } = require('openai');const client = new OpenAI({ baseURL: 'https://api.123h.info/v1', apiKey: 'YOUR_API_KEY' });const response = await client.audio.speech.create(...);
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. These voices maintain engagement without sounding overly dramatic.
23 languages
Any voice speaks any of these languages.
