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.mp3Python (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 | |
|---|---|
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 |
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
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
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
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
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
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
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") ```

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
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
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.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriVox public-domain audiobooks
- MDN: Web Speech API
- Creative Commons Attribution 4.0
- W3C WAI: making audio and video accessible
- LibriTTS-R corpus (OpenSLR 141)
- openai-python on GitHub
- Python documentation
- openai-node on GitHub
- Node.js documentation
- OpenAI API reference: create speech
- LibriTTS-R paper (arXiv 2305.18802)
