Cloud TTS API: Integration Guide & Pricing

By VoxLocale editorial team · Updated 2026-11-18

This guide helps localization agencies integrate VoxLocale’s text-to-speech API into their dubbing pipelines. You will learn how to generate audio files from text using standard JSON requests, compatible with the OpenAI SDK. The documentation covers authentication, voice selection, and format options for 23 languages.

We provide concrete examples for cURL and Python integration. You will find details on rate limits, character quotas, and text processing rules. This page is designed for developers who need a reliable, character-based TTS solution to scale voice-over production without hiring extra talent.

Cloud TTS API: Integration Guide & Pricing

Frequently asked questions

How do I generate an API key?

Navigate to /get-api-key/ and sign up using Google or an email and password. Your unique API key appears on the dashboard immediately. You can issue a new key at any time, which instantly invalidates the previous one, ensuring secure access for your localization projects.

Can I use the OpenAI Python SDK?

Yes. The API uses the same request shape as the OpenAI speech endpoint. Simply update the base_url to https://api.playyy9.com/v1 in your OpenAI SDK configuration. This allows you to use standard OpenAI client libraries without writing custom HTTP logic for your dubbing pipeline.

What is the maximum text length?

Each request supports up to 4096 characters in the input field. Spaces and punctuation count toward this limit. For longer scripts, split your text into chunks of 4096 characters or less, generate each segment, and join the resulting audio files to create your final voice-over.

How do I set the voice parameter?

Include one of the eight preset voice names in the voice field of your JSON request body. Available options include aria, nova, luna, sage, felix, milo, atlas, and orion. You can view the full list and details by sending a GET request to /v1/voices.

Can I adjust the speed of the audio?

Yes, use the speed parameter to control playback rate. Acceptable values range from 0.25 to 4.0. This allows you to fine-tune the pacing of your localized content to match the original video’s timing or to fit specific character limits within your dubbing workflow.

Do I need to specify the language?

It is recommended to set the language field using an ISO code. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin text, explicitly setting the language ensures accurate pronunciation and prevents misidentification in your localization projects.

What happens if I exceed the rate limit?

The API allows 60 requests per minute per key (10 per minute before your first top-up). If you exceed this limit, your requests will be queued and processed sequentially. Under heavy load, generation may take longer than usual as requests wait in line.

Is the API synchronous or asynchronous?

The API is synchronous. You send a POST request to /v1/audio/speech and receive the audio file directly in the response. There is no WebSocket or streaming support for partial audio, so you must wait for the full synthesis to complete before receiving the file.

How do I handle large files?

Split your input text into segments of up to 4096 characters. Send each segment as a separate request to the speech endpoint. Once you receive all the individual audio files, concatenate them in order to create the final continuous audio file for your dubbing project.

Can I use the same key on multiple projects?

Yes, you can use your single active API key across multiple projects or services. Each account has one active key, but you can issue a new key at any time if needed. The new key becomes active immediately, and the old one stops working at once.

What is the response format?

You can specify the response_format as mp3, wav, opus, flac, or pcm. The API returns the generated audio file directly in the HTTP response body. This allows you to integrate the audio directly into your video editing or localization pipeline without additional conversion steps.

Do I need to install extra libraries?

No extra libraries are required beyond standard HTTP clients. You can use plain HTTP requests or the official OpenAI SDKs by adjusting the base URL. No custom SDK or mobile library is needed, making integration straightforward for your existing development workflows and automation scripts.

How do I authenticate my requests?

Include your API key in the Authorization header as a Bearer token. The format is Authorization: Bearer tts-.... Ensure you use the key generated from your account dashboard. Failed requests are free, so authentication errors will not incur charges against your balance.

What are the common error codes?

The API uses standard HTTP status codes. Common errors include 401 for invalid authentication, 429 for rate limit exceeded, and 400 for invalid parameters like unsupported voices or format. Failed synthesis requests are free, so you can retry without worrying about character consumption on errors.

First request

