Developer Guide: Cloud TTS API Integration

By News Audio Logic editorial team · Updated 2026-11-19

This guide provides everything product teams at news outlets need to integrate our cloud text-to-speech API into their audio journalism workflows. You will find concrete examples for generating audio from text, managing voices, and handling errors with clear, studio-quality results. We focus on reliability and scalability, ensuring your team can deliver consistent narration beyond the browser's native SpeechSynthesis API.

We cover the essential endpoints, including model selection and supported formats, so you can choose the right balance of quality and bandwidth. The documentation assumes you are using the official OpenAI SDKs or plain HTTP, with straightforward setup steps to get your API key and make your first request. Everything you need to start generating audio for your news platform is here.

Developer Guide: Cloud TTS API Integration

Frequently asked questions

How do I set the base_url for the OpenAI SDK?

Set the base_url to https://api.vm1974.net/v1. This allows you to use the official OpenAI SDKs by simply changing the endpoint while keeping the same request shape and authentication method with your Bearer token key.

What is the maximum input length?

Each request supports up to 4096 characters of input text. If your content exceeds this limit, you must split the text into smaller parts, generate audio for each segment, and join the resulting audio files.

Can I stream audio in real-time?

No. The API does not support streaming, WebSockets, or real-time partial audio. You receive the complete audio file in the response after the synthesis process finishes. Requests are processed sequentially, so longer texts may take time.

Does the API support SSML?

No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You provide plain text input, and the system handles pronunciation based on the specified voice and language parameters without additional markup.

How do I specify a different voice?

Include the voice field in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone suitable for different types of news content.

What is the speed range for speech?

You can adjust the speech speed using the speed parameter, which accepts values between 0.25 and 4.0. This allows you to control the pacing of the generated audio to fit your specific editorial needs.

Can I mix multiple voices in one request?

No. Each request generates audio using a single voice preset. To use multiple voices, you must make separate requests for each segment and then join the resulting audio files together in your post-processing pipeline.

How do I handle large texts?

Split your text into chunks of up to 4096 characters. Send each chunk as a separate request to the API, then join the returned audio files. This ensures compatibility with the single-voice-per-request limitation.

Is the API key case-sensitive?

Yes. Your API key is a specific string starting with tts-. Ensure you copy it exactly, including case, when setting the Authorization: Bearer header. Incorrect casing will result in authentication errors.

What happens if I exceed the rate limit?

You are limited to 60 requests per minute per key (10 before the first top-up). Exceeding this limit may result in delayed processing or errors. Requests are processed sequentially, so high volume can cause queuing delays.

Can I use the same key for multiple apps?

Yes. One active key per account can be used across multiple applications or services. However, all usage counts against the same rate limit and character balance, so monitor your consumption across all integrations.

How do I renew my API key?

You can issue a new key at any time via your account dashboard. When you generate a new key, the old one stops working immediately. This allows you to rotate keys for security without downtime.

Is there a webhook for completion?

No. There is no webhook for completion. The API returns the audio file directly in the response. You must poll or wait for the synchronous response to receive your generated audio content.

Can I download the audio directly?

Yes. The API returns the generated audio file directly in the response body. You can save this file to your local storage or upload it to your CDN. Supported formats include mp3, wav, opus, flac, and pcm.

First request

curl

curl https://api.vm1974.net/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.vm1974.net/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.vm1974.net/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

Get Your API Key

Sound wave illustration for: Get Your API Key

Access the /get-api-key/ page to create your account using Google or an email and password combination. This is the entry point for generating the credentials required to authenticate your API requests against the News Audio Logic infrastructure.

Sign up on the site

Sign up on the site

Registration is immediate. Google sign-ups receive a $0.50 trial credit valid for 7 days, while email-based accounts start with zero balance. Once registered, you can proceed to generate your first API key directly from the dashboard.

Copy your Bearer token

Copy your Bearer token

