Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.km12.info/v1. You send POST requests to https://api.km12.info/v1/audio/speech for synthesis. Other endpoints include GET /v1/voices and GET /v1/models. This structure ensures compatibility with standard HTTP clients and SDKs that expect a consistent base path for all API interactions.
Can I use the OpenAI Python SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.km12.info/v1 and using your site's key. This allows you to use familiar code structures. You do not need a custom SDK. Simply configure the client to point to our endpoint while maintaining the same request shape as the OpenAI speech endpoint.
How do I set the language for French text?
Include the optional 'language' field set to 'fr' in your JSON body. If omitted, the system guesses the language from the script. Since French uses Latin script, it defaults to English without explicit configuration. Setting the language parameter ensures accurate synthesis for non-English Latin-script text and prevents mispronunciation.
What happens if I exceed the rate limit?
Your limit is 60 requests per minute per key. Requests are processed sequentially, so exceeding this may cause your request to wait in a queue. If the queue backs up, generation time increases. Failed requests remain free, but successful ones consume your character balance. Monitor your usage to maintain consistent throughput.
Is the API key reusable across servers?
Yes, one active key per account works across any number of servers or environments. You can issue a new key at any time, which immediately invalidates the old one. This allows you to rotate credentials securely without changing your application logic, ensuring consistent authentication across all your deployment infrastructure.
How do I handle long texts over 4096 characters?
Split your input text into parts of up to 4096 characters. Send each part as a separate request to the speech endpoint. Then, join the resulting audio files programmatically. This approach ensures compatibility with the character limit while allowing you to generate audio for longer documents or scripts efficiently.
Does the API support streaming audio?
No, the API does not support streaming, WebSocket, or real-time partial audio. You receive the complete audio file in the response body. Requests are processed sequentially, so you must wait for synthesis to complete before receiving the data. This design simplifies integration but does not allow for real-time playback during generation.
What is the default voice if none is specified?
You must explicitly provide a voice parameter from the eight presets (aria, nova, luna, sage, felix, milo, atlas, orion).
How do I switch from tts-1 to tts-1-hd?
Change the 'model' field in your JSON body from 'tts-1' to 'tts-1-hd'. Both models use the same engine and price. The request shape remains identical. This allows you to switch quality levels without modifying other parameters like voice, speed, or response format, ensuring a seamless upgrade or downgrade in audio fidelity.
Are the audio files returned in the response body?
Yes, the generated audio is returned directly in the response body. The audio is not stored on our servers. Input text is used only for synthesis and not for training.
Can I use the same key for production and testing?
Yes, you can use the same API key for both production and testing environments. Each account has one active key. You can issue a new key at any time, which invalidates the old one immediately. This allows you to rotate keys for security without affecting your application's ability to authenticate across environments.
What happens if I lose my API key?
You can 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. This allows you to revoke access to lost or compromised keys instantly. You do not need to update your application code, only the key value.
Is there a webhook for completion notifications?
No, there is no webhook for completion notifications. The API is synchronous; you receive the audio file in the response after synthesis completes. Request metadata is kept for billing, but no real-time notifications are sent. You must poll or wait for the response to know when generation is finished.
How do I test the API before paying?
Sign in with Google to receive a free trial of $0.50 credit, valid for 7 days. This covers about 50,000 characters. Email-based accounts start without trial credit. Use this credit to test voices, languages, and formats before topping up with USDT (TRC-20). Failed requests are free, allowing risk-free testing.
First request
curl
curl https://api.km12.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.km12.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.km12.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 <key> in every request. Use the key generated in your dashboard.
You receive one active key per account. Generate a new key at any time; the previous key becomes invalid immediately.
Bearer token setup
Pass your API key in the Authorization header as a Bearer token. This authenticates all requests to https://api.km12.info/v1. Ensure the key is transmitted securely.
The token format is tts-.... Verify it matches the prefix in your dashboard credentials.
API key generation
Keys are created via the /get-api-key/ dashboard. Each account holds one active key. You can generate a replacement at any time.
A new key issuance revokes the old one instantly. Update your systems to avoid interruptions.
- Access via
/get-api-key/dashboard
Key rotation policy
Rotate keys immediately if compromised. The old key stops working at once upon issuing a new one. Plan for zero-downtime updates if multiple services use the same key.
No grace period exists for the old key. Ensure all consumers update their configuration before rotation.
Endpoints
The API exposes three primary endpoints for speech synthesis, voice discovery, and model metadata: POST /v1/audio/speech, GET /v1/voices, and GET /v1/models. All requests target the base URL https://api.km12.info/v1 and require a Bearer token for authentication.
POST /v1/audio/speech
Generates audio from text. Accepts JSON with model, input, voice, response_format, speed, and optional language. Returns the audio file directly in the response body.
GET /v1/voices
Returns available voices, supported languages, and format options. Use this to verify compatible voice presets before synthesis requests.
- Returns 8 voice presets
- Lists supported ISO language codes
- Confirms available audio formats
GET /v1/models
Lists available models, specifically tts-1 and tts-1-hd. Both use the same engine and pricing tier.
Request Parameters
The API accepts plain text input up to 4096 characters per request. This limit applies to the raw character count, including spaces and punctuation. For longer radio scripts, split the text into chunks and concatenate the resulting audio files.
Input text limit
Each request processes a maximum of 4096 characters. Exceeding this limit returns an error. For extended commercials, divide the script into segments and merge the outputs server-side or via your application logic.
- Maximum length: 4096 characters
- Includes spaces and punctuation
- Longer texts require manual splitting
Voice selection
Select one of eight preset voices: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice offers a distinct tone suitable for different advertising contexts, from upbeat promos to calm narration.
- 8 available presets
- No custom cloning available
Response format
Choose between mp3, wav, opus, flac, or pcm formats. MP3 is recommended for general use due to its balance of quality and file size. WAV provides uncompressed audio for professional editing workflows.
- Supported: mp3, wav, opus, flac, pcm
- Default format: mp3
- Uncompressed option: wav
Speed Settings
The speed parameter allows precise control over speech pacing, accepting values between 0.25 and 4.0. This range enables optimization for different voice types and content density, ensuring synthetic audio matches the intended delivery style for radio spots or localized advertising content.
Adjusting speed affects generation time and character throughput. Slower rates improve clarity for complex narratives, while faster rates suit brief promotional messages. The API processes requests sequentially, so speed adjustments may influence queue wait times under load.
Range 0.25 to 4.0
Speed values are floating-point numbers. Values below 1.0 slow the speech; values above 1.0 accelerate it.
Extreme speeds may reduce intelligibility for certain voice presets. Test specific combinations with your content before scaling production deployments.
Default speed
The default speed is 1.0. This setting provides a balanced pace suitable for most general-purpose text-to-speech applications.
Using the default ensures consistent audio length predictions, which is critical for scheduling radio spot slots accurately.
Adjusting for radio
For advertising agencies producing radio spots, speed adjustments help fit specific voiceovers into fixed time slots. A 15-second spot may require faster pacing than a 30-second narrative.
Combine speed settings with voice selection to achieve the desired tonal quality.
- Optimize for clarity: slower speeds improve listener comprehension for complex product details.
- Balance length: faster speeds reduce generation time but may sacrifice nuance.
- Test edge cases: verify audio quality at 0.25x and 4.0x before bulk generation.
Language Handling
AuraCast supports 23 languages, from Arabic to Turkish. Explicitly setting the language parameter via ISO code ensures accurate synthesis, particularly for non-English texts using Latin script.
Proper language configuration prevents mispronunciation and maintains the intended tone for localized radio spots and advertising content.
ISO code specification
Pass the language field with a valid ISO 639-1 code (e.g., de for German, fr for French). This guarantees the engine selects the correct phonetic rules for the provided text.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Automatic detection
The API attempts to guess the language from the input script when the language field is omitted. This works reliably for standard scripts but may fail for mixed-language content.
Latin script defaults
If language is not set and the text uses Latin characters, the system defaults to English. For any non-English Latin text (e.g., Spanish or German), you must explicitly specify the language code to avoid English pronunciation artifacts.

