API Documentation for Speech Synthesis Online

By VerbaCore editorial team · Updated 2026-11-18

This page provides the complete API documentation for VerbaCore’s text-to-speech service, designed specifically for fintech teams and banking infrastructure. You will find precise technical details on how to integrate speech synthesis into your customer notification workflows, including authentication, endpoint structures, and parameter definitions. The guide covers all essential aspects of the API, ensuring you can deploy reliable audio delivery for high-volume use cases.

We have structured this documentation to help engineering teams implement the solution quickly and correctly. You will see how to use standard OpenAI SDKs with our base URL, understand rate limits, and handle errors effectively. Whether you are sending bulk notifications or processing individual user requests, this guide gives you the concrete code examples and technical facts needed to get started immediately.

API Documentation for Speech Synthesis Online

Frequently asked questions

How do I get an API key?

Sign up on /get-api-key/ using Google or email. Accounts are per site. The dashboard displays your active key, balance, and usage details immediately after registration. You can issue a new key at any time, which stops the old one instantly.

What is the base_url for the API?

Use https://api.playq22.com/v1 as your base URL. Send POST requests to /v1/audio/speech for synthesis. Other endpoints include GET /v1/voices for metadata and GET /v1/models. This structure matches the OpenAI speech endpoint format for easy integration.

Can I use OpenAI SDKs?

Yes. The API uses the same request shape as OpenAI’s speech endpoint. Official OpenAI SDKs work by changing the base_url to https://api.playq22.com/v1 and using your site-specific key. This allows seamless migration for teams already familiar with OpenAI’s client libraries.

How do I handle rate limits?

Limits are 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up. Process requests sequentially; under load, requests queue automatically. Split long texts into 4096-character chunks to manage throughput efficiently during high-volume notifications.

What happens if a request fails?

Failed requests are free. If synthesis fails, the charge is returned in full. Request metadata like time, characters, and status are kept for billing, but you are not charged for audio that was not successfully generated. No extra cost for errors.

Which models are available?

Two models exist: "tts-1" and "tts-1-hd". Both use the same engine and price. Choose based on quality needs. The API returns audio files directly. Both models support all eight voice presets and all 23 supported languages for consistent fintech communication standards.

How do I set the language?

Pass the optional language field with an ISO code. If omitted, the system guesses from the script (Latin defaults to English). For non-English Latin text, always set language explicitly. Supported languages include English, Spanish, German, French, and 19 others.

Can I control the speed?

Yes, use the speed field with values between 0.25 and 4.0. This allows fine-tuning audio length for customer notifications. Faster speeds reduce latency, while slower speeds improve clarity. The API processes requests sequentially, so speed adjustments help manage queue times.

What is the character limit?

Each request accepts up to 4096 characters in the input field. Spaces and punctuation count. For longer texts, split into parts of this size and join the resulting audio files. This ensures consistent processing and avoids timeouts during high-volume batch notifications.

How do I revoke a key?

Issue a new key via the dashboard. The old key stops working instantly when the new one is active. You can do this anytime. This provides immediate security control without waiting for expiration. Only one key is active per account at a time.

Is SSML supported?

Q: Is SSML supported? A: No, SSML is not supported. The API accepts plain text input. You cannot use phoneme dictionaries or custom pronunciation lexicons.

Can I stream audio?

No streaming or WebSocket support exists. Audio is returned as a complete file in the response. Use formats like mp3, wav, opus, flac, or pcm. This is suitable for batch processing where real-time partial audio is not required for customer notifications.

How do I authenticate?

Use the header Authorization: Bearer tts-... with your active key. One key per account. Generate new keys via the dashboard to revoke old ones instantly. Ensure your key is secure in your fintech infrastructure to prevent unauthorized audio generation requests.

What errors can occur?

Common errors include rate limit exceeded (60 req/min) or invalid input. Failed synthesis returns full refunds. Ensure text is under 4096 characters. Check voice names and language codes. Network errors may cause retries.

First request

curl

curl https://api.playq22.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.playq22.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.playq22.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 access to the speech synthesis engine relies on a single API key issued to your account. You will include this credential in every request to ensure your usage is billed correctly against your balance.

Use Bearer token in Authorization header

Use Bearer token in Authorization header

Include your key as a Bearer token in the Authorization header of your HTTP requests. This standard method keeps your credentials separate from the payload and works seamlessly with existing fintech infrastructure.

One active key per account

One active key per account