Your unique key appears on the dashboard alongside your current balance and usage statistics. Copy this string to use in the Authorization: Bearer header of your HTTP requests. Ensure no extra whitespace is included when pasting into your code configuration.

One key per account

The system supports exactly one active key per account for simplicity. If you need to rotate credentials, issuing a new key immediately invalidates the previous one.

First Request with cURL

Sound wave illustration for: First Request with cURL

The API accepts standard JSON payloads via POST requests. You send text, select a voice model, and receive synthesized audio after processing. This straightforward structure fits easily into existing newsroom workflows.

Below is a minimal example using cURL. It demonstrates the required fields and how to handle the binary audio response efficiently in production environments.

Basic JSON body structure

Each request must include the text to be spoken, the target voice, and the model version. The API handles character counting and returns a direct audio file, eliminating the need for intermediate storage steps.

  • POST https://api.vm1974.net/v1/audio/speech
  • Content-Type: application/json

Required fields: model, input, voice

The model field accepts tts-1 or tts-1-hd. The input field takes your news script, up to 4096 characters. The voice field selects from eight presets like aria or atlas. You can also optionally set a language code.

  • model: "tts-1" or "tts-1-hd"
  • input: "Breaking news update..."
  • voice: "atlas"

Response with audio file

A successful request returns the audio file directly in the response body. The format matches your response_format choice, such as mp3 or wav. Failed synthesis returns a JSON error object and charges nothing.

  • Returns binary audio data
  • Standard HTTP 200 on success
  • Error JSON on failure

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

Integrate News Audio Logic into your newsroom’s audio pipeline using the official OpenAI SDKs. Since our API mirrors the standard request shape, you can repurpose existing code by simply updating the configuration endpoint.

Modify the base URL in your SDK client to point to our infrastructure. This allows you to generate narration for articles using familiar methods without rewriting your integration logic.

Change the base_url

Update the client’s base URL to https://api.vm1974.net/v1. This directs all synthesis requests to our cloud infrastructure while maintaining the standard JSON body structure expected by OpenAI-compatible libraries.

Use official OpenAI SDKs

Leverage the official OpenAI SDKs for your preferred language. Pass your tts-... Bearer token in the authorization header and call the audio.speech endpoint just as you would for OpenAI’s service.

Point to api.vm1974.net

Ensure your configuration explicitly targets api.vm1974.net to access the News Audio Logic engine.

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

The API supports five standard audio formats: mp3, wav, opus, flac, and pcm. These options allow news product teams to balance file size and quality based on their specific delivery infrastructure and playback requirements.

Selecting the right format depends on your bandwidth constraints and archival needs. MP3 and Opus offer efficient compression for web delivery, while WAV and FLAC provide lossless quality for master files. PCM is available for raw audio processing.

Each format serves a distinct purpose in the audio journalism workflow. Use compressed formats for rapid web publishing and lossless options for high-fidelity storage. The choice does not affect voice synthesis quality, only the final file structure.

mp3, wav, opus, flac, pcm

All five formats are generated with the same engine quality. You can switch formats without re-synthesizing the text, as the API handles the encoding in the response.

The choice is made via the response_format field in your JSON request. It accepts lowercase string values corresponding to each codec.

  • mp3: Standard lossy compression, ideal for web players.
  • wav: Uncompressed PCM, suitable for editing workflows.
  • opus: High-efficiency compression, suitable for mobile data.
  • flac: Lossless compression, preserves audio integrity.
  • pcm: Raw 16-bit linear audio data.

Choose based on bandwidth

News outlets often publish to mobile apps where data usage matters. Opus and MP3 significantly reduce bandwidth costs compared to uncompressed WAV files.

For internal editing or archival, FLAC or WAV ensures no generation artifacts are lost during compression.

  • Prioritize Opus for high-traffic mobile delivery.
  • Use MP3 for broad browser compatibility.
  • Select WAV for post-production editing.
  • Choose FLAC for long-term archival storage.

Standard compression options

The API applies standard encoding for each format. No additional parameters are required for basic usage.

