Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or email plus password. Accounts are per site. The dashboard displays your active key, balance, and usage statistics immediately after creation.
What is the base URL for the API?
The API base URL is https://api.vs55.info/v1. Use this endpoint for all requests, including the speech generation POST endpoint and the voices GET endpoint.
Does the API support OpenAI SDK?
Yes. The request shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.vs55.info/v1 and providing your site-specific key.
What models are available?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing structure, allowing you to choose based on quality preferences without cost variation.
What is the character limit per request?
Each request supports up to 4096 characters in the input field. For longer texts, split the content into parts of this size and join the resulting audio files.
How do I set the language?
Pass the optional language parameter with an ISO code. If omitted, the system guesses from the script, defaulting to English for Latin text. Set it explicitly for non-English Latin scripts.
What response formats are supported?
Supported formats include mp3, wav, opus, flac, and pcm. Select the appropriate format via the response_format field in your JSON request body.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key (10 before the first top-up). Requests are processed sequentially, so excess requests may wait in a queue until capacity is available.
How long are requests queued?
Requests are processed one after another. Under load, a request may wait in a queue. Typical speed is roughly real-time, but short phrases take a few seconds to generate.
Is SSML supported in the request?
No. The API does not support SSML.
Can I stream the audio response?
No. There is no streaming or WebSocket support. The API returns the complete audio file in the response after synthesis is finished.
How do I handle failed requests?
Failed requests are free. If synthesis fails, the charge is returned in full. No additional cost is incurred for unsuccessful synthesis attempts.
What is the authorization header format?
Use the header: Authorization: Bearer tts-... where ... is your active API key. One key is active per account, and it authenticates all requests.
Can I change my API key?
Yes. A new key can be issued at any time. When a new key is issued, the old one stops working immediately.
First request
curl
curl https://api.vs55.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.vs55.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.vs55.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 API Keys
Authentication for the Text-to-Speech API relies on a single active API key per account, issued upon registration via Google or email. This key authorizes all requests to the API endpoints, ensuring secure access to speech synthesis services for localization workflows.
Generating Your API Key
Keys are generated on the /get-api-key/ dashboard after account creation. The interface displays the active key, current balance, and usage statistics, providing immediate access to your credentials for integration into your dubbing pipeline.
Bearer Token Format
Include the key in the HTTP header as Authorization: Bearer tts-.... Ensure no extra whitespace surrounds the token string to avoid authentication errors during request processing.
- Format:
Authorization: Bearer tts-[your_key] - Single active key per account
- Keys are case-sensitive
Key Rotation Policy
You can issue a new key at any time via the dashboard. Upon generation, the previous key becomes invalid immediately, ensuring tight control over access without waiting for expiration periods.
Endpoint Overview
The API exposes three core endpoints for synthesis, discovery, and configuration. All requests target the base URL https://api.vs55.info/v1 using standard HTTP methods. Authentication requires a Bearer token in the Authorization header.
Speech Synthesis Endpoint
POST /v1/audio/speech accepts text and returns an audio file. The request body mirrors the OpenAI speech endpoint structure, allowing immediate use of existing SDKs by simply updating the base URL.
- Endpoint: POST /v1/audio/speech
- Input: JSON body with model, input, voice, and format
Voices Listing Endpoint
GET /v1/voices returns available voices, supported languages, and pricing details. This endpoint helps agencies verify that specific voice models support the required localization languages before committing to synthesis.
- Endpoint: GET /v1/voices
- Returns: Voice ID, name, language support, and format options
Models Endpoint
GET /v1/models lists available model variants, such as tts-1 and tts-1-hd. Both models use the same engine and have identical pricing.
- Endpoint: GET /v1/models
- Returns: Model ID, name, and associated pricing tier
Request Parameters
The API accepts JSON bodies containing the text to synthesize. You must specify the model, input text, voice, and response format. The system supports two models for different quality tiers, both using the same underlying engine.
Model Selection (tts-1, tts-1-hd)
Choose between tts-1 and tts-1-hd. Both models use the same engine and have identical pricing, so selection depends only on your preferred audio characteristics rather than cost differences.
Input Text Limits
Each request supports up to 4096 characters. Longer texts must be split into parts and the resulting audio files joined. Spaces and punctuation count toward the character limit.
Voice and Language Selection
Select one of eight voice presets and an optional ISO language code. If the language is omitted, the system guesses it from the script, defaulting to English for Latin text.
- Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Response Formats
The API supports five distinct audio formats, allowing localization teams to choose the optimal balance between file size and fidelity for their dubbing pipeline. Each format is returned directly in the response body, ready for immediate playback or storage.
MP3 Output Format
MP3 is the default and most widely supported format. It offers excellent compression for web delivery and standard audio players, making it ideal for general-purpose dubbing and quick review cycles.
WAV and FLAC Options
WAV provides uncompressed audio. FLAC offers lossless compression, reducing storage costs while preserving all audio details required for high-end localization masters.
Opus and PCM Support
Opus is a supported response format. PCM provides raw, uncompressed audio data, useful for direct integration into systems requiring specific sample rate inputs without decoding overhead.
OpenAI SDK Integration
The Dubbing Voice Metrics API mirrors the OpenAI speech endpoint structure, allowing agencies to reuse existing codebases with minimal friction. By adjusting the base URL, teams can integrate our TTS engine directly into localization pipelines without rewriting request logic or audio handling routines.
Base URL Configuration
Point your OpenAI SDK client to https://api.vs55.info/v1 instead of the default OpenAI endpoint. Ensure your API key is passed via the standard Authorization: Bearer header to authenticate requests for speech synthesis.
SDK Compatibility
The official OpenAI Python and Node.js SDKs work seamlessly by overriding the base URL. This compatibility ensures that standard request shapes for text input, voice selection, and format settings are processed correctly by our infrastructure.
Code Example Snippets
Initialize the client with base_url="https://api.vs55.info/v1" and your unique key. Send a POST request to /v1/audio/speech with your model, input, voice, and response_format parameters to receive the audio file.

