Cloud Text-to-Speech API Documentation and Integration Guide

By VoxEdge editorial team · Updated 2026-11-19

This documentation provides the technical specifications for integrating the VoxEdge Text-to-Speech API into fintech and banking notification systems. You will find concrete examples for generating audio files from text, covering all essential parameters like voice selection, speed control, and supported output formats. The guide is designed for indie developers who need a reliable cloud service to replace legacy local engines like pyttsx3, ensuring your automated voice notifications are consistent and compliant.

Start by obtaining your API key via Google or email, then proceed to the basic cURL request and Python SDK integration. We detail how to handle long texts exceeding 4096 characters, manage rate limits, and select from eight distinct voices across 23 languages. All endpoints follow the standard OpenAI request shape, allowing you to use existing SDKs with a simple base URL change for immediate deployment in your production environment.

Cloud Text-to-Speech API Documentation and Integration Guide

Frequently asked questions

How do I get an API key?

Sign up on /get-api-key/ using Google or email plus password. Your account page displays your active API key, balance, and usage details. Each account has one active key; issuing a new key immediately invalidates the previous one.

Is the API compatible with Python?

Yes. Since the request shape matches the OpenAI speech endpoint, you can use the official OpenAI Python SDK by changing the base_url to https://api.idrok.top/v1. Alternatively, you can send standard HTTP POST requests using any Python HTTP library.

What is the base URL?

The API base URL is https://api.idrok.top/v1. You use this for all endpoints, including POST /v1/audio/speech for generation, GET /v1/voices for available options, and GET /v1/models for model information.

Can I use the OpenAI SDK?

Yes. The API uses the same request shape as the OpenAI speech endpoint. You can use the official OpenAI SDKs by simply updating the base_url configuration to https://api.idrok.top/v1 and providing your VoxEdge API key.

What audio formats are supported?

The API supports mp3, wav, opus, flac, and pcm formats. You specify the desired format using the response_format field in your JSON request body. All generated audio files are returned directly in the API response.

How do I handle errors?

If synthesis fails, the request is free and the charge is returned in full. Check the response status code and error message to identify issues like invalid parameters or rate limits. Failed requests do not consume your character balance.

What are the rate limits?

You are limited to 60 requests per minute per key. Before your first top-up, this limit is reduced to 10 requests per minute. Exceeding the limit will result in errors until the window resets.

Can I change my API key?

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

How do I specify a voice?

Include the voice parameter in your request JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. You can also optionally specify a language ISO code to guide synthesis.

Does the API support SSML?

No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You must provide plain text input, which is limited to 4096 characters per request. Complex formatting must be handled by splitting text manually.

How is speed controlled?

Use the speed parameter in your request, accepting values between 0.25 and 4.0. This adjusts the playback speed of the generated audio. Default speed is 1.0.

What happens if text exceeds 4096 characters?

The API limits input to 4096 characters per request. You must split longer texts into smaller parts, generate audio for each part, and then join the resulting audio files. This ensures compatibility with the single-request constraint.

Is streaming supported?

No. The API does not support streaming, WebSocket connections, or real-time partial audio. You receive the complete audio file in the response after synthesis finishes. Requests are processed sequentially, so longer texts may take time to generate.

How do I track usage?

Your account page on /get-api-key/ displays your current balance, trial status, characters left, and usage history. Request metadata including time, characters, and status is kept for billing purposes and visible in your dashboard.

First request

curl

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

Get Your API Key

Sound wave illustration for: Get Your API Key

Create an account on /get-api-key/ using Google or email. The dashboard displays your active API key, current balance, and usage statistics immediately upon login.

Sign Up via Google or Email

Sign Up via Google or Email

Google sign-in provides a $0.50 free trial (50,000 characters, valid 7 days). Email accounts start with zero balance. Use your key in the Authorization header as Bearer tts-....

Key Management and Revocation

Key Management and Revocation

