API Documentation for Text to Audio Reader Integration

By NewsAudio Reader editorial team · Updated 2026-11-18

This guide provides the technical specifications for integrating NewsAudio Reader’s text-to-speech API into newsroom workflows. It details the request schema, authentication requirements, and parameter constraints necessary for converting articles and transcripts into audio assets. The documentation assumes familiarity with standard RESTful APIs and JSON data structures, targeting product teams who require reliable, programmatic audio generation for accessibility compliance and multi-channel distribution.

Readers will find exact endpoint definitions, supported voice presets, and rate limit thresholds. The guide includes ready-to-use code examples in cURL, Python, and JavaScript, demonstrating how to adjust the base URL for compatibility with the OpenAI SDK. All technical details are derived directly from the API’s current behavior, ensuring accurate implementation for high-volume news production environments.

API Documentation for Text to Audio Reader Integration

Frequently asked questions

What is the API endpoint for speech generation?

Send a POST request to https://api.playmomoo.com/v1/audio/speech with a JSON body containing your text and configuration parameters. This endpoint accepts standard TTS inputs and returns the generated audio file directly in the response, allowing seamless integration into your newsroom’s audio pipeline.

How do I authenticate with the API?

Include an Authorization header with the value Bearer followed by your unique API key (e.g., Bearer tts-...). Each account holds one active key; issuing a new key immediately invalidates the previous one, ensuring secure access to your synthesis credits and usage data.

Which models are available for synthesis?

The API offers two models: tts-1 and tts-1-hd. Both utilize the same underlying engine and incur identical pricing. You may select either model based on your quality preferences without any difference in cost or performance characteristics, as they share the same voice presets and capabilities.

What is the maximum input text length?

Each request supports a maximum of 4096 characters for the input field. For longer articles or transcripts, split the text into chunks of this size and join the resulting audio files. Spaces and punctuation count toward the character limit, so plan your batching strategy accordingly.

How do I set the language for synthesis?

Pass an optional ISO language code in the request body. If omitted, the system guesses the language, defaulting to English for Latin-script text. For non-English Latin text, explicitly set the language parameter to ensure accurate pronunciation, as the API supports 23 specific languages.

Does the API support OpenAI SDKs?

Yes, the API follows the same request shape as the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playmomoo.com/v1 and providing your site-specific API key, enabling quick integration for existing OpenAI-compatible codebases.

What happens if the rate limit is exceeded?

The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so exceeding the limit or high load may cause your request to wait in a queue. Ensure your implementation handles potential delays gracefully.

How are errors reported in the response?

Standard HTTP error codes indicate issues, such as authentication failures or invalid parameters. The response body includes details about the error. Failed synthesis requests do not incur charges, and any deducted credits are returned automatically if the synthesis process fails before completion.

Are failed requests refunded automatically?

Yes, if synthesis fails, the charge is returned in full. You do not need to submit a support ticket for refunds. This ensures that you only pay for successfully generated audio files, protecting your budget during integration testing or unexpected service interruptions.

Which audio formats can be requested?

You can request audio in mp3, wav, opus, flac, or pcm formats by setting the response_format field. Choose the format that best suits your distribution needs.

How do I generate a new API key?

Log in to your account dashboard at /get-api-key/ and issue a new key. The new key becomes active immediately, and the previous key stops working at once. This allows you to rotate keys securely without downtime, ensuring continuous access to the API.

What is the default voice if none is specified?

The API requires a voice parameter. You must specify one of the eight available presets: aria, nova, luna, sage, felix, milo, atlas, or orion.

Can I adjust the speed of the audio output?

Yes, use the speed parameter to adjust playback speed between 0.25 and 4.0.

How long does a typical request take?

Typical speed is roughly real time, generating about 25 characters of text per second of audio. Short phrases may take a few seconds, while longer texts process proportionally. Under load, requests may queue, so expect variable latency depending on current system usage.

First request

curl

curl https://api.playmomoo.com/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.playmomoo.com/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.playmomoo.com/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 and Keys

Sound wave illustration for: Authentication and Keys

Access to the NewsAudio Reader API requires a valid Bearer token included in the request header. This token authenticates your account and tracks usage against your current balance and rate limits.

Bearer token format

Include the header Authorization: Bearer tts-<your_key> in every API call. The key format is tts- followed by alphanumeric characters.

Key generation process

Keys are issued upon account creation via Google sign-in or email registration on the /get-api-key/ page. Each account maintains one active key at a time.

Key rotation policy

Issue a new key at any time via the dashboard. The previous key becomes invalid immediately upon generation of the new one, ensuring secure access control.

Endpoint Structure

