API Documentation for Voice Over Generation

By SyncVoice editorial team · Updated 2026-11-18

This documentation provides the technical specifications for the SyncVoice API, designed for localization agencies processing high volumes of video voice-overs. It details the integration of our text-to-speech engine into your existing production pipelines, covering authentication, endpoint structures, and response formats. The guide assumes familiarity with standard HTTP methods and JSON payloads, ensuring your engineering team can implement programmatic audio generation at scale without manual intervention.

The API accepts text input and returns synthesized audio files via a POST request to https://api.playbd2.com/v1/audio/speech. It supports eight distinct voice presets across 23 languages, allowing you to maintain consistent audio quality across diverse dubbing projects. By replacing manual recording workflows with this reliable API, your team can generate audio assets programmatically, ensuring consistency and speed for large-scale localization efforts.

API Documentation for Voice Over Generation

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.mp3

Python (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
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

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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

Rate Limits and Throttling

Code Examples

Sound wave illustration for: 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_url to https://api.playbd2.com/v1
  • Pass Authorization: Bearer tts-... header
  • Use standard openai or requests libraries

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, and response_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 fetch or axios
  • Set base_url to https://api.playbd2.com/v1
  • Handle binary audio response data

Handling Long Texts

Sound wave illustration for: 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

Sound wave illustration for: 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.

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. IETF RFC 7845: Ogg Opus
  3. Creative Commons Attribution 4.0
  4. ISO 639 language codes
  5. Tether (USDT)
  6. openai-python on GitHub
  7. Node.js documentation
  8. openai-node on GitHub
  9. OpenAI API reference: create speech
  10. TRON developer hub: TRC-20
  11. curl documentation
  12. LibriTTS-R paper (arXiv 2305.18802)

More on this site