curl

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

Get Your API Key

Sound wave illustration for: Get Your API Key

Access the /get-api-key/ page to create your VoxLocale account. This is the entry point for obtaining the credentials needed to call our TTS API. You will need an active account to generate the bearer token required for authentication.

Sign Up on /get-api-key/

Sign Up on /get-api-key/

Navigate to the sign-up page to register. You can create an account using your Google account or by providing an email address and password. Each site in our network maintains independent accounts, so ensure you are signing up on the correct domain.

  • Independent account per site
  • No minimum spend required

Google or Email Authentication

Google or Email Authentication

You may authenticate via Google SSO or traditional email/password login. Google sign-ups receive a $0.50 free trial credit valid for 7 days. Email-based accounts start with zero balance and require a top-up before use.

Copy Your Bearer Token

After logging in, locate your API key on the dashboard. This key starts with 'tts-' and serves as your Bearer token. Copy it securely; you will include it in the Authorization header of every API request.

  • Format: Bearer tts-...
  • One active key per account

Make Your First Request

Sound wave illustration for: Make Your First Request

Send a POST request to https://api.playyy9.com/v1/audio/speech with your text payload. The API returns the generated audio file directly in the response body, allowing you to save it or pass it to your dubbing pipeline.

cURL Example

Use this command to generate speech with the nova voice in English. Replace YOUR_API_KEY with your token from /get-api-key/.

  • curl -X POST "https://api.playyy9.com/v1/audio/speech" \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}'

JSON Body Structure

The request body is standard JSON. You can include optional fields like speed (0.25–4.0) or language to override auto-detection.

Required Fields

Three fields are mandatory for every synthesis job.

  • model: "tts-1" or "tts-1-hd"
  • input: Text string (max 4096 characters)
  • voice: One of the 8 available presets

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Leverage existing OpenAI client libraries to integrate VoxLocale’s TTS API with minimal code changes. By simply adjusting the base URL configuration, you can utilize the official SDKs without rewriting request logic or handling authentication headers manually.

Set base_url

Configure your OpenAI SDK client to point to the VoxLocale API endpoint. This ensures all standard speech generation methods route through our infrastructure while maintaining the familiar request structure.

Use Official SDK

The official OpenAI SDKs work seamlessly because our endpoint shape matches theirs. You can continue using your preferred language client (Python, Node.js, etc.) without learning a new API syntax.

Change Endpoint URL

Update the base URL to https://api.playyy9.com/v1. This directs requests to our processing servers, allowing you to use standard voice and model parameters immediately.

Available Voices

Sound wave illustration for: Available Voices

VoxLocale provides eight distinct voice presets designed to cover the full spectrum of localization needs. Each voice is derived from licensed LibriTTS-R and public-domain LibriVox readings, ensuring clear, high-quality audio for dubbing pipelines without the need for hiring additional talent.

Aria and Nova (Female)

Aria offers a warm, clear narration style. Nova delivers a bright, upbeat tone. Both voices support all 23 languages, allowing consistent character branding across global releases.

Felix and Milo (Male)

Felix brings an energetic, promo-ready energy. Milo provides a friendly, conversational tone. Like all voices, they handle multi-language scripts seamlessly without accent drift.

Atlas and Orion (Neutral/Deep)

Atlas serves as a neutral, news-style voice. Orion offers a deep, documentary-grade tone. Both are optimized for clarity and can be adjusted via the speed parameter (0.25–4.0) to fit exact timing requirements.

Supported Formats

Sound wave illustration for: Supported Formats

VoxLocale supports MP3, WAV, OPUS, and FLAC output formats, letting you choose the right balance of quality and file size for your dubbing pipeline. Selecting the appropriate format ensures seamless integration with your existing audio editing and localization workflows.

MP3 for Web

MP3 is a standard choice for web playback. It offers a compact file size while maintaining clear audio quality, making it ideal for quick delivery to final clients or embedding in video players.

  • Ideal for web playback and streaming
  • Compact file size for faster delivery
  • Broad compatibility with media players

