Python Integration Guide for the TTS API Integration

By NewsBrio editorial team · Updated 2026-11-19

This guide helps news product teams integrate the NewsBrio text-to-speech API using Python. You will learn how to generate audio from editorial text quickly, whether you are using standard HTTP requests or the OpenAI SDK. The documentation covers essential workflows, from obtaining your API key to handling responses and errors, ensuring you can turn articles into audio files without complex setup.

We focus on practical steps for building reliable audio pipelines. You will find clear examples for setting voices like Atlas for neutral news or Milo for conversational segments, adjusting speed, and managing rate limits. This resource is designed for developers who need straightforward, specific instructions to get their CMS or broadcast workflow generating audio efficiently.

Python Integration Guide for the TTS API Integration

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

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

Getting Your API Key

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

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

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

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

Sound wave illustration for: 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 openai in 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 the api_key parameter.

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

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

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

Handling Errors

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

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

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

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. MDN: Web Speech API
  3. Creative Commons Attribution 4.0
  4. TRON developer hub: TRC-20
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. W3C WAI: making audio and video accessible
  7. ISO 639 language codes
  8. LibriTTS-R corpus (OpenSLR 141)
  9. LibriVox public-domain audiobooks
  10. OpenAI API reference: create speech
  11. openai-node on GitHub
  12. Node.js documentation

More on this site