Developer Guide to TTS API Integration and Usage

By AuraCast editorial team · Updated 2026-11-19

This guide provides the technical specifications for integrating the AuraCast text-to-speech API into your production pipelines. It details the request structure, authentication requirements, and rate limits for generating audio from text. You will find the exact endpoints, parameters, and error codes necessary for reliable implementation in startup or agency environments.

The documentation is designed for developers who need to incorporate synthetic voice generation into advertising workflows or localized content systems. It includes ready-to-use curl commands and OpenAI SDK configurations, allowing you to begin testing immediately with the provided base URL and key format.

Developer Guide to TTS API Integration and Usage

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

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

Authentication

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

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

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

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

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

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

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

Language Handling

Error Handling

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

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

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

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

More on this site