Frequently asked questions
How do I authenticate with the API?
Include your unique API key in the request header as Authorization: Bearer tts-.... Each account maintains one active key; issuing a new key immediately invalidates the previous one, ensuring secure access control for your localization workflows.
What is the base URL for the API?
The API base URL is https://api.playbd2.com/v1. You can use the official OpenAI SDKs by setting this as the base_url and providing your SyncVoice API key.
Which models are available?
Two models are available: tts-1 and tts-1-hd. Both utilize the same engine and pricing structure.
How do I set the voice speed?
Include the speed parameter in your JSON request body, accepting values between 0.25 and 4.0. This allows precise control over the playback rate of the synthesized speech, enabling faster delivery for summaries or slower pacing for detailed instructions.
What happens if I exceed the rate limit?
The standard limit is 60 requests per minute per key (10 per minute before the first top-up). Exceeding this limit may result in request delays or errors. Requests are processed sequentially, so high volumes may experience queueing under load.
Can I send text longer than 4096 characters?
Each request supports up to 4096 characters. For longer texts, split the content into parts of this maximum length, generate audio for each part, and join the resulting audio files. This ensures consistent quality and manageable request sizes.
How do I detect the language automatically?
If the language field is omitted, the system guesses the language from the script. Latin script text defaults to English. For non-English Latin-script text, explicitly set the language parameter to ensure accurate synthesis and avoid mispronunciation.
What is the difference between tts-1 and tts-1-hd?
There is no functional difference between tts-1 and tts-1-hd. Both models use the same engine and incur the same price of $10 per million characters, allowing you to choose either model without affecting cost or audio quality.
How do I handle errors in the API response?
Failed requests are free, with the charge returned in full. Check the HTTP status code and response body for error details. Ensure your text is within the 4096-character limit and that your API key is valid and active.
Is the API synchronous or asynchronous?
You send a POST request and receive the audio file in the response. Requests are processed sequentially, so under heavy load, a request may wait in a queue before synthesis begins and completes.
What audio formats can I request?
You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the desired format using the response_format parameter in your JSON request body. This flexibility allows integration with various video editing and localization pipelines.
How do I rotate my API key?
Issue a new API key from your account dashboard at any time. The new key becomes active immediately, and the old key stops working at once. This allows seamless rotation without downtime for your production voice-over workflows.
Does the API support streaming audio?
No, the API does not support streaming or WebSocket connections. The entire audio file is generated and returned in a single response. This synchronous approach simplifies integration but requires waiting for full generation before playback begins.
Can I use the OpenAI JavaScript SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.playbd2.com/v1. Use your SyncVoice API key for authentication. This allows you to leverage familiar SDK methods for making requests to our text-to-speech service.
First request
curl
curl https://api.playbd2.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playbd2.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.playbd2.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 | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Authentication
The SyncVoice API uses standard Bearer token authentication. Include your unique key in the HTTP header as Authorization: Bearer <key> for every request sent to https://api.playbd2.com/v1. This single key authenticates all endpoints, including speech generation and voice listings.
Each account is assigned exactly one active API key. The key remains valid until you explicitly rotate it. If the key is compromised or you wish to change it, you can generate a new key at any time via the dashboard.
Bearer Token Usage
Pass the token in the Authorization header of every POST and GET request. The API rejects requests missing this header or using an invalid token with a 401 status code. Ensure the key is transmitted securely via HTTPS.
Key Management
Your account holds one active key at a time. You can view the current key and its status on the /get-api-key/ page. The key is generated upon account creation or manual issuance. Store it in your CI/CD environment variables to avoid hardcoding.
- Only one key is active per account.
Key Rotation Policy
Issue a new key at any time through the dashboard. The old key is invalidated immediately upon the new key's creation. This allows for zero-downtime rotation if you update your integration configuration. There is no grace period between keys.
Endpoints Overview
The API provides three primary endpoints for integrating synthetic voice-over generation into localization pipelines. These endpoints handle audio synthesis, voice metadata retrieval, and model status checking, enabling programmatic control over bulk audio production.
Speech Generation Endpoint
Use POST /v1/audio/speech to generate audio files. The endpoint accepts JSON bodies with text input, voice selection, and formatting options, returning the synthesized audio directly in the response.
Voices Listing Endpoint
Call GET /v1/voices to retrieve available voice presets, supported languages, and audio formats. This allows localization teams to programmatically select appropriate voices for different regional content without hardcoding voice IDs.
Models Endpoint
The GET /v1/models endpoint returns current model configurations. This ensures your integration remains compatible with the underlying synthesis engine, supporting both standard and high-definition audio generation modes.
Request Parameters
The API accepts standard TTS parameters to configure audio synthesis. You must specify the engine model, input text, target voice, and playback speed in the request body.
All parameters are strictly validated before processing. Incorrect values return immediate errors, ensuring predictable behavior for automated localization pipelines.
Model Selection (tts-1, tts-1-hd)
Both models use the same engine and price. Select either 'tts-1' or 'tts-1-hd' based on your quality preference without affecting cost calculations.
- tts-1
- tts-1-hd
Input Text Constraints
The 'input' field accepts plain text up to 4096 characters per request. Spaces and punctuation count toward this limit. Exceeding the limit returns an error.
- Max 4096 characters
- Counts spaces and punctuation
Voice and Speed Settings
Select one of eight preset voices from the /v1/voices endpoint. Set 'speed' between 0.25 and 4.0. The 'language' field is optional; if omitted, the system guesses the language from the script.
- 8 voice presets
- Speed: 0.25–4.0
- Optional ISO language code
Response Formats
The API returns the synthesized audio file directly in the response body, allowing your systems to save it immediately to your localization pipeline. Supported formats include MP3, WAV, OPUS, FLAC, and PCM, selected via the response_format parameter to match your downstream encoding requirements.
The response includes the audio file; request metadata (time, characters, status) is kept for billing. This structure allows your automation tools to verify successful generation before proceeding with video sync or batch processing workflows.
Audio File Delivery
Audio files are returned as raw binary data within the HTTP response body. You must specify the desired format (mp3, wav, opus, flac, or pcm) in the request to ensure compatibility with your existing media infrastructure. The file is not stored on our servers; it is delivered directly in the response payload for immediate consumption.
JSON Metadata
Standard HTTP headers accompany the audio response. Request metadata is kept for billing. This metadata is essential for automated reconciliation of character counts against your account balance.
Error Response Codes
The API returns standard HTTP status codes to indicate the outcome of your request. A 200 OK status confirms successful synthesis. If the request fails, the charge is returned in full. Failed requests incur no charge, and any pre-charged amount is refunded automatically.
Rate Limits and Throttling
The API enforces a strict rate limit of 60 requests per minute per active key. This cap ensures stable throughput for high-volume localization pipelines processing multiple voice-overs simultaneously.
Requests Per Minute
Each API key is limited to 60 requests per minute. This limit applies globally to all endpoints and ensures consistent performance during peak usage periods for large teams.
Pre-Topup Limits
Accounts without a funded balance are restricted to 10 requests per minute. This lower limit allows testing of the integration while preventing resource exhaustion before the first top-up.
Queue Behavior
Requests are processed sequentially. Under heavy load, additional requests may wait in a queue before synthesis begins. Typical generation speed is roughly real-time, but short phrases may take a few seconds to process.