Sound wave illustration for: Endpoint Structure

The API exposes three primary endpoints for integration. The speech synthesis endpoint accepts POST requests to convert text into audio files. The voices listing endpoint provides metadata on available presets, while the model information endpoint details engine specifications.

Speech synthesis endpoint

Send text to POST /v1/audio/speech to receive an audio file. The endpoint processes input up to 4096 characters per request. For longer texts, split the input and join the resulting audio files sequentially.

Voices listing endpoint

Use GET /v1/voices to retrieve available voice presets, supported languages, and formats. This endpoint confirms which of the eight voices (e.g., aria, atlas) are active and compatible with your selected language code.

  • Lists 8 voice presets with metadata
  • Shows supported ISO language codes
  • Returns available response formats

Model information endpoint

Call GET /v1/models to verify the available engine models. The API supports tts-1 and tts-1-hd, which use the same engine and pricing structure.

Endpoint Structure

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts two model variants, both using the same synthesis engine with identical pricing. Select "tts-1" for standard generation or "tts-1-hd" for higher fidelity. The input field carries the article text, limited to 4096 characters per request. Longer articles must be split programmatically and concatenated client-side.

Specify the voice from the eight presets and optionally the language via ISO code. If language is omitted, the system guesses the language from the script, defaulting to English for Latin text. Ensure the language parameter is set explicitly for non-English Latin-script content to avoid misidentification.

Model selection (tts-1, tts-1-hd)

Both models use the same engine and price. Choose tts-1 for standard output or tts-1-hd for enhanced quality. The model field accepts either string value in the JSON body.

Input text length limits

Each request supports up to 4096 characters, including spaces and punctuation. For longer articles, split the text into chunks and join the resulting audio files. Processing is sequential, so long texts may experience queue delays during peak load.

  • Maximum 4096 characters per request
  • Include spaces and punctuation in count
  • Split and join for longer articles

Voice and language selection

Select one of eight voices (e.g., aria, nova, atlas). The language field accepts optional ISO codes. If omitted, the system guesses the language from the script, defaulting to English for Latin text.

Explicitly set language for non-English Latin-script text to ensure accurate synthesis. All eight voices support all 23 listed languages.

  • Eight voice presets available
  • Language defaults to English for Latin script if unset
  • Explicit language setting recommended for non-English

Supported Formats

Sound wave illustration for: Supported Formats

NewsAudio Reader provides five audio output formats to meet diverse distribution needs. Select mp3, wav, opus, or flac via the response_format parameter. Each format serves specific archival or streaming requirements without altering the underlying synthesis engine.

MP3 compression standard

MP3 is one of the available formats, offering efficient compression for broad compatibility. This format is suitable for most standard news clips and audio articles.

WAV lossless output

WAV provides uncompressed audio data. It is ideal for professional editing workflows where file integrity is critical. Use this format when distributing master files to broadcast teams or for high-fidelity accessibility archives.

Opus and FLAC options

Opus offers high-quality compression at low bitrates, suitable for bandwidth-constrained environments. FLAC provides lossless compression. Choose FLAC for long-form content where storage efficiency matters but quality must remain pristine.

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

Rate limits are enforced per API key to ensure stable synthesis. The standard allowance is 60 requests per minute for active accounts. This limit applies to all speech synthesis endpoints and helps maintain consistent service quality during high-volume newsroom workflows.

Requests per minute limit

Each active key allows up to 60 requests per minute. This capacity supports bulk article processing without overwhelming the synthesis engine. Exceeding this limit results in standard HTTP 429 responses until the window resets.

  • Standard limit: 60 requests/minute per key.
  • Applies to all synthesis endpoints.

Pre-top-up restrictions

Accounts without a top-up are restricted to 10 requests per minute. This lower threshold prevents resource exhaustion while users manage their USDT transfers. Limits increase automatically once the transfer is confirmed.

  • Pre-top-up limit: 10 requests/minute.
  • Automatic increase upon USDT confirmation.

Queue behavior under load

Requests are processed sequentially. Under heavy load, synthesis may wait in a queue. Typical generation speed is roughly real-time, but short phrases may take a few seconds. Patience ensures consistent audio quality without additional costs.

  • Sequential processing order.
Rate Limits and Throttling

Error Handling

Sound wave illustration for: Error Handling

When synthesis fails, the request is free. The API returns a standard HTTP error code, and the character count is not deducted from your balance. This ensures you are not charged for unsuccessful audio generation.

Understanding error responses helps you debug integration issues quickly. The system provides clear feedback on invalid inputs or temporary service limitations.

Standard HTTP error codes

