Comprehensive API Documentation for Text to Speech Synthesis

By Narrivo editorial team · Updated 2026-11-18

This documentation provides a complete reference for integrating Narrivo’s text-to-speech API into your startup’s applications. You will find the endpoint specifications, authentication details, and code examples needed to generate natural-sounding audio from text. The guide covers all available voices, supported languages, and audio formats, ensuring you can deliver clear voice notifications and interface audio to your users.

Designed for developers building SaaS products, this reference helps you add human-like voice capabilities without hiring voice actors. We use standard OpenAI-compatible endpoints, so you can integrate quickly using existing tools. Below, we detail the request structure, rate limits, and error handling to ensure a smooth development experience from the first API call to production deployment.

Comprehensive API Documentation for Text to Speech Synthesis

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playbd4.com/v1. You send POST requests to https://api.playbd4.com/v1/audio/speech for synthesis. Other endpoints like /v1/voices and /v1/models are also available at this base path for retrieving voice details and model information.

How do I generate an API key?

Sign up on the /get-api-key/ page using Google or email and password. Your account page displays your active API key, balance, and usage. You can issue a new key at any time, which immediately invalidates the previous one.

Can I use the official OpenAI SDK?

Yes. The request shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.playbd4.com/v1 and providing your Narrivo API key in the Authorization header.

What is the maximum character limit per request?

Each request supports up to 4096 characters in the input field. Spaces and punctuation count toward this limit. For longer texts, you must split the input into chunks of 4096 characters or fewer and join the resulting audio files.

How do I split long texts into audio?

Split your text into parts of up to 4096 characters. Send each part as a separate POST request to the speech endpoint. Then, programmatically join the returned audio files to create the final continuous audio output.

Does the API support streaming audio?

No. The API returns the complete audio file in the response. There is no streaming, WebSocket, or real-time partial audio support. You receive the full file once synthesis is complete, which may take a few seconds for short phrases.

What languages are available via the API?

We support 23 languages: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish. Any voice can speak any of these languages.

How do I specify a voice in the request?

Include the voice parameter in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. You can list all available voices by sending a GET request to /v1/voices.

Is SSML supported in the input text?

No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You provide plain text in the input field. The system guesses the language from the script if the language parameter is not set.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so excess requests may wait in a queue. Failed requests are free and do not consume your character balance.

Can I rotate my API key?

Yes. You can issue a new API key at any time from your account page. When a new key is issued, the old one stops working immediately, ensuring secure access management for your integration.

Do failed requests count against my limit?

No. If synthesis fails, the charge is returned in full. Failed requests do not consume your character balance or credits.

How do I set the response format?

Include the response_format field in your request body. Supported formats are mp3, wav, opus, flac, and pcm.

Is there a webhook for status updates?

No. There is no webhook for status updates or asynchronous notifications. The API is synchronous; you receive the audio file directly in the response body.

First request

curl

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

Sound wave illustration for: Authentication

Secure your API access with a Bearer token sent in the Authorization header. This single key authenticates all requests to the Narrivo endpoint, ensuring your usage is tracked against your account balance.

Bearer Token Usage

Bearer Token Usage

Include the header Authorization: Bearer tts-... with every POST request. The token is the only credential needed to distinguish your account from others in the shared API environment.

Key Management

Key Management

Each account maintains one active key. You can view your current key, balance, and character usage directly on the dashboard. The key is unique to this storefront and does not work elsewhere.

  • One active key per account
  • View key and usage on dashboard
  • Key is site-specific

Key Rotation

Issue a new key at any time via the dashboard. The old key stops working immediately, providing instant security without needing to wait for expiration periods or manual deactivation.

Speech Endpoint

Sound wave illustration for: Speech Endpoint

The core of Narrivo’s API is the speech endpoint, where you convert text into audio files. It accepts a POST request to the API base URL with a JSON body containing the text, voice selection, and audio format preferences.

POST /v1/audio/speech

