Frequently asked questions
What is the API endpoint URL?
The endpoint is POST https://api.hajee.info/v1/audio/speech. You send a JSON body containing your text and parameters to this URL. It follows the same request shape as the OpenAI speech endpoint, allowing you to integrate it directly into your existing workflows without learning a new structure.
How do I authenticate my requests?
Include your API key in the Authorization header as a Bearer token: Authorization: Bearer tts-... . Each account has one active key. If you issue a new key, the old one stops immediately, so ensure your application uses the current valid key for all requests.
Which models are available?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and have the same price. You can choose between them based on your quality preferences, but they offer identical audio generation capabilities and pricing structures for your language learning content.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.hajee.info/v1 and using your site-specific key. This allows you to use familiar code structures without rewriting your integration logic, making it easy to adopt our TTS API into your existing projects.
What is the rate limit per minute?
You are limited to 60 requests per minute per key. Before your first top-up, this limit is 10 requests per minute. If you exceed the limit, requests may wait in a queue. Plan your batch generation accordingly to avoid delays in your production pipeline.
How do I specify a language?
Include an optional ISO language code in your request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always set the language parameter to ensure accurate pronunciation and voice selection.
What formats can I download?
You can choose from mp3, wav, opus, flac, and pcm formats. Select the format that best fits your distribution channel. MP3 is suitable for web streaming, while WAV or FLAC may be preferred for high-quality archival or editing purposes in your language learning materials.
How do I handle errors?
Failed requests are free: if synthesis fails, the charge is returned in full. Monitor your response status codes to detect errors. If a request fails, you can retry it without incurring additional costs, ensuring you only pay for successfully generated audio files.
Is there a free tier?
Signing in with Google provides a $0.50 trial credit valid for 7 days, enough for about 50,000 characters. Email-based accounts start without trial credit. There is no monthly plan or minimum spend, so you only pay for what you use, starting with your top-up.
Can I change my API key?
Yes, you can issue a new key at any time from your account dashboard. When a new key is issued, the old one stops immediately. This allows you to revoke access quickly if needed, ensuring secure management of your API credentials across different projects.
How long are requests processed?
Typical speed is roughly real-time, generating about 25 characters of text per second of audio. Short phrases may take a few seconds. Requests are processed sequentially, so under load, a request may wait in a queue before being synthesized and returned to you.
Do I need to install dependencies?
You can use the official OpenAI SDK by adjusting the base_url, or use plain HTTP requests. No proprietary SDK is required. For plain HTTP, you only need a standard HTTP client library in your preferred language to send POST requests with JSON bodies.
Can I stream the audio?
No, the API does not support streaming or WebSocket connections. Audio is returned as a complete file in the response. You must wait for the full synthesis to complete before receiving the audio data, which is suitable for batch processing rather than real-time playback.
How do I check my usage?
Visit the /get-api-key/ page on our site to view your balance, trial status, characters left, and usage history. The dashboard provides a ready curl example and real-time statistics, allowing you to monitor your consumption and manage your top-ups efficiently.
First request
curl
curl https://api.hajee.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.hajee.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.hajee.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 API Key
Access the SonicLingo API by generating a Bearer token from the /get-api-key/ dashboard. This single key authenticates all requests via the Authorization: Bearer tts-... header, ensuring secure identification for your language learning content generation workflows.
Generate Your Bearer Token
Create your key directly on the site's authentication page. The dashboard displays your active token alongside your current balance and character usage, providing immediate visibility into your API credentials without navigating external portals.
Single Active Key Per Account
Each account maintains one active key at a time. This simplifies security management for independent creators, as you do not need to track multiple rotating tokens across different development environments or video production pipelines.
Revoke and Regenerate Keys
Issue a new key at any moment via the dashboard. The previous key stops working immediately, allowing you to quickly revoke access if a key is exposed or if you are transitioning between different language lesson projects.
Endpoint: POST /v1/audio/speech
The POST /v1/audio/speech endpoint is the core of the SonicLingo API. Send a JSON payload to receive synthesized audio files instantly. This single endpoint handles all generation tasks, from short practice phrases to longer lesson segments.
JSON Request Body Structure
The request body must be a valid JSON object. It contains the model identifier, the text input, and optional configuration parameters. The API validates the structure before processing, ensuring consistent behavior for language learning creators generating bulk audio.
Required Fields: Model and Input
Every request requires the model field set to either tts-1 or tts-1-hd. The input field accepts up to 4096 characters of text. Spaces and punctuation count toward this limit. For longer lessons, split text into multiple requests and join the resulting audio files.
- Model:
tts-1ortts-1-hd - Input: String up to 4096 characters
Optional Parameters: Voice and Speed
Specify a voice from the 8 presets (e.g., aria, felix) to maintain consistent narration across your video lessons. The speed parameter ranges from 0.25 to 4.0, allowing you to adjust playback for different proficiency levels.
- Voice: One of 8 presets
- Speed: 0.25–4.0
Supported Models and Formats
The API offers two model variants, tts-1 and tts-1-hd, which utilize the same underlying engine and pricing structure. Both accept identical request parameters, allowing you to switch between them without changing your integration logic. The choice depends on your audio quality requirements versus processing speed needs.
tts-1 Standard Model
The tts-1 model provides a balance of quality and speed for standard language learning content.
tts-1-hd High Definition Model
The tts-1-hd model delivers enhanced audio fidelity, ideal for educational materials where clarity is paramount. It maintains the same pricing of $0.01 per 1,000 characters as the standard model, ensuring consistent costs regardless of the selected quality tier.
Output Formats: MP3, WAV, OPUS
You can specify the output format using the response_format field in your request. Supported formats include MP3 for web compatibility, WAV for uncompressed high-quality audio, and OPUS for efficient streaming or storage. FLAC and PCM are also available for specific use cases.
- MP3: Best for web playback and small file sizes.
- WAV: Uncompressed audio.
- OPUS: Efficient compression for storage.
- FLAC: Lossless compression for archival quality.
- PCM: Raw audio data without encoding.
Voice Selection and Language
The API provides eight distinct voice presets, each designed for specific educational contexts. Female voices include Aria for clear narration, Nova for upbeat lessons, Luna for storytelling, and Sage for instructional content. Male options include Felix for energetic promos, Milo for conversational practice, Atlas for neutral news-style delivery, and Orion for deep documentary tones.
8 Preset Voices Available
Each voice is derived from licensed LibriTTS-R recordings and public-domain audiobooks, ensuring consistent quality across thousands of generated tracks. You can select any voice regardless of the target language, allowing you to maintain a consistent narrator identity across different language modules in your course.
- 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
Setting the Language Code
You can explicitly specify the language using an ISO code (e.g., 'es', 'fr', 'de') in the request body. This ensures the model applies the correct phonetic rules and intonation patterns for the target language, which is critical for accurate pronunciation in language learning materials.
Auto-Detection for Latin Script
If you omit the language parameter, the system guesses the language based on the input script. Text in Latin script defaults to English. For non-English Latin-script text, you must set the language field explicitly to avoid incorrect accentuation or pronunciation errors.
Rate Limits and Performance
Rate limits govern how many requests your API key can process per minute. Understanding these constraints helps you plan batch generation for language learning materials without hitting throttling walls unexpectedly.
60 Requests Per Minute Limit
Each active API key supports a maximum throughput of 60 requests per minute. This limit applies uniformly regardless of model choice, allowing consistent planning for your audio generation pipelines.
Initial 10 RPM for New Keys
Newly created keys start with a reduced limit of 10 requests per minute. This lower threshold remains in effect until you complete your first top-up, after which the limit increases to the standard 60 RPM.
Queue Processing Under Load
Requests are processed sequentially. During high demand, additional requests may wait in a queue before synthesis begins. Expect roughly real-time generation speed, averaging about 25 characters of text per second of audio output.