File sizes vary by length and format. A minute of audio in MP3 is significantly smaller than in WAV.

All formats support the full speed range of 0.25–4.0, ensuring consistent audio integrity regardless of the chosen compression level.

Model Selection

Sound wave illustration for: Model Selection

The API offers two model variants, tts-1 and tts-1-hd, both powered by the same underlying engine. This means audio quality differences are minimal, but both are optimized for natural speech synthesis suitable for news broadcasting and long-form audio journalism.

tts-1 standard engine

Use tts-1 for efficient, real-time generation. It is ideal for high-volume news updates, processing roughly 25 characters per second.

tts-1-hd high definition

The tts-1-hd model provides enhanced clarity for complex scripts. It uses the same engine as tts-1, so there is no technical quality difference, and it costs the same, making it a flexible choice for detailed features.

Same price for both

Both models cost $10 per 1 million characters. You can switch between tts-1 and tts-1-hd in your request body without changing your budget or pricing tier. Use the HD version for critical segments without penalty.

Model Selection

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

Each API key is limited to 60 requests per minute once your account is active. This limit applies to all endpoints and ensures fair usage across the network. You can monitor your current usage and remaining quota directly from the dashboard.

60 requests per minute per key

Once your account is active, you can send up to 60 requests per minute.

10 per minute before first top-up

New accounts start with a lower limit of 10 requests per minute. This allows you to test the integration before adding funds. The limit increases to 60 RPM after your first top-up.

Queue processing under load

Requests are processed sequentially. During high traffic, your request may wait in a queue. Longer texts take roughly real-time to generate, so plan your batch jobs accordingly to avoid delays.

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate request outcomes. A 200 OK response contains the audio file, while error codes like 429 or 500 indicate issues. Failed synthesis requests are free, ensuring you are not charged for audio that was not delivered.

Refund on error

If synthesis fails, the charge is returned in full. This applies to any request where the audio file is not successfully generated. You only pay for completed audio files.

Standard HTTP status codes

The API uses standard HTTP status codes to communicate request status. A 200 OK response includes the audio file in the body. Other codes, such as 429 for rate limits or 500 for server errors, indicate specific issues.

  • 200 OK: Audio file returned in response body
  • 400 Bad Request: Invalid parameters or missing fields
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Temporary processing failure

Failed requests are free

Failed requests are free. If synthesis fails, the charge is returned in full. This ensures you are only billed for successfully generated audio files. Check the HTTP status code to confirm if your request was successful.

Voices and Languages

Sound wave illustration for: Voices and Languages

News Audio Logic provides eight distinct voice presets, including female options like Aria and Luna, and male voices such as Felix and Atlas. Each voice is engineered for clarity and consistency, ensuring reliable delivery for audio journalism workflows.

The API supports 23 languages, allowing any voice to speak any supported language. This flexibility enables news teams to produce multilingual content without managing multiple voice models or providers.

List available voices

We offer eight presets based on licensed recordings. Female voices include Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (instructional). Male voices include Felix (energetic), Milo (conversational), Atlas (neutral news), and Orion (documentary).

  • 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

Set language explicitly

Include the language field with an ISO code in your request. While the system guesses language from the script, explicit setting ensures accuracy for non-English Latin text. Supported languages include Arabic, Chinese, English, French, German, Japanese, Spanish, and others.

Default language detection

If the language field is omitted, the API infers the language from the input text. Latin script text defaults to English. For accurate results with other languages using Latin characters, always specify the language parameter.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. If synthesis fails, the request is free, so you do not need to manage complex retry logic for billing issues.

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. openai-python on GitHub
  3. W3C WAI: making audio and video accessible
  4. curl documentation
  5. Node.js documentation
  6. MDN: Web Speech API
  7. TRON developer hub: TRC-20
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. FFmpeg documentation
  10. LibriTTS-R corpus (OpenSLR 141)
  11. Creative Commons Attribution 4.0
  12. Tether (USDT)

More on this site