Send your text payload here. The endpoint processes up to 4,096 characters per request. For longer texts, split the input into chunks and join the resulting audio files. Requests are processed sequentially, so under load, synthesis may queue.

Request Body Fields

Key parameters include model (tts-1 or tts-1-hd), voice (one of eight presets), and response_format (mp3, wav, opus, flac, pcm). You can also adjust speed between 0.25 and 4.0 or specify an ISO language code.

  • model: "tts-1" or "tts-1-hd"
  • voice: e.g., "aria", "nova", "atlas"
  • response_format: mp3, wav, opus, flac, pcm
  • speed: 0.25 to 4.0
  • input: text string (max 4096 chars)

Response Formats

Successful responses return the audio file directly in the requested format. If synthesis fails, the charge is returned in full, and an error code explains the issue. No extra metadata is included in the audio stream itself.

Voices Endpoint

Sound wave illustration for: Voices Endpoint

Retrieve available voices and metadata via a simple GET request. This endpoint provides the canonical list of eight presets, their supported languages, and pricing tiers, ensuring your app knows exactly which voice to select before synthesis begins.

GET /v1/voices

Call this endpoint to fetch the current voice catalog. The response includes each voice’s ID, gender, and the full list of supported ISO language codes. Use this data to populate your UI’s voice selector dynamically.

Voice Descriptions

Narrivo offers eight curated voices designed for clarity in startup interfaces. Female voices include Aria (warm narrator), Nova (bright), Luna (soft storytelling), and Sage (calm instruction). Male options feature Felix (energetic promo), Milo (friendly), Atlas (neutral news), and Orion (deep documentary). Every generated file carries an inaudible watermark that marks it as synthetic speech.

  • 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

Language Codes

Each voice can speak any of the 23 supported languages. If you omit the language field, the system guesses based on script, defaulting to English for Latin text. For non-English Latin scripts, explicitly set the ISO code to ensure accurate pronunciation.

  • Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

Models Endpoint

Sound wave illustration for: Models Endpoint

The /v1/models endpoint returns a list of available synthesis engines, currently listing "tts-1" and "tts-1-hd". Both models use the same engine and price.

GET /v1/models

A simple GET request to /v1/models returns a JSON object listing all supported model IDs.

tts-1 vs tts-1-hd

Both "tts-1" and "tts-1-hd" utilize the exact same engine and are priced identically at $10 per 1 million characters. The distinction lies solely in the model ID string used in your request body, allowing you to target specific versions if needed, though performance characteristics remain consistent across both identifiers.

Engine Details

Our engine processes requests sequentially, meaning under heavy load, synthesis may queue behind previous requests. For most startup use cases, such as app notifications or onboarding flows, the processing time aligns closely with real-time speech generation, roughly 25 characters per second for long texts.

  • Single engine for all model IDs
  • Real-time generation speed (~25 chars/sec)
  • Sequential processing under load
  • Identical pricing for tts-1 and tts-1-hd

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Narrivo’s API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI SDK clients with minimal configuration. By simply pointing the client to our base URL, you gain access to high-quality TTS without rewriting integration logic or learning a new library.

This approach leverages the robustness of the OpenAI SDK while utilizing our curated voices and pricing model. It is ideal for startup teams who want to drop voice features into their apps quickly using familiar tools.

Base URL Configuration

Set your SDK’s base URL to https://api.playbd4.com/v1. This redirects requests to our synthesis engine while maintaining standard request shapes.

Use your tts-... API key in the Authorization header. The key format is identical to standard Bearer tokens, ensuring seamless authentication.

  • Base URL: https://api.playbd4.com/v1
  • Auth Header: Authorization: Bearer tts-...

Standard SDK Methods

Use the standard speech method provided by the OpenAI SDK. Pass your text, selected voice, and desired audio format directly as parameters.

The SDK handles the JSON serialization and HTTP transport, returning the audio file directly in your application flow.

Code Examples

Here is a minimal Python example using the openai package to generate speech with the nova voice.

