Developer Documentation for the TTS API Integration

By VocalSync editorial team · Updated 2026-11-18

This documentation provides the technical specifications for integrating the VocalSync text-to-speech API. It covers authentication, endpoint structures, and parameter configurations required to automate high-volume voiceover workflows for YouTube agencies. The guide assumes familiarity with standard HTTP requests and JSON payloads.

Readers will find precise details on request limits, supported response formats, and error handling procedures. The content is tailored for developers who need to implement reliable, character-based TTS generation without managing complex infrastructure. Use this reference to build robust integrations using the official OpenAI SDKs or plain HTTP clients.

Developer Documentation for the TTS API Integration

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or email plus password. The dashboard displays your active API key, balance, and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one. Each account is tied to a specific site instance.

Does the API support streaming?

No. The API is synchronous; you send a POST request and receive the complete audio file in the response. There is no WebSocket support or real-time partial audio streaming. You must wait for the full synthesis to complete before receiving the data.

Is there an official SDK?

No. We do not provide an official SDK. You should use the OpenAI SDK or standard HTTP libraries. Configure the SDK by changing the base URL to our API endpoint. This approach works with any language that supports the OpenAI SDK structure.

How do I set the language?

Pass the optional language field with an ISO code in the JSON body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language is recommended for non-English Latin-script texts to ensure accuracy.

What is the max text length?

The maximum input length is 4096 characters per request. For longer texts, split the input into parts of up to 4096 characters, generate audio for each part, and join the resulting audio files. Spaces and punctuation count toward this character limit.

Can I use the OpenAI SDK?

Yes. The request shape matches the OpenAI speech endpoint. Change the SDK's base_url to https://api.playbd11.com/v1 and use your site-specific key. This allows you to use the official OpenAI SDKs directly without modifying the core request logic.

How do I handle rate limits?

The limit is 60 requests per minute per key, or 10 per minute before the first top-up. Requests are processed sequentially, so under load, requests may queue. Implement retry logic with exponential backoff to handle temporary delays or queueing during high traffic.

What happens on a 401 error?

A 401 error indicates an invalid or missing API key. Ensure your Authorization: Bearer header contains a valid key from your dashboard. If you recently rotated your key, ensure you are using the new one, as the old key stops immediately upon issuance.

Is SSML supported?

No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You can only control basic parameters like voice, speed, and response format. For precise control, you must adjust the input text directly rather than using markup tags.

Can I clone voices?

No. We do not offer custom voice cloning or the ability to upload your own voice. You must choose from the eight available presets. These voices are based on licensed recordings from LibriTTS-R (CC BY 4.0) and LibriVox public-domain audiobook readings.

How do I rotate keys?

Issue a new key from your dashboard at any time. The new key becomes active immediately, and the old key stops working at once. This allows seamless rotation without downtime. You can generate a new key as often as needed for security.

Is the API RESTful?

Yes. The API uses standard HTTP methods and JSON bodies. Use POST for speech generation and GET for retrieving voices or models. It follows RESTful conventions, making it easy to integrate with existing HTTP clients and libraries that support standard web protocols.

What is the base URL?

The base URL is https://api.playbd11.com/v1. Use this for all API requests. For the speech endpoint, POST to https://api.playbd11.com/v1/audio/speech. Ensure your SDK or HTTP client is configured to point to this domain for correct routing and authentication.

Do I need a WebSocket connection?

No. The API is entirely HTTP-based. You do not need a WebSocket connection for streaming or real-time updates. All interactions are request-response cycles. Send your text via POST and receive the audio file directly in the HTTP response body.

First request

curl

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

Include your API key in the Authorization header using the Bearer scheme. Every request to https://api.playbd11.com/v1 requires Authorization: Bearer tts-.... Keys are tied to your account balance and rate limits.

Bearer Token

Bearer Token

Pass the token in the HTTP header for every API call. The system validates the key before processing the request. If the token is missing or invalid, the server returns a 401 Unauthorized error immediately.

Key Management

Key Management

Each account holds one active key, visible on your dashboard at /get-api-key/. You can issue a new key at any time via the dashboard. The previous key stops working instantly upon generation of the new one.

  • One active key per account
  • Instant invalidation of old keys
  • Visible in account dashboard

Key Rotation

Rotate keys by generating a new one from the dashboard. The old key becomes invalid immediately. Update your agency’s automation scripts to use the new key to avoid service interruption during deployment.

Speech Endpoint

Sound wave illustration for: Speech Endpoint

The core synthesis endpoint accepts text and returns audio files via a standard POST request. It mirrors the OpenAI speech endpoint structure, allowing agencies to integrate VocalSync into existing pipelines by simply updating the base URL to https://api.playbd11.com/v1. This compatibility ensures that official OpenAI SDKs function correctly with minimal code changes.

