Frequently asked questions
Do I need to install a specific SDK?
No proprietary SDK is required. You can use standard HTTP libraries or the official OpenAI SDK by changing the base_url to https://api.bbokk.info/v1. This allows you to use existing client code with your API key for seamless integration into your localization pipeline without additional dependencies.
Can I use the API with Python or Node.js?
Yes. Since the endpoint matches the OpenAI speech endpoint shape, you can use the official OpenAI SDKs for Python or Node.js. Simply configure the base_url to https://api.bbokk.info/v1 and provide your Bearer token. This enables direct integration using familiar libraries and standard HTTP clients.
How do I handle long texts exceeding 4096 characters?
Split your input text into chunks of up to 4096 characters each. Send each chunk as a separate POST request to the /v1/audio/speech endpoint. Once all requests complete, join the returned audio files sequentially. This ensures compliance with the per-request character limit while delivering complete audio assets.
What is the default language if none is specified?
If the language parameter is omitted, the system guesses the language from the script. For Latin-script text, English is the default. For non-English Latin-script text, you should explicitly set the language field to ensure accurate synthesis. Supported languages include Hindi, English, and 21 others.
Can I stream audio as it generates?
No, streaming is not supported. The API returns the complete audio file in the response after synthesis finishes. Requests are processed sequentially, so longer texts may experience queue delays. You receive the full file once generation is complete, rather than partial audio chunks during processing.
Is there an SSML tag support documented?
No SSML support is available. The API accepts plain text input only. There are no SSML tags, phoneme dictionaries, or custom pronunciation lexicons documented. You cannot control pacing or pronunciation via markup. For precise control, adjust the speed parameter or split text into separate requests.
How do I rotate API keys without downtime?
Issue a new API key from your account dashboard. The old key stops working immediately upon issuance of the new one. Update your application configuration to use the new key. This ensures seamless rotation without downtime, as only one active key exists per account at any time.
What is the maximum file size for a response?
The response size depends on the input text length and selected format. However, each request is limited to 4096 characters of input text. For longer texts, split the input and join the resulting audio files to manage size effectively.
First request
curl
curl https://api.bbokk.info/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.bbokk.info/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.bbokk.info/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 and Keys
To begin using the DubScript API, you must first obtain an authentication key. Navigate to the /get-api-key/ page on bbokk.info to generate your credential. You can sign up using Google or create an account with an email and password. The dashboard will immediately display your unique key along with your current balance and usage statistics.
Generate key via /get-api-key/ page
Access the /get-api-key/ page to create your account and retrieve your API key. Sign up via Google for immediate trial credit, or use email/password for standard access. The dashboard provides your key, current balance, and a ready-to-use cURL example for quick integration testing.
- Sign up via Google or email/password
- View key, balance, and usage stats
- Access ready cURL examples
Use Bearer token in Authorization header
Include your API key in the Authorization header of every request using the Bearer scheme. The format is Authorization: Bearer tts-.... This ensures secure authentication for your text-to-speech synthesis requests. Without this header, requests will be rejected with a 401 status code.
One active key per account; replace old key instantly
Each account holds only one active key at a time. Generating a new key immediately invalidates the previous one, ensuring tight security control. This is useful for rotating credentials or recovering from a potential leak without needing multiple simultaneous active keys.
Endpoints Overview
The DubScript API exposes three primary endpoints to manage your localization workflow. The core generation endpoint accepts text and configuration parameters to produce audio files. Two additional endpoints provide metadata about available voices and model specifications, allowing your integration to dynamically adapt to available assets without hardcoding values.
POST /v1/audio/speech for generation
This endpoint is the main engine for creating audio assets. Send a JSON body containing the text input, selected voice preset, and desired output format. The API processes the request and returns the synthesized audio file, which can be saved directly to your storage.
- Accepts text up to 4096 characters per request
GET /v1/voices for list of available presets
Use this endpoint to retrieve the current list of eight voice presets and their associated metadata. This allows your application to present users with a dynamic list of available narrators, including details on language support and voice characteristics, ensuring accurate selection for specific localization projects.
- Returns voice ID, name, and gender
GET /v1/models for model details
Query this endpoint to retrieve information about the underlying TTS models. This includes details on model capabilities and pricing tiers, helping you optimize your infrastructure costs by choosing between standard and high-definition models based on your project's audio quality requirements.
Request Parameters
The input field accepts plain text strings up to 4096 characters per request. Spaces and punctuation count toward this limit, so longer scripts must be split and joined by the client. Each segment generates independently, allowing precise control over audio segmentation for long-form localization projects.
input: text up to 4096 characters
Send your source text in the input field. The API processes up to 4096 characters per call. If your script exceeds this length, divide it into chunks and concatenate the resulting audio files on the client side.
- Maximum 4096 characters per request
- Spaces and punctuation count as characters
- Plain text only; no SSML support
voice: select from 8 available presets
Choose one of eight licensed voice presets to match your brand tone. Voices like aria offer a warm narrator style, while felix provides an energetic promo sound. All voices support Hindi and the other 22 available languages.
- 8 distinct voice presets
- Supports Hindi and 22 other languages
- Based on licensed LibriTTS-R recordings
response_format: mp3, wav, opus, flac, or pcm
Specify the desired audio format using the response_format parameter. Options include mp3, wav, opus, flac, and pcm. The choice depends on your downstream processing pipeline, balancing file size against quality requirements for your dubbing workflow.
- Supported formats: mp3, wav, opus, flac, pcm
- Default format is mp3
- Audio files include an inaudible synthetic watermark
Speed and Language Settings
Adjust the playback speed between 0.25 and 4.0 to match your dubbing style. Lower speeds clarify dense narration, while higher speeds suit quick voice-overs. This parameter accepts decimal values for precise timing control during localization.
Speed range: 0.25 to 4.0
Set the speed field in your request to control voice pacing. Values outside this range will be rejected. This allows consistent audio length across different language versions of the same script.
Optional language ISO code for disambiguation
Send the language parameter with an ISO code (e.g., "hi" for Hindi) to ensure accurate pronunciation. While the engine guesses the language, explicit codes prevent errors with mixed-script text or ambiguous names.
Auto-detection defaults to English for Latin script
If you omit the language field, the system infers the language from the script. For Latin-script text that is not English, always specify the language to avoid defaulting to English pronunciation.
OpenAI SDK Compatibility
Leverage your existing infrastructure by using the official OpenAI SDKs, which require only a minor configuration adjustment. By pointing the client’s base_url to https://api.bbokk.info/v1, you can utilize familiar libraries without rewriting integration logic. This approach ensures your development team can integrate our TTS capabilities using standard, well-documented tools they already know.
Use official OpenAI SDKs
Our API maintains compatibility with the official OpenAI SDKs across multiple languages. This means you can continue using the same client libraries for HTTP requests, ensuring consistent behavior and reducing the learning curve for your developers. No proprietary wrappers or custom HTTP clients are necessary to send your audio synthesis requests.
Change base_url to https://api.bbokk.info/v1
To connect, update your SDK configuration to use https://api.bbokk.info/v1 as the base URL. This simple change directs all API calls to our processing endpoints while maintaining the standard request structure. Your existing API key, prefixed with tts-, will authenticate these requests seamlessly against our service.
Use same request shape as OpenAI speech endpoint
The JSON body structure for POST /v1/audio/speech mirrors the OpenAI speech endpoint exactly. You send parameters like model, input, voice, and response_format in the same format. This parity allows for easy swapping between providers if needed, ensuring your code remains portable and your integration process remains straightforward.