Replace YOUR_API_KEY with your key from the dashboard. The response contains the audio binary, ready for playback or storage.

```python import openai client = openai.OpenAI( base_url="https://api.playbd4.com/v1", api_key="YOUR_API_KEY" ) audio = client.audio.speech.create( model="tts-1", voice="nova", input="Hello, welcome to our app!" ) audio.stream_to_file("output.mp3") ```

OpenAI SDK Integration

Rate Limits

Sound wave illustration for: Rate Limits

Requests are processed sequentially, so synthesis time depends on queue depth. You can send up to 60 requests per minute per key, which is sufficient for most batch processing and real-time notification triggers.

Initial accounts start with a lower limit of 10 requests per minute. This increases to the standard 60 rpm after your first top-up, ensuring smoother performance as you scale your integration.

60 Requests Per Minute

The standard rate limit is 60 requests per minute. This allows for steady generation of audio assets without overwhelming the service. Requests are queued if the limit is exceeded, so longer texts may take additional time to complete.

  • Standard limit: 60 requests/minute
  • Queued processing during peaks
  • Per-key basis

Initial Limit

New accounts begin with a 10 requests per minute limit. This protects the infrastructure during the trial phase. The limit automatically upgrades to 60 rpm once you make your first top-up of at least $5.

  • Starts at 10 rpm
  • Upgrades after first top-up
  • Automatic adjustment

Burst Behavior

Bursts are handled by queuing rather than dropping requests. If you send many requests at once, they will process one after another. This ensures fair access but may increase total generation time for large batches.

  • Queued, not dropped
  • Sequential processing
  • Fair access guarantee

Audio Formats

Sound wave illustration for: Audio Formats

Choose the format that best fits your app’s performance needs. MP3 is a common choice for mobile and web notifications.

MP3 Support

Use MP3 for general delivery. It keeps bandwidth low while maintaining clear speech for user interfaces.

WAV Support

WAV provides uncompressed audio. Select this when you need maximum fidelity for local playback or debugging.

FLAC and OPUS

FLAC offers lossless compression for archival quality. OPUS provides efficient compression suitable for variable network conditions. Both are valid options via the response_format parameter.

Error Handling

Sound wave illustration for: Error Handling

Handling API errors requires attention to standard HTTP status codes and specific synthesis failures. Requests may fail due to invalid parameters, network issues, or internal processing errors, but failed synthesis attempts incur no charge.

Implementing exponential backoff for transient errors ensures reliable delivery without overwhelming the server. Always check the response body for detailed error messages to debug parameter issues quickly.

Common Error Codes

The API returns standard HTTP status codes to indicate success or failure. A 200 OK confirms audio generation, while 400 Bad Request indicates invalid input, such as an unsupported voice or format.

Use 401 Unauthorized if your Bearer token is missing or invalid, and 429 Too Many Requests when exceeding the rate limit. Review the error message in the response body to identify the exact cause.

  • 400: Invalid parameter (e.g., unknown voice ID)
  • 401: Invalid or expired API key
  • 429: Rate limit exceeded (60 requests/minute)
  • 500: Internal server error during synthesis

Retry Logic

For transient errors like 500 or 503, implement exponential backoff with jitter. Wait 1 second, then 2, 4, and 8 seconds before retrying, up to three attempts.

Failed requests are free, so retrying does not incur extra cost if the error is confirmed as a server-side issue. However, avoid rapid retries for 429 errors to prevent further throttling.

Character Limits

Each request supports up to 4096 characters. Exceeding this limit returns a 400 error. For longer texts, split the input into chunks, synthesize each part, and join the resulting audio files.

Spaces and punctuation count toward the character limit. Ensure your text preprocessing correctly handles Unicode characters to avoid unexpected limit breaches.

  • Max 4096 characters per request
  • Spaces and punctuation count as characters
  • Split longer texts into chunks for synthesis

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. You can generate thousands of unique notifications daily, ensuring your product feels dynamic and responsive to user needs.

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

More on this site