WAV for Editing

Choose WAV when you need uncompressed audio for professional editing. This format preserves the full fidelity of the generated speech.

  • Uncompressed, high-fidelity audio
  • Perfect for professional post-production
  • No quality loss during editing

FLAC and OPUS Options

FLAC provides lossless compression, while OPUS offers efficient quality at low bitrates. Both formats provide efficient storage without sacrificing the clarity needed for voice-over work.

  • FLAC: Lossless compression for masters
  • OPUS: Efficient bandwidth usage
  • High quality at low bitrates
Supported Formats

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

VoxLocale provides a reliable TTS API designed for automation pipelines. Understanding rate limits ensures your dubbing jobs process smoothly.

60 Requests Per Minute

Each API key supports up to 60 requests per minute once fully active. This limit applies to all synthesis endpoints and ensures stable performance for your automated workflows.

10 Requests Before Top-Up

New accounts start with a lower quota of 10 requests per minute. This applies until you complete your first top-up via USDT (TRC-20). Once credited, your limit increases to the full 60 requests per minute.

Queue Processing

Requests are processed sequentially. If you exceed the rate limit or hit peak load, new requests may wait in a queue. Longer texts generate in roughly real-time, so plan your batching strategy to avoid bottlenecks during large-scale dubbing projects.

Error Handling

Sound wave illustration for: Error Handling

When integrating the TTS API, understanding error responses ensures your dubbing pipeline remains robust. Client errors typically indicate issues with your request payload, authentication, or rate limits, while server errors suggest temporary infrastructure hiccups that you can safely retry.

4xx Client Errors

A 4xx response (e.g., 400 Bad Request, 401 Unauthorized, or 429 Too Many Requests) indicates an issue with your specific request. Common causes include invalid JSON syntax, an expired or incorrect Bearer token, or exceeding the 60 requests per minute limit. Ensure your model, voice, and input fields are correctly formatted before retrying.

  • 401: Check your Bearer token validity.
  • 429: Wait before retrying to respect rate limits.

5xx Server Errors

Server errors (500–503) are rare but may occur during peak load or brief maintenance. These indicate the API service itself encountered an issue. Since failed synthesis requests are free, you are not charged for retries triggered by 5xx errors, making it safe to implement exponential backoff without financial risk.

Retry Logic

Implement exponential backoff for both 429 and 5xx errors. Start with a short delay (e.g., 1 second) and double it with each attempt. For 429 errors, always respect the Retry-After header if provided. This strategy prevents overwhelming the queue during high-demand periods, ensuring your audio files are delivered smoothly.

  • Use exponential backoff for transient errors.
  • Respect Retry-After headers for rate limits.

Text Processing Rules

Sound wave illustration for: Text Processing Rules

The API enforces a strict 4096-character limit per request, counting all spaces and punctuation. This constraint limits the size of each request.

4096 Character Limit

Each API call accepts input text up to 4096 characters. Exceeding this limit results in a 400 Bad Request error. The character count includes every space, comma, and special character in your payload.

Manual Splitting for Long Text

For longer scripts, split your text into chunks of 4096 characters or fewer. Submit each chunk as a separate POST request. This approach maintains audio quality and ensures reliable delivery for dubbing pipelines.

Audio Joining Strategy

Receive individual audio files for each chunk. Concatenate these files sequentially to reconstruct the full narration. Since requests are processed sequentially, ensure your client handles the output files in the correct order to avoid audio gaps.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Unlike many consumer-grade platforms, we do not use your input text to train our models.

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. openai-python on GitHub
  3. curl documentation
  4. TRON developer hub: TRC-20
  5. W3C WAI: making audio and video accessible
  6. Python documentation
  7. MDN: Web Speech API
  8. OpenAI API reference: create speech
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. LibriVox public-domain audiobooks
  11. Tether (USDT)
  12. IETF RFC 7845: Ogg Opus

More on this site