One active key per account. Generate a new key anytime from the dashboard. The previous key stops working immediately upon issuance. No expiration unless manually revoked.

Rate Limits Overview

Limit is 60 requests per minute per key. New accounts without top-ups are limited to 10 requests per minute. Requests are processed sequentially, so high volume may queue.

First Request with Curl

Sound wave illustration for: First Request with Curl

Use a simple curl command to generate speech. Send a JSON payload to the POST /v1/audio/speech endpoint. This basic request confirms your API key works and returns an audio file.

Ensure your key is active and you have sufficient balance. Failed requests are free, so testing is risk-free.

Basic JSON Payload

Send a POST request with a JSON body. The structure matches the OpenAI speech endpoint. Replace YOUR_API_KEY with your actual key from the dashboard.

```bash curl -X POST https://api.idrok.top/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Payment received.", "voice": "nova"}' ```

Required Parameters

Three fields are mandatory: model, input, and voice. model accepts tts-1 or tts-1-hd. input is your text (max 4096 chars). voice must be one of the 8 presets.

Optional fields include response_format, speed, and language. If language is omitted, the system guesses it from the script, defaulting to English for Latin text.

Response Format

A successful request returns the audio file in the requested format (default MP3). Save the output to a file for playback in your fintech app. The response contains the raw audio binary.

If the synthesis fails, you receive an error JSON object explaining the issue. No characters are deducted for failed requests.

Python Integration with OpenAI SDK

Sound wave illustration for: Python Integration with OpenAI SDK

Leverage the official OpenAI Python SDK to integrate VoxEdge’s TTS API with minimal code changes. By simply overriding the base_url configuration, you can direct requests to our cloud endpoint without modifying the core request structure or payload schema.

Changing Base URL

Initialize the OpenAI client and set the base_url to https://api.idrok.top/v1. This directs all standard speech requests to our infrastructure while maintaining compatibility with existing OpenAI SDK methods.

Authentication Setup

Pass your unique API key via the api_key parameter. Ensure the key starts with tts- and is scoped to your account. The SDK automatically attaches the Authorization: Bearer header for each request.

Sending Text Input

Call the audio.speech method with your text input, selected voice, and desired format. The SDK handles the JSON serialization and returns the audio binary stream, which you can save directly to a file or pipe to your notification service.

  • Install the library: pip install openai
  • Set base_url="https://api.idrok.top/v1"
  • Use model="tts-1" or "tts-1-hd"

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

VoxEdge supports four audio formats to suit different deployment needs. Each format balances file size, compatibility, and quality differently, ensuring your fintech notifications load quickly while remaining clear for end-users.

MP3 for Web Delivery

MP3 is the default format for most web-based applications. It offers a balance between file size and audio quality, making it suitable for mobile push notifications or web players where bandwidth matters.

WAV for High Quality

WAV provides uncompressed audio. Use this format when you need pristine sound quality for voice calls or premium user experiences, accepting the larger file size that comes with it.

FLAC for Archiving

FLAC offers lossless compression. This is suitable for long-term storage or archival purposes where you want to keep the original quality for future reprocessing.

Error Handling

Sound wave illustration for: Error Handling

Robust error handling ensures your fintech notifications trigger reliably without silent failures. The API returns standard HTTP codes to indicate the status of each synthesis request, allowing your application to react appropriately based on the specific cause.

400 Bad Request

This error indicates a problem with the request structure, such as missing required fields or invalid character limits. Ensure the input text does not exceed 4096 characters and that the voice parameter matches one of the available presets. Invalid JSON formatting or unsupported response_format values also trigger this response.

  • Check text length against the 4096 character limit.
  • Verify voice names against the /v1/voices endpoint.
  • Ensure valid response_format values (mp3, wav, opus, flac, pcm).

429 Rate Limit Exceeded

