Text-to-Speech API Documentation: Quickstart, Curl, and SDKs

By Dubbing Voice Metrics editorial team · Updated 2026-11-19

This documentation provides a precise technical reference for integrating the Dubbing Voice Metrics TTS API into your localization and dubbing workflows. You will find exact specifications for the speech synthesis endpoint, including required JSON structures, supported voice presets, and valid response formats like MP3, WAV, Opus, FLAC, and PCM. The guide details how to handle request parameters such as model selection, input text limits, and language codes to ensure accurate audio generation for your global content projects.

Designed for engineering teams and technical decision-makers, this page also covers authentication mechanics, OpenAI SDK compatibility, and rate limit behaviors. You will learn how to generate API keys, manage token rotation, and interpret error codes. The documentation includes ready-to-use cURL examples and SDK integration patterns, enabling you to quickly prototype and deploy synthetic voice solutions that meet your quality and cost standards.

Text-to-Speech API Documentation: Quickstart, Curl, and SDKs

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

Python (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
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 and API Keys

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

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

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

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

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

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

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

OpenAI SDK Integration

Error Handling and Status Codes

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

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

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

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. LibriTTS-R paper (arXiv 2305.18802)
  3. Python documentation
  4. Tether (USDT)
  5. W3C WAI: making audio and video accessible
  6. TRON developer hub: TRC-20
  7. FFmpeg documentation
  8. Creative Commons Attribution 4.0
  9. curl documentation
  10. LibriTTS-R corpus (OpenSLR 141)
  11. openai-node on GitHub
  12. MDN: Web Speech API

More on this site