API Documentation for Voice Notifications

By VerbaClear editorial team · Updated 2026-11-18

This documentation provides the technical reference for integrating VerbaClear’s text-to-speech API into your fintech notification systems. You will find concrete code examples, parameter definitions, and integration guides for delivering clear, human-sounding voice alerts to your users via a reliable cloud API.

The guide is designed for product engineers building high-volume notification pipelines. It covers authentication, OpenAI SDK compatibility, rate limits, and error handling, ensuring you can implement compliant voice outputs with predictable costs and straightforward logic.

API Documentation for Voice Notifications

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or an email and password. Accounts are specific to this site. Once registered, your dashboard displays your active API key, current balance, and usage statistics immediately, allowing you to start making requests without waiting for approval.

Does the API support 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.playa71.com/v1 and providing your VerbaClear key. This allows seamless integration into existing codebases that already utilize OpenAI’s TTS infrastructure.

What is the base URL?

The API base URL is https://api.playa71.com/v1. All requests, including speech synthesis and voice listing, originate from this domain. Ensure your SDK configuration points to this address to route requests correctly to VerbaClear’s infrastructure instead of OpenAI’s servers.

How do I handle errors?

Failed requests are free, and the charge is returned in full if synthesis fails. You should implement standard HTTP error handling in your application. Check the response status code to determine if the request succeeded or if an issue occurred during processing.

What is the rate limit?

The limit is 60 requests per minute per key. Before your first top-up, this limit is reduced to 10 requests per minute. If you exceed this limit, requests may queue or fail. Monitor your usage via the dashboard to stay within these bounds.

Can I change my API key?

Yes, you can issue a new key at any time from your account dashboard. When a new key is generated, the old one stops working immediately. This ensures security and allows you to rotate credentials without downtime if you suspect a leak.

What formats are supported?

We support mp3, wav, opus, flac, and pcm formats. You specify the desired output format using the response_format field in your request body. This flexibility allows you to choose the best balance between file size and quality for your specific fintech notification use case.

How do I split long texts?

Each request accepts up to 4096 characters. For longer texts, split your input into parts of this size, generate audio for each part, and join the resulting audio files. This ensures you stay within character limits while delivering complete audio notifications to your users.

Is SSML supported?

No, the API does not support SSML. It accepts plain text input. If you need specific pronunciation or pacing, you must manage that within the text itself or post-process the audio. We do not offer phoneme dictionaries or custom pronunciation lexicons either.

Can I stream audio?

No, we do not support streaming, WebSocket, or real-time partial audio. The API returns the complete audio file upon request completion. Requests are processed sequentially, so under load, you may experience delays before the full file is available for download or playback.

How do I set the language?

Pass an optional ISO language code in the request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always explicitly set the language to ensure accurate synthesis and voice selection.

What is the speed range?

The speed parameter accepts values between 0.25 and 4.0. This allows you to adjust the playback speed of the generated speech to fit your notification style. Faster speeds are useful for quick alerts, while slower speeds may improve clarity for complex information.

Do I need a library?

No, you can use plain HTTP requests or the official OpenAI SDK. No proprietary library is required. Using the OpenAI SDK is recommended for ease of use, but standard HTTP clients work perfectly fine as long as you format the JSON body correctly.

How do I authenticate?

Include your API key in the Authorization header as a Bearer token. The format is: Authorization: Bearer tts-... . Ensure you use the correct key associated with your account. Each account has one active key at a time, which you can rotate via the dashboard.

First request

curl

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

Getting Your API Key

Sound wave illustration for: Getting Your API Key

Start by visiting /get-api-key/ and signing up with Google. This instant method grants a $0.50 free trial (50,000 characters) valid for seven days, allowing you to test voice alerts immediately without payment details.

Alternatively, create an account using an email and password. This method provides immediate access to the dashboard but does not include trial credit, requiring a top-up before the first synthesis.

Sign up via Google

Sign up via Google

Click the Google sign-in button on the registration page. Upon verification, your account is created instantly with a $0.50 credit. This trial allows you to generate approximately 50,000 characters over seven days, perfect for testing integration with your fintech notification system.

  • Instant account creation
  • $0.50 trial credit included
  • 7-day validity period
  • No credit card required