Submit your text payload along with the desired voice and format settings. The API processes the request and returns the synthesized audio file directly in the response body, ready for immediate playback or storage in your YouTube production workflow.

POST /v1/audio/speech

Send a POST request to the speech endpoint with your authentication token and JSON payload. The endpoint processes the request and returns the audio data. Ensure your input text does not exceed 4096 characters per request; longer scripts must be split client-side.

  • Endpoint: POST https://api.playbd11.com/v1/audio/speech
  • Auth: Bearer token in header
  • Input: JSON body with model, voice, and text

JSON Body Structure

The request body requires specific fields to define the output. The model field accepts either tts-1 or tts-1-hd, both using the same engine and pricing tier. You must specify the input text, a voice preset from our eight options, and the desired response_format.

  • model: 'tts-1' or 'tts-1-hd'
  • input: string (max 4096 chars)
  • voice: one of 8 presets (e.g., 'nova', 'atlas')
  • response_format: mp3, wav, opus, flac, or pcm
  • speed: 0.25 to 4.0 (optional)
  • language: ISO code (optional)

Response Format

On success, the endpoint returns the audio file with the appropriate content-type header (e.g., audio/mpeg). Failed requests incur no charge and return a JSON error object with details. For long texts, split your input into chunks and join the resulting audio files client-side to maintain synchronization.

Voices Endpoint

Sound wave illustration for: Voices Endpoint

The /v1/voices endpoint returns the full catalog of available synthesis voices, their supported languages, and pricing tiers. This data allows your application to dynamically populate dropdown menus or validation checks before sending a speech request.

Use this endpoint to verify voice availability and ensure your selected voice matches the target language code. It provides the essential metadata needed to configure the POST /v1/audio/speech request accurately.

GET /v1/voices

Send a GET request to /v1/voices with your Bearer token to retrieve the complete list of available voices and their attributes. The response includes voice IDs, gender, and supported language codes.

This endpoint is lightweight and can be called once during initialization to cache voice options, reducing latency during runtime speech generation.

  • Returns a JSON array of voice objects.
  • Includes voice ID, name, gender, and language support.
  • No pagination required; returns all 8 voices.

Voice List

The API provides 8 distinct voice presets: four female voices (Aria, Nova, Luna, Sage) and four male voices (Felix, Milo, Atlas, Orion). Each voice offers a specific tonal character, from warm narration to energetic promo styles.

All voices support the full 23-language list. Select the voice ID that best matches your content's tone, such as Atlas for neutral news or Orion for deep documentary styles.

  • 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 supports 23 languages, including English, Spanish, German, Japanese, and Hindi. You can optionally specify a language ISO code in your request to guide the synthesis engine.

If the language parameter is omitted, the engine guesses the language from the text script. For non-English Latin-script text, always set the language code explicitly to ensure accurate pronunciation.

Supported languages include Arabic, Chinese, Danish, Dutch, Finnish, French, Greek, Hebrew, Italian, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Swahili, Swedish, and Turkish.

  • English, Spanish, French, German, Italian.
  • Japanese, Korean, Chinese, Arabic, Hindi.
  • Russian, Portuguese, Turkish, Polish, Dutch.
  • Swedish, Norwegian, Danish, Finnish, Greek.
  • Hebrew, Malay, Swahili, Chinese (Mandarin).

Models Endpoint

Sound wave illustration for: Models Endpoint

The /v1/models endpoint returns the available synthesis engines. This data is static and defines the two supported architectures: the standard model for cost efficiency and the high-definition variant for superior audio fidelity.

GET /v1/models

Send a GET request to this endpoint to retrieve the current list of available models. The response confirms the supported engine IDs, allowing your integration to dynamically select the appropriate model based on budget or quality requirements.

Model IDs

The API supports two model IDs: "tts-1" and "tts-1-hd". These IDs are used in the model field of the speech request. Both models use the same engine and price but differ in output quality.

  • tts-1: Standard quality, lower latency
  • tts-1-hd: High-definition quality

Engine Details

Both models share the same voice presets and language support. The primary difference lies in the neural network complexity. "tts-1-hd" provides richer audio detail but may take marginally longer to generate. Pricing remains identical for both models at $10 per 1 million characters.

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts text input up to 4,096 characters per request. Spaces and punctuation count toward this limit. For longer scripts, split the text into chunks and join the resulting audio files.

Input Text Limits

Each request must contain text under 4,096 characters. Generate audio for longer content by splitting the source text and concatenating the output files.

  • Maximum length: 4,096 characters per request
  • Serves as the primary constraint for single synthesis calls

