Frequently asked questions
Which Python library should I use?
You can use the official OpenAI Python SDK or plain HTTP requests. The API endpoint matches the OpenAI speech endpoint shape, so changing the base_url allows you to use standard SDK methods.
Can I use the OpenAI SDK with this API?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.innwa.info/v1. You simply point the SDK to our API base and use your NewsBrio key. This allows you to use familiar methods like client.audio.speech.create with our endpoint.
How do I handle the 4096 character limit?
Split your input text into parts of up to 4096 characters. Generate audio for each part separately, then join the resulting audio files. This approach ensures you stay within the single-request limit while producing a continuous audio file for longer editorial content.
What is the difference between tts-1 and tts-1-hd?
Both models use the same engine and price. The only difference is the model identifier string you send in the request. You can choose either 'tts-1' or 'tts-1-hd' without any change in cost or performance characteristics for your news audio generation workflow.
Does the API support streaming audio?
No, the API does not support streaming, WebSocket, or real-time partial audio. You send a text request and receive the complete audio file in the response. For news workflows, this means you wait for the full synthesis before playing or storing the file.
How do I set the language explicitly?
Include the optional 'language' field with an ISO code in your JSON body. If omitted, the system guesses the language, defaulting to English for Latin script. Explicitly setting it ensures correct pronunciation for non-English texts like German, French, or Spanish news articles.
Can I generate audio in multiple languages in one call?
No, each request generates audio for a single language based on the voice and optional language parameter. To produce multi-language audio, you must make separate requests for each language segment. The API does not mix languages within a single audio output file.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. Failed requests are free, so you are not charged for attempts that do not complete. You can monitor your usage in the account dashboard.
Is the API key the same for all environments?
You have one active key per account. You can use this same key across development, staging, and production environments. If needed, you can issue a new key at any time, which immediately invalidates the previous one, ensuring secure access control across your team.
Do I need to install a specific version of Python?
The API works with any Python version that supports the requests library or the OpenAI SDK. There is no specific Python version requirement. As long as your environment can send HTTP POST requests or use standard SDKs, it will integrate seamlessly with our endpoint.
How do I decode the binary audio response?
The API returns binary audio data in the response body. You can write this directly to a file with the requested format (mp3, wav, opus, flac, or pcm). No additional decoding is needed; the file is ready to play or store immediately upon receipt.
Can I use async requests in Python?
Yes, you can use async requests by utilizing the async capabilities of the OpenAI SDK or libraries like aiohttp. Since the API is standard HTTP, any async Python HTTP client can interact with the endpoint.
Is there a mock endpoint for testing?
No, there is no separate mock endpoint for testing. You use the same production endpoint at https://api.innwa.info/v1. You can test with your free trial credit or by making small requests. The API behaves identically in test and production environments.
How do I verify the audio file format?
Specify the desired format using the 'response_format' field (mp3, wav, opus, flac, or pcm). The returned file will match this format exactly. You can verify the format by checking the file extension or using standard media tools to confirm the audio codec.
First request
curl
curl https://api.innwa.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.innwa.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.innwa.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 |
Getting Your API Key
Access the /get-api-key/ page to create your account using either Google or a standard email and password combination. Each account is tied to the innwa.info site, so ensure you are on the correct domain before proceeding.
Sign up via Google or email
Google sign-ups receive a $0.50 free trial credit valid for seven days, while email accounts start with a zero balance. This allows immediate testing without payment setup.
- Google sign-up includes $0.50 trial credit
- Email accounts start with zero balance
- Accounts are specific to innwa.info
Find your key on the dashboard
Your unique API key appears on the dashboard alongside your current balance, character usage, and a ready-to-use cURL example. This key authenticates all requests to the API.
Regenerate key if compromised
You can issue a new key at any time. When you generate a replacement, the old key stops working immediately, ensuring quick security response without downtime.
First Request with cURL
Use cURL to send your first synthesis request directly to the endpoint. This method requires no library installation and works in any terminal, making it ideal for quick testing of your NewsBrio API integration.
The request body is JSON. You must specify the model, input text, voice, and desired audio format. The API returns the audio file in the response body.
Basic POST request structure
Send a POST request to https://api.innwa.info/v1/audio/speech. Include the model (tts-1 or tts-1-hd), your text input (max 4096 characters), and the voice preset in the JSON body.
Example command: `curl -X POST https://api.innwa.info/v1/audio/speech -H 'Content-Type: application/json' -d '{"model": "tts-1", "input": "Breaking news update", "voice": "atlas"}'`.
Setting the Authorization header
Include your API key in the Authorization header as a Bearer token. This authenticates your request and deducts characters from your balance.
Format: -H 'Authorization: Bearer tts-your-api-key-here'. Ensure the key is valid and not expired.
Receiving audio in MP3 format
Specify response_format: mp3 in your request body for small, widely compatible files. The API returns the binary audio data directly in the response.
Save the output to a file using > output.mp3 in your terminal command for immediate playback or CMS integration.
Using the OpenAI SDK
The OpenAI Python library is our recommended integration method for news product teams. It provides a familiar interface that requires minimal configuration changes to your existing workflows. You can leverage the official SDK to send text and receive audio files without writing custom HTTP logic.
Install the official OpenAI Python library
Install the library using pip. This package handles the underlying HTTP requests and JSON parsing for you.
- Run
pip install openaiin your terminal or virtual environment.
Set base_url to our API endpoint
Configure the client to point to our infrastructure instead of OpenAI's servers. Use the base_url parameter to direct requests to https://api.innwa.info/v1.
- Ensure you pass your
tts-...key in theapi_keyparameter.
Use tts-1 or tts-1-hd models
Select either tts-1 or tts-1-hd as your model. Both models use the same engine and pricing structure, allowing you to switch based on your quality needs without changing your code logic.
Request Parameters
Configure your speech synthesis requests by defining the source text, selecting a voice preset that matches your editorial tone, and adjusting the playback speed to fit your broadcast schedule. Each parameter directly influences how the final audio file is rendered and delivered.
input: text up to 4096 characters
The input field accepts your raw text, which can include spaces and punctuation. Each request is limited to 4,096 characters. For longer articles, split the text into chunks and join the resulting audio files sequentially.
voice: choose from 8 presets
Select one of eight licensed voices from our presets. Each voice offers a distinct tone suitable for different types of news content, from neutral reporting to conversational interviews. All voices support any of the 23 supported languages.
- Atlas: Neutral, news delivery
- Milo: Friendly, conversational
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
speed: adjust from 0.25 to 4.0
Adjust the speed parameter to control the playback rate, ranging from 0.25 (slow) to 4.0 (fast). This allows you to compress audio for quick updates or slow it down for clarity. Default speed is 1.0.
Response Formats
The API returns audio as binary data. You must specify the desired format in the response_format field. The system supports mp3, wav, opus, flac, and pcm, allowing you to balance file size, quality, and compatibility based on your newsroom's workflow.
mp3: small file size, widely compatible
MP3 is the default choice for most news applications. It offers a good balance between audio quality and file size, making it ideal for quick delivery via CMS or broadcast workflows. This format ensures broad compatibility across web players and mobile apps without significant bandwidth overhead.
- Best for web delivery and mobile apps.
- Significantly smaller file sizes than WAV.
- Universal support across all modern browsers and players.
wav: high quality, larger files
WAV provides uncompressed, high-fidelity audio. Use this format when you need the highest possible quality for archival purposes or professional broadcast mastering. Be aware that WAV files are substantially larger than MP3s, which may impact storage and transfer speeds for long news segments.
- Ideal for archival and broadcast mastering.
- Uncompressed audio for maximum fidelity.
- Results in significantly larger file sizes.
opus: efficient streaming-ready format
Opus is an efficient codec. It offers high quality at low bitrates, making it suitable for real-time or low-latency news updates. This format is particularly useful if you are building custom audio players that require efficient data transmission over varying network conditions.
- High quality at low bitrates.