Requests are capped at 60 per minute per API key. If your application sends rapid bursts of notifications, you may encounter this limit. New accounts without a top-up start with a lower limit of 10 requests per minute. Implement exponential backoff in your code to handle these intervals gracefully.

  • Standard limit: 60 requests per minute.
  • Pre-top-up limit: 10 requests per minute.
  • Retry strategy: Use exponential backoff.

500 Internal Server Error

A 500 status code signals a server-side issue during synthesis. The request metadata is recorded, but the audio file is not generated. These errors are typically resolved by retrying the request after a short delay, as the underlying engine recovers automatically.

  • Indicates a temporary server-side synthesis failure.
  • No charge is applied if synthesis fails.
  • Safe to retry with a short delay.
Error Handling

Voice Selection

Sound wave illustration for: Voice Selection

VoxEdge provides eight distinct voice presets optimized for automated financial notifications. Each voice is distinct in timbre and pacing, allowing you to match the tone of your fintech application precisely.

Available Voices List

The API supports eight licensed voices derived from LibriTTS-R public domain recordings. Female options include Aria (warm narrator), Nova (bright), Luna (soft storyteller), and Sage (calm instructor). Male voices offer Felix (energetic promo), Milo (friendly conversation), Atlas (neutral news), and Orion (deep documentary).

Each voice is distinct in timbre and pacing, allowing you to match the tone of your fintech application precisely.

  • 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

Gender and Tone Options

Select voices based on the context of your notification. Use Atlas for neutral transaction updates or Orion for detailed investment summaries. For urgent alerts, Milo or Nova provide clear, friendly urgency without sounding alarming.

Language Specification

All eight voices support 23 languages, including English, Spanish, German, French, and Chinese. If the language parameter is omitted, the system guesses from the script, defaulting to English for Latin text. For non-English Latin-script inputs, explicitly set the language code to ensure accurate pronunciation.

Speed Control

Sound wave illustration for: Speed Control

The speed parameter allows you to adjust voice playback from 0.25x to 4.0x, enabling precise control over notification pacing for banking alerts. This flexibility ensures audio remains clear whether delivering quick transaction updates or detailed account summaries.

Adjustable Speed Range

You can set any float value between 0.25 and 4.0 in the request body. Lower speeds (e.g., 0.5x) are useful for complex financial data, while higher speeds (e.g., 2.0x) suit brief status checks.

Default Speed Setting

If you omit the speed field, the API defaults to 1.0x. This standard pace matches natural speech rhythm, making it ideal for general-purpose notifications without additional configuration.

Impact on Clarity

Extreme speeds may slightly reduce intelligibility, especially with non-English languages. We recommend testing 0.25x and 4.0x with your specific text to ensure clarity.

Long Text Handling

Sound wave illustration for: Long Text Handling

Text-to-speech synthesis supports up to 4,096 characters per request. Longer notifications, such as full banking alerts or transaction summaries, require splitting the input text into smaller chunks before submission.

4096 Character Limit

Each API call accepts a maximum of 4,096 characters, including spaces and punctuation. Exceeding this limit results in a 400 Bad Request error. Plan your message structure to fit within this constraint or prepare to segment your content.

Splitting and Joining Audio

Split your text into segments of 4,096 characters or fewer. Send each segment as a separate POST request to generate individual audio files. On the client side, concatenate these MP3 or WAV files into a single continuous file for playback.

Queue Management

Requests are processed sequentially. Under heavy load, a request may wait in a queue before synthesis begins. For time-sensitive banking alerts, monitor the rate limit (60 requests/minute) and stagger your splitting requests to avoid delays.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. For live voice interactions requiring immediate partial audio, consider combining multiple short requests or using a different streaming solution.

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. Creative Commons Attribution 4.0
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. LibriTTS-R corpus (OpenSLR 141)
  6. IETF RFC 7845: Ogg Opus
  7. openai-python on GitHub
  8. Tether (USDT)
  9. LibriVox public-domain audiobooks
  10. MDN: Web Speech API
  11. Node.js documentation
  12. W3C WAI: making audio and video accessible

More on this site