Voice Selection

Select from eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Any voice supports all 23 languages. If the language field is omitted, the system guesses the language from the script, defaulting to English for Latin text.

  • 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

The speed parameter accepts values between 0.25 and 4.0. Use this to adjust playback rate without re-synthesizing the audio. This allows fine-tuning of narration pacing for specific video segments.

  • Range: 0.25 to 4.0
  • Adjusts playback speed post-generation
Request Parameters

Response Formats

Sound wave illustration for: Response Formats

VocalSync returns synthesized audio as binary data, allowing immediate file saving. Choose the format that best balances your bandwidth constraints with playback compatibility across different media players and editing software.

MP3 Output

MP3 is the default and most compatible format, suitable for web playback and most video editors. It is the default and most compatible format.

  • Default response format
  • Universal player support
  • Optimal for web streaming

WAV Output

WAV provides uncompressed, lossless audio data. This format is ideal for professional post-production where you need to apply effects or compress the audio later without generational quality loss.

  • Lossless audio quality
  • Best for editing pipelines
  • Larger file size

Opus and FLAC

Opus delivers high-quality audio at very low bitrates, reducing bandwidth costs for large-scale deployments. FLAC provides lossless compression, offering smaller files than WAV without sacrificing any audio fidelity.

  • Opus: High quality at low bitrates
  • FLAC: Lossless compression
  • Supports both formats via response_format parameter

Rate Limits

Sound wave illustration for: Rate Limits

VocalSync enforces a strict rate limit of 60 requests per minute per API key. This ceiling ensures stable generation for high-volume agency workflows, preventing resource contention during peak narration production hours. Each request processes sequentially, meaning concurrent jobs may experience slight delays depending on text length.

For new accounts, the initial limit is reduced to 10 requests per minute until the first top-up is processed. This protects infrastructure during the trial phase, after which the standard 60 RPM limit applies automatically to your active key.

60 Requests Per Minute

The standard limit is 60 requests per minute. Since generation takes roughly real-time (25 characters per second), longer texts consume the quota faster than short phrases. Plan your batch sizes accordingly to avoid hitting the cap during active production runs.

Requests are processed one after another. If you send multiple long-text requests simultaneously, they will queue sequentially. Ensure your integration handles HTTP 429 Too Many Requests responses by implementing exponential backoff.

  • Limit: 60 requests/minute per key
  • Processing: Sequential
  • Retry: Exponential backoff recommended

New Account Limits

New accounts start with a 10 requests per minute limit. This lower threshold applies immediately upon account creation. The limit increases to 60 RPM automatically within minutes after your first USDT (TRC-20) top-up of at least $5 is confirmed on the TRON network.

This mechanism ensures fair usage during the trial period without requiring manual verification. Once the top-up is credited, your key resumes standard throughput immediately.

Queue Behavior

Under load, requests enter a processing queue. Short phrases may take a few seconds to generate, while longer texts approach real-time speed. Delays are normal during peak usage and do not indicate a failure.

Failed requests do not consume your character balance. Monitor your usage dashboard to adjust batch sizes if you consistently hit the 60 RPM ceiling.

Error Handling

Sound wave illustration for: Error Handling

Robust error handling ensures your YouTube narration pipeline remains stable during high-volume synthesis. VocalSync returns standard HTTP status codes to indicate success or failure, allowing your scripts to distinguish between transient network issues and permanent configuration errors.

HTTP Status Codes

Use standard codes like 200 for success, 400 for bad requests (e.g., invalid JSON or missing fields), and 429 for rate limit exhaustion.

  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 429: Too Many Requests
  • 500: Internal Server Error

Error Messages

The response body includes a descriptive error message explaining the failure reason, such as exceeding the 4096 character input limit or an invalid voice ID.

  • Check the 'message' field for details
  • Validate input length before sending
  • Verify voice ID exists in GET /v1/voices

Retry Logic

Implement exponential backoff for 5xx errors and 429 responses. For 400 errors, check the payload and retry only if the issue is transient, as invalid parameters will fail repeatedly.

  • Retry 5xx errors immediately
  • Backoff on 429 limits
  • Fail fast on 400 errors

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. We empower creators by delivering precise audience insights that drive meaningful engagement for agencies.

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. Node.js documentation
  3. LibriVox public-domain audiobooks
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. Python documentation
  6. LibriTTS-R corpus (OpenSLR 141)
  7. OpenAI API reference: create speech
  8. FFmpeg documentation
  9. Tether (USDT)
  10. IETF RFC 7845: Ogg Opus
  11. TRON developer hub: TRC-20
  12. openai-python on GitHub

More on this site