Frequently asked questions
How do I get an API key?
Sign up on the /get-api-key/ page using Google or an email and password. The page displays your active API key, balance, and usage details. Each account holds one active key; issuing a new one immediately invalidates the previous one.
What is the base URL for the API?
The API base URL is https://api.vv2667.info/v1. Use this base URL for requests and configure your SDK accordingly. The speech endpoint is POST https://api.vv2667.info/v1/audio/speech.
Can I use the OpenAI SDK?
Yes. The request shape matches the OpenAI speech endpoint. Configure your OpenAI SDK by changing the base_url to https://api.vv2667.info/v1 and using your SereniSpeech key.
What voices are available?
Eight presets are available: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. These voices are based on licensed recordings from LibriTTS-R and LibriVox. Any voice can speak any of the 23 supported languages.
What audio formats are supported?
Supported formats are mp3, wav, opus, flac, and pcm. Specify the desired format using the response_format field in your request JSON body.
What is the rate limit?
The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so load may cause queuing.
What is the character limit per request?
Each request supports up to 4096 characters of input text. For longer texts, split the text into parts of this size and join the resulting audio files.
How do I specify a language?
Use the optional language field with an ISO code. If omitted, the system guesses the language from the script, defaulting Latin text to English. Set it explicitly for non-English Latin-script text.
Can I control the speech speed?
Yes. Use the speed field with a value between 0.25 and 4.0. This allows you to adjust the playback rate to suit your meditation or fitness app context.
What happens if the request fails?
Failed requests are free. If synthesis fails, the charge is returned in full. No cost is incurred for unsuccessful synthesis attempts.
Do I need to split long texts?
Yes, if your text exceeds 4096 characters. Split the text into chunks of up to 4096 characters, generate audio for each, and join the files.
How do I handle errors?
Standard HTTP error codes indicate issues. Failed synthesis returns a refund. Check the response status and handle errors according to your application logic. Use the /v1/voices endpoint to verify voices, languages, formats, and price.
Is there a WebSocket endpoint?
No. There is no WebSocket endpoint or streaming support. Audio is returned as a complete file in the response after processing.
Do I need to install a specific SDK?
No. Use the official OpenAI SDK or plain HTTP. No specific SereniSpeech SDK is required. Just configure the base URL and authorization header.
First request
curl
curl https://api.vv2667.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.vv2667.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.vv2667.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
Access the API via the /get-api-key/ dashboard to generate your credential. Each account holds one active key; new keys revoke the old one immediately, ensuring clear audit trails for your billing.
Generating Your API Key
Sign up with Google or email to receive a unique key starting with tts-. This key is tied to your account’s balance and usage limits.
Authorization Header Format
Include your key in the HTTP header: Authorization: Bearer tts-.... This standard format works with the OpenAI SDK by setting your base_url to https://api.vv2667.info/v1.
Key Rotation and Revocation
Generate a new key via the dashboard to invalidate the previous one instantly. This is useful if you suspect exposure or need to rotate credentials without losing your balance.
Making Your First Request
Generating audio requires a single HTTP POST request to the speech endpoint. The service accepts plain text and returns an audio file in your chosen format. This straightforward workflow fits easily into meditation or fitness app backends without complex infrastructure.
You can test the endpoint immediately using command line tools or your preferred HTTP client. The response contains the audio file, allowing you to play it directly or save it for later use in your application’s audio library.
cURL Example
Use the following command to generate speech. Replace YOUR_API_KEY with your key from /get-api-key/. This example uses the nova voice and requests an MP3 file.
```bash curl -X POST https://api.vv2667.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Find your calm.", "voice": "nova", "response_format": "mp3"}' \ -o speech.mp3 ```
JSON Body Structure
The request body is a JSON object containing the text and voice parameters. You can optionally specify the speed, language, and audio format. The service validates the input before processing, ensuring only supported parameters are used.
All fields are optional except input and voice, though model defaults to tts-1. The API expects standard UTF-8 encoded text. Long texts exceeding 4096 characters must be split by the client before sending.
model: "tts-1" or "tts-1-hd"input: Text string (max 4096 chars)voice: One of 8 presetsresponse_format: mp3, wav, opus, flac, or pcmspeed: 0.25–4.0language: Optional ISO code
Required Fields
The input field contains the text to be synthesized. It supports up to 4096 characters per request. Spaces and punctuation count toward this limit. If your text exceeds this, split it into smaller chunks and join the resulting audio files.
The voice field selects one of the eight presets. Each voice has a distinct tone suitable for different app contexts. For example, sage offers a calm, instructional tone ideal for guided meditation, while nova provides a bright, upbeat delivery for fitness cues.
OpenAI SDK Integration
The API follows the same request structure as the OpenAI speech endpoint, allowing you to use official SDKs by simply adjusting the base URL. Point your client to https://api.vv2667.info/v1 and use your SereniSpeech key for authentication.
Changing the Base URL
Update your SDK configuration to use https://api.vv2667.info/v1 as the base URL. This single change directs requests to our inference engine while maintaining standard field compatibility.
Using Official SDKs
You can use the official OpenAI SDKs for Python, Node.js, or other supported languages. Pass your API key via the standard Authorization: Bearer header, replacing the default OpenAI endpoint with our base URL.
- Supported languages: Python, Node.js, Java, Go, C#, Ruby, PHP, and others.
Compatibility Notes
Our endpoint accepts the same JSON body fields (model, input, voice, response_format, speed). No custom SDK is required; standard HTTP libraries work equally well. We do not offer a proprietary client library.
Available Voices and Models
The API offers eight preset voices, including warm narrators like Aria and calm instructors like Sage, all capable of speaking any of the 23 supported languages. These voices are based on licensed recordings: LibriTTS-R (CC BY 4.0), from LibriVox public-domain audiobook readings.
8 Preset Voices
Female voices include Aria (warm, clear narrator), Nova (bright, upbeat), Luna (soft, storytelling), and Sage (calm, instructional). Male options are Felix (energetic, promo), Milo (friendly, conversational), Atlas (neutral, news), and Orion (deep, documentary). Each voice supports all 23 languages without requiring specific voice models per language.
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
- Luna: Soft, storytelling
- Sage: Calm, instructional
- Felix: Energetic, promo
- Milo: Friendly, conversational
tts-1 vs tts-1-hd
The model field accepts either "tts-1" or "tts-1-hd". Both use the same underlying engine and incur identical pricing of $0.01 per 1,000 characters. The choice between them does not affect cost or voice selection, allowing developers to test both formats without financial penalty.
Voice Selection Guide
For meditation apps, Luna or Sage provide a soothing, low-energy tone suitable for guided sessions. Fitness apps may benefit from Felix’s energetic delivery or Nova’s upbeat pace. Atlas offers a neutral baseline for news-style updates, while Orion’s deep tone suits documentary-style content.
Audio Formats and Output
The API returns audio in five standard formats: mp3, wav, opus, flac, and pcm. Choose mp3 for efficient storage and broad compatibility in meditation apps, or wav for lossless quality during development. Each format is optimized for different workflow needs without compromising the synthetic speech clarity.
Opus and FLAC offer alternative compression strategies. Opus provides small file sizes suitable for mobile data, while FLAC ensures bit-perfect fidelity for archival purposes. PCM delivers raw, uncompressed audio data, useful for immediate playback in custom audio engines that handle their own compression.
Supported Formats (MP3, WAV, FLAC)
MP3 remains the most practical choice for most indie fitness and meditation apps due to its balance of quality and file size. WAV is ideal for debugging or when downstream tools require uncompressed input. FLAC preserves every detail of the generated voice without lossy compression.
All three formats support the full range of speeds from 0.25x to 4.0x. The voice characteristics remain consistent regardless of the container format selected for the final delivery.
PCM and Opus Options
PCM returns raw audio data. This is useful if your app’s audio player handles its own encoding or if you need to process the waveform directly. It results in larger files but eliminates codec overhead.
Opus is highly efficient for streaming or low-bandwidth environments. It maintains high quality at lower bitrates, making it suitable for users with limited data plans accessing your meditation content on mobile devices.
File Size Considerations
Audio duration directly correlates with text length. Since generation is roughly real-time, a 4000-character text will produce approximately 160 seconds of audio. File sizes vary significantly by format; MP3 files are typically 32-48KB per second, while WAV files are much larger.
Consider storing only the MP3 or Opus versions for end-users to conserve storage costs. Keep WAV or FLAC versions only if you need them for specific editing workflows or high-fidelity playback requirements in your app.