Email password sign-up

Email password sign-up

Enter your email address and create a secure password to register. This standard method creates an active account immediately but starts without any trial credit. You must top up via USDT (TRC-20) to begin generating voice alerts.

  • Standard email registration
  • No trial credit included
  • Immediate dashboard access

Key management

Your API key is visible on the /get-api-key/ dashboard alongside your current balance and usage statistics. The key format is tts-... and is used in the Authorization: Bearer header for all requests.

  • One active key per account
  • Revoke old keys instantly
  • Issue new key anytime
  • Key displayed on dashboard

Quickstart with cURL

Sound wave illustration for: Quickstart with cURL

Get started instantly using standard HTTP requests. Send a POST to the speech endpoint with your API key and desired parameters to receive synthesized audio directly in your fintech notification pipeline.

This quickstart demonstrates the minimal setup required to generate voice alerts for balance updates or transaction confirmations using the VerbaClear TTS engine.

First POST request

Send your first request using the following cURL command. Replace YOUR_API_KEY with your key from the dashboard.

```bash curl -X POST "https://api.playa71.com/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Your transaction is confirmed.", "voice": "nova"}' ```

JSON body structure

The request body is standard JSON. The input field accepts up to 4,096 characters. Specify the voice preset, such as nova for bright alerts or atlas for neutral news-style updates. The model can be tts-1 or tts-1-hd.

Optional fields include speed (0.25–4.0) and language (ISO code). If omitted, language is guessed from the script.

Response handling

On success, the API returns the audio file directly in the response body with the specified response_format. Save this binary data to your application’s storage or stream it to users. Failed requests return a JSON error object and incur no charge.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

VerbaClear’s API mirrors the OpenAI speech endpoint structure, allowing fintech developers to integrate voice alerts using familiar OpenAI SDKs. By simply adjusting the base_url to https://api.playa71.com/v1, your existing code connects directly to our TTS engine without requiring a complete rewrite.

This compatibility ensures you can leverage standard authentication and request patterns while accessing our specific voice presets and cost-efficient pricing. It simplifies the transition for teams already comfortable with OpenAI’s ecosystem, reducing integration friction for high-volume notification systems.

Base URL configuration

Update your SDK’s base URL to https://api.playa71.com/v1. Use your tts-... bearer token in the Authorization header. This single change redirects all requests to VerbaClear’s infrastructure.

Ensure your key starts with tts- to match our authentication format. The SDK handles the rest, maintaining standard request shapes.

SDK compatibility

Any OpenAI SDK compatible with the speech endpoint works seamlessly. No custom VerbaClear SDK is required, keeping your dependencies light.

Standard headers and JSON bodies are accepted. Our endpoint processes requests identically to the OpenAI model, ensuring predictable behavior.

Code examples

  • Set base_url to https://api.playa71.com/v1
  • Pass model as 'tts-1' or 'tts-1-hd'
  • Use voice parameter with preset names like 'aria' or 'nova'
  • Include Authorization: Bearer tts-your-key-here

Request Parameters

Sound wave illustration for: Request Parameters

Configure the core synthesis behavior using the model, voice, and speed parameters in your JSON body. These fields determine the audio engine, the persona of the voice, and the playback rate for fintech alerts.

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

Both tts-1 and tts-1-hd use the same engine and price. Choose based on your quality needs without worrying about cost differences.

Voice presets

Select from eight licensed presets like nova for upbeat updates or atlas for neutral news. Each voice supports all 23 languages, ensuring consistent tone across global markets.

  • 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

Speed control

Adjust speed between 0.25 and 4.0 to fit your notification style. Faster speeds help convey urgency, while slower rates improve clarity for complex account details.

Response Formats

Sound wave illustration for: Response Formats

VerbaClear supports five audio formats to suit different notification pipelines. Choose MP3 for efficient bandwidth usage or WAV for high-fidelity playback in banking apps. Each format ensures clear, human-sounding alerts without compromising quality.

MP3 output

MP3 is the default and most efficient format for mobile notifications. It balances file size and audio quality, ensuring fast delivery to users' devices while maintaining clarity for voice alerts.

  • Default format for most integrations
  • Optimal for mobile data efficiency
  • High compatibility across all devices