Error Handling
The API returns standard HTTP status codes to indicate request outcomes. A 200 OK response confirms successful audio synthesis and returns the binary audio data. Clients should validate the HTTP status before attempting to parse the response body.
For persistent issues, verify the request payload structure and ensure the authentication header is correctly formatted. If the error persists, contact support via email.
Common HTTP errors
The API uses standard HTTP status codes to indicate request outcomes. A 200 OK response confirms successful audio synthesis and returns the binary audio data. Clients should validate the HTTP status before attempting to parse the response body.
- 400 Bad Request: Invalid JSON body or missing required fields.
- 401 Unauthorized: Invalid or expired API key.
- 429 Too Many Requests: Rate limit exceeded.
- 500 Internal Server Error: Temporary service issue.
Rate limit responses
When the request limit is exceeded, the API returns a 429 status code. The response includes a Retry-After header indicating the seconds to wait before the next request. For new accounts, the limit is 10 requests per minute; after the first top-up, it increases to 60 requests per minute.
- 429 Too Many Requests: Retry after the specified seconds.
- Check the Retry-After header for exact wait time.
- Monitor usage via the dashboard to anticipate limits.
Invalid voice codes
If a voice ID not in the supported list is provided, the API returns a 400 Bad Request error. The supported voices are aria, nova, luna, sage, felix, milo, atlas, and orion. Verify the voice code against the GET /v1/voices endpoint before making synthesis requests.
- 400 Bad Request: Invalid voice ID.
- Valid voices: aria, nova, luna, sage, felix, milo, atlas, orion.
Rate Limits
The API enforces a standard rate limit of 60 requests per minute per active key. This cap ensures consistent processing performance for high-volume advertising workflows. Each request counts toward this limit, regardless of text length or audio format selected.
60 requests per minute
Standard accounts operate under a 60 requests per minute threshold. This limit applies uniformly to all endpoints and request types, including model and voice metadata queries. Exceeding this threshold triggers a 429 Too Many Requests response.
- Both POST and GET requests consume rate limit quota.
Initial limit 10 req/min
New accounts begin with a restricted limit of 10 requests per minute. This constraint remains active until the first top-up is processed. After a minimum $5 USDT (TRC-20) transfer is confirmed, the limit increases to the standard 60 requests per minute automatically.
- No top-up required for basic trial credit usage.
- Limit upgrade occurs within minutes of transfer confirmation.
- Initial limit prevents accidental high-volume charges on unverified accounts.
Queue behavior
Queue behavior
Requests are processed one after another. Under heavy load, additional requests may wait in a queue before synthesis begins. This ensures fair resource distribution but may increase latency for burst traffic. Plan your integration to avoid simultaneous bursts.
- Processing is sequential, not parallel.
- Queue wait times vary based on current server load.
- Short phrases may take several seconds to generate.
Code Examples
Integrate AuraCast into your production pipeline using standard HTTP requests or the OpenAI SDK. The API accepts JSON bodies with text, voice, and format parameters, returning synthesized audio files ready for broadcast or localization workflows.
For rapid testing, use the provided curl command. For production environments, configure the base URL to https://api.km12.info/v1 and authenticate with your Bearer token. Python users can leverage the official OpenAI SDK.
Curl command example
Use this command to generate speech immediately. Replace YOUR_API_KEY with your active token and adjust the voice and format parameters as needed for your radio spot or localized content.
- curl -X POST https://api.km12.info/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}'
OpenAI SDK configuration
The API endpoint mirrors the OpenAI speech structure, allowing you to use the official OpenAI SDKs by simply changing the base URL. This ensures compatibility with existing client libraries and simplifies migration for teams already familiar with the OpenAI pattern.
Python integration
Install the openai package and initialize the client with your custom base URL. Pass your text, voice selection, and desired audio format to the speech method. The response contains the binary audio data, which can be saved directly to disk or streamed to your broadcasting infrastructure.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This ensures that your radio spots maintain the same tonal quality and pacing across all episodes and campaigns.
23 languages
Any voice speaks any of these languages.