Rate Limits and Quotas
Your API key enforces a strict rate limit of 60 requests per minute. This quota applies collectively to all endpoints associated with that key. If you need higher throughput, you can issue a new key at any time; the old key stops instantly, allowing you to run parallel processes with separate keys.
60 requests per minute per key
The standard limit is 60 requests per minute for active accounts. This ensures fair usage and stable processing for high-volume dubbing workflows. Each key operates independently, so scaling requires additional keys rather than waiting for the current queue to clear.
10 requests per minute before first top-up
New accounts without a top-up are restricted to 10 requests per minute. This lower limit helps verify integration stability before you commit to production volume. Once you add USDT (TRC-20), your limit increases to the full 60 requests per minute immediately.
Requests processed sequentially under load
Requests are processed one after another. Under heavy load, a request may wait in a queue before synthesis begins. For long texts split into multiple parts, ensure your client code handles the sequential nature to avoid overwhelming the endpoint.
- Synthesis takes roughly real-time speed (25 chars/sec) for long texts.
- Short phrases may take a few seconds to generate.
- Failed requests do not consume your character balance.
Error Handling
When synthesis fails, the charge is returned in full, ensuring you only pay for successful audio generation. This applies to transient errors or service interruptions where the audio file is not delivered. You are not penalized for requests that do not complete successfully, maintaining transparent billing for high-volume dubbing workflows.
Always inspect the HTTP status code in the response header to determine the nature of the issue. The API uses standard HTTP conventions to indicate success, client-side mistakes, or server-side problems, allowing your automation scripts to route failures correctly without manual intervention.
Failed requests are free of charge
If the synthesis process fails for any reason, the character count is not deducted from your balance. The API returns the full credit for that specific request, so you can retry or adjust parameters without financial loss.
This policy applies to both transient network issues and internal processing errors. Since requests are processed sequentially, a temporary queue delay that results in a timeout is also considered a failed request eligible for a full refund.
Check response status codes for issues
A 200 OK status indicates the audio file is included in the response body. Any other code signals that the audio data is not available or the request requires attention.
Use the status code to trigger appropriate retry logic in your application. For example, a 429 Too Many Requests indicates you have hit the rate limit of 60 requests per minute.
- 200 OK: Audio generated successfully
- 400 Bad Request: Invalid parameters or malformed JSON
- 401 Unauthorized: Invalid or expired API key
- 429 Too Many Requests: Rate limit exceeded
Handle 4xx and 5xx errors appropriately
Client errors (4xx) typically indicate incorrect input, such as an invalid voice ID or text exceeding 4096 characters. Review your request body to ensure all fields match the required schema before retrying.
Server errors (5xx) are rare but may occur during peak load. Implement exponential backoff for 5xx errors to avoid overwhelming the service. Since requests are processed one after another, under heavy load, temporary 503 Service Unavailable responses may occur while the queue clears.
- 400: Verify input text length and voice ID
- 401: Refresh API key via dashboard
- 429: Wait and retry after rate limit window
- 503: Implement exponential backoff for retries
Example Requests
The API enables seamless Hindi voice-over integration for localization projects. Developers can generate audio files by sending text payloads to the speech endpoint, ensuring consistent quality across multilingual assets.
This section provides concrete implementation details for integrating the DubScript API into existing workflows, covering request structures, response handling, and practical code examples for rapid deployment.
Ready curl example provided on dashboard
The /get-api-key/ dashboard displays a ready-to-use curl command tailored to your specific key. This allows immediate testing of the API without manual configuration of headers or endpoints.
You can copy this example directly into your terminal to verify connectivity and generate your first audio file instantly.
JSON body structure for POST requests
Send a POST request to https://api.bbokk.info/v1/audio/speech with a JSON body. Required fields include model ("tts-1" or "tts-1-hd"), input (text up to 4096 characters), voice (e.g., "nova" for Hindi), and response_format.
Optional parameters include speed (0.25–4.0) and language (ISO code like "hi") to ensure accurate pronunciation when auto-detection might default incorrectly.
- model: "tts-1" or "tts-1-hd"
- input: String, max 4096 characters
- voice: One of 8 presets (e.g., "nova", "aria")
- response_format: mp3, wav, opus, flac, or pcm
- speed: Float, 0.25 to 4.0
- language: Optional ISO code (e.g., "hi")
Handling audio response in client code
The API returns the audio file directly in the response body as binary data. Your client code should handle this stream or buffer according to the specified response_format.
For example, in Python, you can write the response content directly to a file. Ensure you handle potential 4xx or 5xx errors, noting that failed requests incur no charge.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. The gender balance allows for multi-character dialogue generation without relying on third-party voice cloning services.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriTTS-R corpus (OpenSLR 141)
- ISO 639 language codes
- TRON developer hub: TRC-20
- openai-node on GitHub
- LibriTTS-R paper (arXiv 2305.18802)
- Node.js documentation
- Python documentation
- W3C WAI: making audio and video accessible
- Creative Commons Attribution 4.0
- Tether (USDT)
- OpenAI API reference: create speech