Each account holds exactly one active key at any given time. This simplifies permission management for large banking teams, ensuring a single point of control for all API usage.

Revoke and issue new keys anytime

If a key is compromised or you need to rotate credentials, you can issue a new key at any time. The previous key stops working immediately, ensuring no overlap or lingering access.

Endpoint for speech synthesis

Sound wave illustration for: Endpoint for speech synthesis

The synthesis endpoint accepts your text and converts it into audio instantly. It is the core of the API, designed for high-volume banking notifications where reliability matters. You send a simple POST request, and the system handles the rest.

POST /v1/audio/speech

Send your request to this endpoint with the correct base URL. The API processes texts up to 4,096 characters per call. For longer messages, split the text and join the resulting audio files to maintain quality and meet limits.

  • Endpoint: POST /v1/audio/speech
  • Max input: 4,096 characters
  • Process: Split long texts if needed

JSON body with text and voice

Structure your request with the input text, voice preset, and model. Choose from eight voices like aria for warm narration or atlas for neutral news updates. Each voice supports all 23 languages, ensuring consistent tone across your global customer base.

  • input: Your text string
  • voice: One of 8 presets
  • model: tts-1 or tts-1-hd

Returns audio file directly

The response contains the audio file directly in the body. Formats include mp3, wav, opus, flac, and pcm. There is no streaming or partial audio; the entire file is delivered once synthesis completes, ensuring you have the full notification ready to play.

  • Formats: mp3, wav, opus, flac, pcm
  • Direct audio return
  • No streaming

Request parameters

Sound wave illustration for: Request parameters

The API request parameters define how your text is transformed into audio. You specify the synthesis model, the input text, and the voice preset to ensure the output matches your fintech notification requirements.

model: tts-1 or tts-1-hd

Choose between "tts-1" for standard quality or "tts-1-hd" for high-definition audio. Both models use the same underlying engine and pricing, allowing you to select based on your latency and quality needs for banking alerts.

input: text up to 4,096 characters

Provide your notification text in the "input" field, with a maximum limit of 4,096 characters per request. Spaces and punctuation count toward this limit. For longer texts, split them into chunks and join the resulting audio files.

voice: one of 8 presets

Select from eight distinct voice presets to match your brand tone. Use "sage" for calm, instructional alerts or "milo" for friendly, conversational updates. Other options include aria, nova, luna, felix, atlas, and orion.

Response formats

Sound wave illustration for: Response formats

Your API call returns the synthesized audio directly in the response body, eliminating the need for separate download steps. You select the desired format via the response_format parameter, with options including mp3, wav, opus, flac, and pcm. This direct delivery ensures seamless integration into your fintech notification pipelines or voice banking applications without intermediate storage requirements.

mp3, wav, opus, flac, pcm

Choose the format that best fits your delivery channel. MP3 offers efficient compression for web playback, while WAV provides uncompressed quality for legacy systems. OPUS and FLAC deliver high-fidelity audio, and PCM is available for raw data processing. All formats are generated instantly upon request completion.

  • MP3: Standard compressed audio for web and mobile apps.
  • WAV: Uncompressed PCM audio for high-quality playback.
  • OPUS: Efficient high-quality audio for low-bandwidth environments.
  • FLAC: Lossless compression for archival quality.
  • PCM: Raw uncompressed audio data.

Audio file in response body

The generated audio file is returned immediately in the HTTP response body. You do not need to poll for a file ID or wait for an asynchronous job to complete. This synchronous delivery model simplifies error handling and ensures your application receives the exact audio asset corresponding to the submitted text.

No streaming or partial audio

The API does not support streaming or WebSocket connections for real-time audio chunks. The entire audio file is generated and returned as a single unit. This means you cannot receive partial audio while synthesis is ongoing; you must wait for the full response before processing or playing the audio.

Rate limits

Sound wave illustration for: Rate limits

Your API key allows 60 requests per minute, providing sufficient throughput for standard fintech notification workflows. This limit applies per key, so you can manage concurrent streams effectively by monitoring your usage dashboard.

Before your first top-up, the limit is reduced to 10 requests per minute. This ensures stable performance during initial testing phases. Once you add funds, the full 60 req/min capacity is immediately available.

60 requests per minute per key

The standard rate limit is 60 requests per minute for each active API key. This capacity supports high-volume audio generation for customer notifications without requiring complex queue management on your end.

  • Limit applies per key, not per account.