Handling Errors and Limits
Rate limits protect service stability during peak usage. Each API key allows 60 requests per minute once your account is active. Before your first top-up, the limit is lower at 10 requests per minute. This ensures fair access while you evaluate the engine for your meditation or fitness app.
Understanding these constraints helps you plan your audio generation workflow efficiently, especially when processing longer scripts or batch-generating voiceovers for multiple tracks.
Rate Limits (60 RPM)
You are allowed 60 requests per minute per key. If you exceed this, the API returns a 429 error. During the trial period or before your first top-up, the limit is 10 requests per minute.
Keep your key secure, as only one key is active per account. Rotate keys via your dashboard if needed.
- Limit: 60 requests/minute (active keys)
Character Limit per Request
Each request accepts up to 4096 characters of text. This includes spaces and punctuation. For longer scripts, split the text into parts and join the resulting audio files.
This limit applies per API call, not per session. Plan your splitting logic in your app to maintain audio continuity.
Common Error Codes
401 Unauthorized: Invalid or expired API key. Check your credentials.
429 Too Many Requests: You have exceeded the rate limit. Wait and retry.
500 Server Error: Temporary issue. Retry with exponential backoff. Failed requests are free.
Failed requests are free, so you can retry without losing credits.
Language Detection and Specification
The API automatically infers language from the input script, defaulting to English for Latin characters. This simplifies initial integration for English-first apps, but relies on script recognition rather than semantic context. If the detection fails, the voice may apply wrong prosody or pronunciation rules.
For precise control, you can explicitly specify the ISO language code in the request. This ensures consistent output regardless of script variations. The API supports 23 languages, allowing any voice to speak any supported language fluently.
Automatic Language Guessing
The system analyzes the input text’s character set to determine the language. Latin script defaults to English unless overridden. This works well for standard texts but may misinterpret mixed-script inputs.
If the detected language is incorrect, the voice may apply wrong prosody or pronunciation rules. Review the output to ensure the tone matches your meditation or fitness app’s style.
- Defaults to English for Latin text
- Based on script analysis, not semantics
Explicit Language Codes
Pass the language field (e.g., "fr", "de", "ja") to force a specific language. This overrides automatic detection and ensures consistent behavior across different input variations.
Use explicit codes when your app supports multiple languages or when the input text contains mixed scripts. This is recommended for non-English Latin scripts like German or Spanish.
- Supports ISO 639-1 codes
- Overrides automatic detection
Non-English Latin Scripts
For languages like German, Spanish, or Italian, explicitly setting the language field is crucial. Without it, the API defaults to English, resulting in an accented or incorrect pronunciation.
The API supports 23 languages. Ensure you set the correct code to avoid unnatural speech patterns in your app’s narration.
- German, Spanish, Italian, etc. require explicit codes
- Prevents default English pronunciation errors
Splitting Long Texts
The API accepts up to 4096 characters per request. For longer meditation scripts or fitness instructions, you must split the text into chunks of this size and send them sequentially.
Each chunk returns a separate audio file. Your client code should concatenate these files in order to create a single continuous track for the user.
4096 Character Limit
Send text no longer than 4096 characters. Exceeding this limit causes the request to fail. For a 10-minute meditation, you might need 5-10 sequential requests.
- Count spaces and punctuation as characters.
- Process requests sequentially to maintain narrative order.
Joining Audio Files
Receive individual audio files for each chunk. Merge them in your app to ensure seamless playback without gaps.
Streaming Alternatives
We do not offer real-time WebSocket streaming. You must wait for each chunk to complete before starting the next synthesis.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Developers can predict expenses based on character count, making financial planning straightforward for both small and growing apps.
23 languages
Any voice speaks any of these languages.