Code Examples
The API mirrors the OpenAI speech endpoint structure, allowing localization teams to reuse existing integrations with minimal configuration. By updating the base_url to https://api.playbd2.com/v1, standard SDKs and HTTP clients can immediately begin generating voice-over assets for video projects.
Python SDK Setup
Initialize the client by pointing it to the SyncVoice base URL. Pass the Bearer token generated from your dashboard. This setup enables direct programmatic generation of audio files for bulk localization tasks.
- Set
base_urltohttps://api.playbd2.com/v1 - Pass
Authorization: Bearer tts-...header - Use standard
openaiorrequestslibraries
cURL Command
Send a POST request to /v1/audio/speech with the desired model, voice, and text input. This method is ideal for quick validation of voice settings or automated scripts in CI/CD pipelines for media asset generation.
- Endpoint:
POST https://api.playbd2.com/v1/audio/speech - Content-Type:
application/json - Body includes
model,input,voice, andresponse_format
Node.js Example
Use the native fetch API or any HTTP library to send the JSON payload. This approach ensures seamless integration with existing Node-based media processing workflows, allowing developers to handle audio binary responses directly in memory or disk.
- Use
fetchoraxios - Set
base_urltohttps://api.playbd2.com/v1 - Handle binary audio response data
Handling Long Texts
SyncVoice API processes input text in segments of up to 4096 characters. For voice-over projects exceeding this limit, the client application must split the source text into sequential chunks. Each chunk generates a distinct audio file via a separate API request.
4096 Character Split
Each API call accepts a maximum of 4096 characters, including spaces and punctuation. To generate a complete voice-over, divide the script into segments that do not exceed this threshold. The application is responsible for managing these segments.
Audio Joining Logic
After receiving individual audio files for each segment, the client must concatenate them in the original order to reconstruct the full audio track. The API does not perform server-side joining; the merge logic resides within the consuming application or local processing pipeline.
Latency Considerations
Processing speed averages roughly 25 characters of text per second of generation time. Requests are processed sequentially, meaning high-volume jobs may experience queue delays. For large scripts, anticipate cumulative latency proportional to the total character count and current system load.
Language Configuration
SyncVoice API supports 23 languages, allowing any of the 8 preset voices to speak any supported language. For precise localization, always specify the language parameter using its ISO code. This ensures consistent output regardless of the script's visual characteristics.
ISO Code Usage
Pass the ISO 639-1 code (e.g., es, de, fr) in the request body. This overrides any auto-detected language and guarantees the voice uses the correct pronunciation rules for the target locale.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Auto-Detection Behavior
If language is omitted, the system guesses the language from the text script. Latin-script text defaults to English. For non-English Latin text, explicitly setting the language is recommended to avoid incorrect pronunciation.
Unsupported Languages
Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali, and other unlisted languages are not supported. Requests for unsupported languages may result in English pronunciation or errors.
- Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This scope targets core localization needs without unnecessary fragmentation.
23 languages
Any voice speaks any of these languages.