10 requests before first top-up

New accounts start with a lower limit of 10 requests per minute. This allows you to verify integration stability before committing to higher volumes. The limit increases automatically after your first USDT top-up.

Requests processed in queue

Requests are processed sequentially under load. If you exceed the instantaneous capacity, requests may wait in a queue before synthesis begins. Typical speed is roughly real-time, but short phrases may take a few seconds to generate.

Rate limits

Error handling

Sound wave illustration for: Error handling

When synthesis fails, you are not charged. The API returns a full refund for any failed request, ensuring you only pay for successful audio generation. This protects your budget during high-volume notification campaigns when network hiccups might occur.

Always verify the HTTP status code to diagnose issues quickly. Standard error codes indicate whether the problem lies with authentication, input limits, or temporary service availability.

Failed requests are free

If the synthesis engine cannot process your text due to internal errors, the charge is returned in full. You do not lose credits for attempts that do not produce an audio file.

This policy applies to all models, including tts-1 and tts-1-hd, making it safe to implement robust retry logic without financial risk for transient failures.

  • Failed requests incur zero cost.
  • Credits are refunded automatically.
  • Applies to all voice models.

Check status code for issues

Inspect the response status code to determine the root cause. A 4xx error typically indicates an issue with your request, such as an invalid API key or exceeding the 4,096 character limit.

A 5xx error suggests a temporary server-side issue. In these cases, the request is processed later or refunded, depending on the specific failure mode.

  • 400: Bad Request (invalid parameters).
  • 401: Unauthorized (invalid key).
  • 429: Too Many Requests (rate limit).

Retry on network errors

For transient network issues, implement exponential backoff when retrying requests. Since requests are processed in a queue, immediate retries might hit rate limits.

Wait briefly before retrying to allow the queue to clear, ensuring efficient use of your 60 requests per minute allowance.

  • Use exponential backoff for retries.
  • Respect the 60 RPM limit.
  • Avoid immediate rapid retries.

OpenAI SDK compatibility

Sound wave illustration for: OpenAI SDK compatibility

Integrating VerbaCore into your fintech infrastructure is straightforward if you already use OpenAI’s client libraries. You do not need a proprietary SDK or custom wrapper for basic integration.

Simply point your existing client to our base URL. This allows your team to use familiar tools without learning a new API surface.

Change base_url to api endpoint

Update your client configuration to use https://api.playq22.com/v1 as the base URL. This directs all requests to our synthesis engine while maintaining your existing code structure.

This single change enables seamless communication with our TTS endpoint without modifying your core application logic.

Use official OpenAI SDKs

You can use the official OpenAI Python, Node.js, or other language SDKs. These libraries handle authentication, retries, and JSON serialization for you.

This reduces boilerplate code and lets your developers focus on integrating speech synthesis into your notification pipelines.

Same request shape as OpenAI

Our endpoint accepts the exact same JSON body structure as the OpenAI speech endpoint. Fields like model, input, voice, and response_format work identically.

You can send text up to 4,096 characters and receive audio files in formats like mp3 or wav with minimal code adjustments.

Curl example for banking

Sound wave illustration for: Curl example for banking

Configure your banking notification system to generate audio alerts instantly. The API accepts standard JSON payloads, allowing you to integrate directly into your existing fintech workflows without complex middleware.

Send POST request with text

Construct a POST request to the speech endpoint. Include your message in the input field, ensuring it stays under 4,096 characters. Specify the model and desired voice preset within the JSON body.

  • Use tts-1 or tts-1-hd models
  • Keep text under 4,096 characters
  • Select from 8 voice presets

Set Authorization header

Include your unique API key in the Authorization header using the Bearer scheme. This authenticates your request and ensures accurate billing against your account balance.

Receive audio file

Upon success, the response body contains the audio file directly. Specify your preferred format (mp3, wav, opus, flac, or pcm) in the request to match your playback infrastructure.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Your recent transaction has been successfully processed and verified by our secure banking network.

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. W3C WAI: making audio and video accessible
  3. TRON developer hub: TRC-20
  4. LibriTTS-R corpus (OpenSLR 141)
  5. FFmpeg documentation
  6. Node.js documentation
  7. ISO 639 language codes
  8. IETF RFC 7845: Ogg Opus
  9. Creative Commons Attribution 4.0
  10. openai-python on GitHub
  11. Tether (USDT)
  12. LibriVox public-domain audiobooks

More on this site