WAV output

WAV provides uncompressed, lossless audio ideal for high-quality playback systems. Use this format when audio fidelity is critical, such as in premium banking interfaces or accessibility features requiring clear sound.

  • Uncompressed, lossless audio
  • Ideal for high-fidelity playback
  • Best for accessibility features

Opus, FLAC, PCM

Opus offers efficient compression, while FLAC provides lossless quality. PCM delivers raw, uncompressed audio for direct processing.

  • Opus: efficient streaming compression
  • FLAC: lossless, smaller than WAV
  • PCM: raw, uncompressed audio data
Response Formats

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

VerbaClear enforces a rate limit of 60 requests per minute per API key. This ensures fair usage for fintech notification pipelines generating high-volume voice alerts. The limit applies globally to your active key, so plan your burst traffic accordingly.

60 requests per minute

Once your account is funded, you can send up to 60 synthesis requests every minute. This throughput supports real-time user notifications without significant delays for standard message lengths.

Initial limit before top-up

New accounts or those with zero balance start with a reduced limit of 10 requests per minute. This allows you to test the integration quickly. Your limit automatically upgrades to 60 requests per minute once you top up your balance with USDT.

Queue behavior

Requests are processed sequentially. If you exceed the limit, subsequent requests may wait in a queue rather than failing immediately. Short phrases generate in seconds, while longer texts take longer due to the real-time generation speed. Be mindful of this when triggering simultaneous alerts for multiple users.

  • Sequential processing ensures consistent audio generation order.
  • Queued requests are not charged until processing begins.

Error Handling

Sound wave illustration for: Error Handling

When voice notifications fail to generate, the API returns specific error codes to help you adjust your integration quickly. Common issues include invalid voice names, exceeding the 4096-character input limit, or temporary rate limits during high-volume bursts.

Common error codes

The API returns standard HTTP status codes. A 400 error typically indicates invalid parameters or an empty input field. A 429 error signals that you have exceeded the 60 requests-per-minute limit. Ensure your client respects these headers and adjusts retry logic accordingly.

  • 400: Invalid parameter or input format
  • 401: Unauthorized (invalid API key)
  • 429: Rate limit exceeded
  • 500: Internal server error during synthesis

Refund for failures

If synthesis fails, the charge is returned in full. You do not need to submit a ticket for automatic refunds on failed requests. Your balance remains accurate based on successful generations only.

Debugging tips

Check the input length carefully; texts over 4096 characters will fail. Verify that the voice parameter matches one of the eight available presets. If using a non-English language, ensure the language field is explicitly set to avoid incorrect language guessing.

Advanced Features

Sound wave illustration for: Advanced Features

Beyond basic synthesis, VerbaClear’s API offers precise control over language detection and long-form content processing, ensuring your fintech alerts remain clear and coherent regardless of source text complexity. These features handle the heavy lifting so your product team can focus on user experience.

By understanding how the API manages linguistic nuances and character limits, you can build robust notification systems that scale efficiently without manual intervention or audio fragmentation.

Language specification

The API automatically detects language from the script, defaulting to English for Latin text. However, for non-English Latin-script texts, explicitly setting the language parameter is recommended to ensure accurate synthesis. Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

Long text splitting

Each request supports up to 4096 characters. For longer texts, split the input into parts, synthesize each part, and join the resulting audio files. This approach maintains audio quality and ensures efficient processing within the API's constraints.

Voice selection

Choose from eight presets tailored for different tones: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice can speak any of the supported languages, allowing you to maintain brand consistency across global notifications. Select the voice that best matches your alert’s urgency and style.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Each voice maintains a consistent tonal character—such as upbeat, calm, or deep—throughout the generation.

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. TRON developer hub: TRC-20
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. Node.js documentation
  5. IETF RFC 7845: Ogg Opus
  6. LibriTTS-R corpus (OpenSLR 141)
  7. Creative Commons Attribution 4.0
  8. LibriVox public-domain audiobooks
  9. curl documentation
  10. MDN: Web Speech API
  11. ISO 639 language codes
  12. Python documentation

More on this site