The API returns standard HTTP status codes to indicate the result of your request. A 200 OK response confirms successful audio generation. Non-200 codes, such as 400 Bad Request or 500 Internal Server Error, indicate specific issues with the request or service status.

Refer to the response body for detailed error messages that explain the cause of the failure.

  • 400: Invalid parameters or malformed JSON body.
  • 401: Unauthorized due to an invalid or missing API key.
  • 429: Too Many Requests if the rate limit is exceeded.
  • 500: Internal server error during synthesis.

Failure refund mechanism

If the synthesis process fails, the charge for the characters is returned in full. You are only billed for successfully generated audio files. This applies to all request types, including high-definition models.

Check your account dashboard to verify that failed requests did not deduct from your balance. The refund is automatic and immediate.

Input validation rules

The input text must not exceed 4096 characters. Texts longer than this limit should be split into multiple requests and the audio files joined. Spaces and punctuation count towards the character limit.

Ensure the voice parameter matches one of the eight available presets. The language parameter is optional but recommended for non-English Latin-script text to avoid incorrect language guessing.

SDK Compatibility

Sound wave illustration for: SDK Compatibility

The API is compatible with the official OpenAI SDK because it uses the same request shape and authentication method. This allows you to reuse existing client libraries without writing custom HTTP parsers, reducing integration time for your newsroom’s engineering team.

You can direct the SDK to our infrastructure by simply changing the base URL. No new library installation is required, and the standard JSON payload structure remains identical to the OpenAI specification.

OpenAI SDK integration

Use the official OpenAI Python or JavaScript SDKs. Pass your API key as a Bearer token in the Authorization header. The library handles serialization and retries automatically.

This approach works for both tts-1 and tts-1-hd models. You do not need to modify the library’s core logic, only the endpoint configuration.

  • Official OpenAI SDKs supported
  • Standard Bearer token auth
  • No custom library required

Base URL modification

Set the base_url parameter to https://api.playmomoo.com/v1. This redirects all requests to our synthesis engine while maintaining the familiar SDK interface. Ensure your API key is valid and active before switching endpoints.

This single change allows you to switch between providers or test our service without altering your codebase’s structure. The SDK continues to handle retries and error parsing as expected.

  • Base URL: https://api.playmomoo.com/v1
  • One-line configuration change
  • Maintains standard SDK behavior

JSON body structure

The request body must include model, input, voice, and response_format. These fields map directly to the OpenAI speech endpoint structure. You can optionally specify speed and language to control audio properties.

Example structure: `{"model": "tts-1", "input": "Article text", "voice": "nova", "response_format": "mp3"}`. The API validates the input length (max 4096 characters) and returns the audio file in the response body.

  • Standard JSON payload
  • Supports speed and language params
  • Max 4096 chars per request
SDK Compatibility

Code Examples

Sound wave illustration for: Code Examples

Provide concrete integration examples for NewsAudio Reader using standard tools. These snippets demonstrate the exact JSON structure and authentication headers required for production workflows.

Each example targets the core synthesis endpoint, ensuring newsroom engineers can quickly verify connectivity and audio generation before full deployment.

cURL command example

Use this command to test voice synthesis directly from the terminal. Replace YOUR_API_KEY with your bearer token from the dashboard.

  • curl -X POST https://api.playmomoo.com/v1/audio/speech \\n -H "Authorization: Bearer YOUR_API_KEY" \\n -H "Content-Type: application/json" \\n -d '{"model": "tts-1", "input": "Breaking news update", "voice": "atlas", "response_format": "mp3"}'

Python SDK snippet

Leverage the official OpenAI SDK by adjusting the base URL. This approach requires minimal code changes for existing Python news automation scripts.

  • import openai client = openai.OpenAI(base_url="https://api.playmomoo.com/v1", api_key="YOUR_API_KEY") response = client.audio.speech.create(model="tts-1", voice="atlas", input="Daily briefing ready.", response_format="mp3")

JavaScript fetch example

Implement direct HTTP requests using the native fetch API. This method is suitable for browser-based audio players or Node.js backend services.

  • fetch('https://api.playmomoo.com/v1/audio/speech', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'tts-1', voice: 'nova', input: 'Market update.' }) })

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. News outlets will amplify your launch, turning product updates into public conversation for your entire audience.

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. Python documentation
  3. Tether (USDT)
  4. ISO 639 language codes
  5. IETF RFC 7845: Ogg Opus
  6. LibriTTS-R corpus (OpenSLR 141)
  7. OpenAI API reference: create speech
  8. curl documentation
  9. openai-node on GitHub
  10. openai-python on GitHub
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. TRON developer hub: TRC-20

More on this site