Handling Errors
When synthesizing audio, the API returns standard HTTP status codes to indicate success or failure. A 200 OK means your audio file is ready in the response body. Any other code signals an issue that requires attention, such as invalid input or server errors.
Check status codes for failures
Always inspect the HTTP status code from your API call. Codes outside the 200 range indicate specific problems, such as missing parameters or internal processing errors. Log these codes to quickly identify whether the issue lies in your request structure or a temporary service disruption.
Refunds for failed synthesis requests
If synthesis fails completely, you are not charged for that request. The API ensures that failed attempts do not deduct from your balance, providing a straightforward billing model where you only pay for successfully generated audio files.
- Failed requests receive a full refund of the character cost.
- Charges only apply to successful 200 OK responses.
Rate limit errors (429 responses)
You will receive a 429 status code if you exceed the allowed request rate. New keys are limited to 10 requests per minute until the first top-up. Once funded, the limit increases to 60 requests per minute. If you hit this cap, wait briefly before retrying.
- 10 requests/minute before top-up.
- 60 requests/minute after top-up.
- Requests queue under heavy load.
Rate Limits
Our API enforces strict rate limits to ensure stable performance for news teams processing editorial batches. Each API key is capped at 60 requests per minute, allowing you to generate audio clips efficiently without overwhelming the service. If your key becomes compromised, you can regenerate it immediately, though the old key stops working at once.
Before your first top-up, the limit is lower at 10 requests per minute. Once you add USDT, the limit increases to 60 requests per minute. These limits apply per key, so using multiple keys can help scale your workflow if needed.
60 requests per minute per key
Each API key allows up to 60 requests per minute. This limit applies to all endpoints, including voice and model queries. If you exceed this limit, you will receive a 429 status code, indicating that you need to wait before sending more requests.
- Limit is per API key, not per account.
- Applies to all endpoints, including /v1/voices and /v1/models.
- Exceeding the limit returns a 429 status code.
10 requests per minute before top-up
Before your first top-up, the rate limit is 10 requests per minute. This lower limit allows new users to test the API without overusing resources. Once you add USDT, the limit increases to 60 requests per minute.
This limit is designed to prevent abuse while allowing new users to get a feel for the service. It is a one-time limit, and once you top up, you will have access to the full 60 requests per minute.
Queuing behavior under load
Requests are processed one after another, so under load, a request may wait in a queue. This means that during high traffic, you might experience slight delays in audio generation. However, the typical speed is roughly real time on long texts, so most requests are processed quickly.
If you notice delays, consider splitting your text into smaller chunks or using multiple API keys to distribute the load. The API is designed to handle bursts of traffic, but it is important to be aware of the queuing behavior to avoid unexpected delays.
Voice Selection
Choosing the right voice ensures your audio aligns with the editorial tone. Our API offers eight presets, each designed for specific use cases within news workflows.
Atlas for neutral news delivery
Atlas provides a neutral, clear voice ideal for standard news readings. Its tone remains professional and unbiased, making it suitable for breaking news or factual reports.
Milo for conversational segments
Milo offers a friendly, conversational tone perfect for interviews or feature stories. It adds a human touch to editorial content without sounding overly formal.
Orion for documentary style
Orion delivers a deep, documentary-style voice for in-depth features. Its resonant tone suits long-form content, enhancing the narrative depth of your audio productions.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This variation keeps your audio feed dynamic and helps listeners distinguish between different types of content within your broadcast workflow.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- MDN: Web Speech API
- Creative Commons Attribution 4.0
- TRON developer hub: TRC-20
- LibriTTS-R paper (arXiv 2305.18802)
- W3C WAI: making audio and video accessible
- ISO 639 language codes
- LibriTTS-R corpus (OpenSLR 141)
- LibriVox public-domain audiobooks
- OpenAI API reference: create speech
- openai-node on GitHub
- Node.js documentation