Error Handling and Status Codes
The API returns specific HTTP status codes to indicate request outcomes. Understanding these responses helps you handle failures gracefully in your language learning workflow without losing sync with your content generation pipeline.
Each error type corresponds to a distinct issue, from invalid parameters to authentication failures. You should implement retry logic for transient issues and log errors for debugging persistent configuration problems.
400 Bad Request Examples
A 400 response indicates the request body is malformed or missing required fields. Common causes include exceeding the 4096 character limit for the input field or providing an invalid voice preset name.
- Ensure
inputdoes not exceed 4096 characters. - Verify
voicematches one of the 8 available presets. - Check that
response_formatis one of mp3, wav, opus, flac, or pcm.
401 Unauthorized Responses
This error occurs when the Authorization header is missing or contains an invalid or revoked bearer token. Since each account has only one active key, generating a new key immediately invalidates the old one.
- Ensure the header format is
Authorization: Bearer tts-.... - Check if the key was recently regenerated.
- Verify the key has sufficient balance or trial credit.
429 Too Many Requests
A 429 status means you have exceeded the rate limit of 60 requests per minute. New keys start with a stricter limit of 10 requests per minute until the first top-up is processed.
- Implement exponential backoff for retry logic.
- Monitor your usage dashboard for current RPM.
- Wait for the rate limit window to reset before retrying.
Using the OpenAI SDK
The official OpenAI Python SDK handles the request lifecycle, leaving only the endpoint configuration as a deviation from standard usage. By overriding the base_url property, you direct traffic to the SonicLingo infrastructure while retaining familiar method signatures for speech generation.
This approach requires no custom client library or wrapper code. You continue using standard object instantiation and parameter passing, ensuring your integration remains compatible with the broader OpenAI ecosystem while leveraging our specific voice models and pricing structure.
Change Base URL to Our Domain
Initialize the OpenAI client as usual, then immediately assign the API base URL to point to our domain. This single line redirect ensures all subsequent API calls route through https://api.hajee.info/v1 without altering the rest of your codebase.
The base URL structure mirrors OpenAI’s, allowing direct substitution. You do not need to adjust headers or authentication logic, as the SDK automatically handles the bearer token provided in your client initialization.
- Set
base_url="https://api.hajee.info/v1"after client instantiation - No additional headers are required beyond the standard Authorization token
- The SDK handles JSON serialization and multipart responses automatically
Standard SDK Compatibility
The API accepts the exact JSON body shape expected by the OpenAI speech endpoint. Parameters like model, input, voice, and response_format map directly to SDK arguments. This compatibility extends to error handling and rate limit headers, making migration seamless.
Since the SDK manages the HTTP connection and retry logic, you benefit from existing stability features. The only deviation is the domain, which means your existing unit tests and integration patterns remain valid with minimal configuration changes.
- Supports standard parameters:
model,input,voice,speed,response_format - Error codes (400, 401, 429) are returned in standard JSON format
- Audio data is returned as binary, handled by the SDK's response parsing
Example Code Snippet
The following Python snippet demonstrates initializing the client with the custom base URL and generating audio. Replace YOUR_API_KEY with your key from the dashboard. The response contains the audio bytes, which can be saved directly to a file.
This example uses the tts-1 model with the nova voice. The SDK handles the HTTP POST request and returns the audio data, which you can then write to disk or stream to a player.
- Ensure the OpenAI Python package is installed via
pip install openai - The
audioobject contains the raw bytes of the generated speech - Save the response directly to an MP3 or WAV file for playback
Testing Your First Request
To verify your integration, start with a minimal curl request or a Python script using the OpenAI SDK. Ensure your API key is correctly passed in the Authorization header and that the base URL points to https://api.hajee.info/v1.
Run the example to generate a short audio clip. Check the response headers for status codes and inspect the returned audio file to confirm the voice and language match your parameters before scaling to your lesson content.
Curl Command Example
Use this command to generate a 5-second clip of the 'nova' voice speaking in English. Replace YOUR_API_KEY with your actual key.
Curl returns the audio file directly to stdout, which you can redirect to a file for immediate playback.
- POST https://api.hajee.info/v1/audio/speech
- --header 'Authorization: Bearer YOUR_API_KEY'
- --data '{"model": "tts-1", "input": "Hello, welcome to our language lesson.", "voice": "nova", "response_format": "mp3"}'
Python Script Example
Install the official OpenAI Python library (pip install openai) and configure the base URL to our API endpoint.
Set the API key using the environment variable OPENAI_API_KEY or pass it explicitly to the client initialization.
- from openai import OpenAI
- client = OpenAI(base_url="https://api.hajee.info/v1", api_key="YOUR_API_KEY")
- audio = client.audio.speech.create(model="tts-1", voice="nova", input="Practice listening.")
- with open("output.mp3", "wb") as f:
- f.write(audio.content)
Verifying Audio Output
Play the generated file to confirm clarity and appropriate speed for your language learners.
Check that the voice matches your selection and that the language is correctly rendered, especially for non-English texts where you specified the language parameter.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This is critical for beginners who are still developing their auditory processing skills for new sounds and rhythms.
23 languages
Any voice speaks any of these languages.