Error Handling and Status Codes
The API returns standard HTTP status codes to indicate request success or failure. A 200 OK response includes the audio binary in the body. Non-success codes provide a JSON error object with a machine-readable code and a human-readable message explaining the issue.
Common HTTP Error Codes
Use 400 for malformed JSON or missing required fields. Use 401 when the Bearer token is invalid or expired. Use 402 if your account balance is insufficient for the character count. Use 429 for rate limit exhaustion. Use 500 for internal server errors during synthesis.
- 400 Bad Request
- 401 Unauthorized
- 402 Payment Required
- 429 Too Many Requests
- 500 Internal Server Error
Rate Limit Errors
You receive a 429 status when exceeding 60 requests per minute per key. New accounts without top-ups are limited to 10 requests per minute. The response includes a Retry-After header indicating seconds to wait before retrying.
- 60 requests/minute after top-up
- 10 requests/minute pre-top-up
- Retry-After header included
Invalid Parameter Responses
Invalid voices or models return a 400 error. Text exceeding 4096 characters triggers a 400 error. Unsupported response formats or out-of-range speeds also return 400. The error message specifies which parameter failed validation.
- Invalid voice ID
- Input exceeds 4096 characters
- Unsupported response format
Rate Limits and Throttling
The API enforces a strict limit of 60 requests per minute per active key. This cap applies uniformly regardless of the model chosen, ensuring predictable throughput for your localization pipelines. Long texts must be split into segments under 4,096 characters to stay within these bounds efficiently.
Requests Per Minute Limit
Each API key allows a maximum of 60 synthesis requests per minute. This limit is consistent across both tts-1 and tts-1-hd models. Exceeding this threshold triggers a 429 Too Many Requests error, requiring your integration to implement exponential backoff or request queuing.
- Limit: 60 requests per minute per key
- Applies to both tts-1 and tts-1-hd
- Exceeded limits return HTTP 429
Pre-Topup Rate Restriction
New accounts without an active top-up are restricted to 10 requests per minute. This lower tier persists until your USDT (TRC-20) transfer is confirmed and credited. Once funded, your limit increases automatically to the standard 60 requests per minute.
Queue Behavior Under Load
Requests are processed sequentially. If multiple requests arrive simultaneously, they are queued and handled one after another. Generation takes roughly one second per 25 characters of text on long texts; short phrases take a few seconds. Under heavy load, queue wait times increase, so plan your batch jobs accordingly to avoid timeouts.
Curl Example for First Request
This curl command demonstrates the standard request shape for synthesizing speech. It sends a POST request to the API endpoint with a JSON body containing the model, voice, input text, and response format.
Replace tts-... with your actual API key. The command outputs the audio file directly to a local file named output.mp3.
Basic Curl Command
Use the following command to generate audio. Ensure your text is URL-safe or properly encoded within the JSON body.
The command assumes curl is installed and accessible in your terminal environment.
curl -X POST https://api.vs55.info/v1/audio/speech-H "Authorization: Bearer tts-..."-H "Content-Type: application/json"- `-d '{"model": "tts-1", "voice": "nova", "input": "Hello world", "response_format": "mp3"}'`
-o output.mp3
Headers Configuration
The Authorization header must contain your Bearer token. The Content-Type must be set to application/json to ensure proper parsing of the request body.
Incorrect headers will result in a 401 or 400 error response.
Response Parsing
A successful response returns the audio file directly in the response body with the specified Content-Type (e.g., audio/mpeg).
If the request fails, the response will contain a JSON object with an error field detailing the issue, such as invalid input or rate limits.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Split logic should respect word boundaries to avoid cutting mid-sentence.
23 languages
Any voice speaks any of these languages.
