Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.ktvsuper.info/v1. You send POST requests to the /audio/speech endpoint. Use the GET /v1/voices endpoint to list available voices, languages, and formats. Authentication requires a Bearer token in the Authorization header. This endpoint structure matches the OpenAI speech endpoint standard.
How do I change the base URL for OpenAI SDK?
Update the base_url configuration in your OpenAI SDK client to https://api.ktvsuper.info/v1. Ensure you provide your unique EchoWave API key. The request shape remains identical to the OpenAI speech endpoint. This allows you to use the official SDK libraries without modifying the core request logic or payload structure.
Can I use the official OpenAI SDKs?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.ktvsuper.info/v1. Use the site's API key for authentication. The request shape matches the OpenAI speech endpoint exactly. You do not need a custom client or wrapper. Standard libraries handle the JSON payload and response parsing seamlessly.
What is the maximum text length?
The maximum input text length is 4096 characters per request. Spaces and punctuation count toward this limit. If your text exceeds this, split it into smaller parts. Generate audio for each part separately. Then join the resulting audio files to create the final output. Each request is processed individually.
How do I set the speed of the speech?
Include the speed parameter in your JSON body with a value between 0.25 and 4.0. The default speed is 1.0. Adjust this value to make the speech faster or slower. This applies to any of the eight available voices. The change affects the playback rate of the generated audio file.
Does the API support multiple languages in one request?
No, each request handles a single language context. You can optionally set the language using an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Ensure the text matches the specified language for accurate synthesis. Unsupported languages include Vietnamese, Thai, Indonesian, Ukrainian, Romanian, Czech, and Bengali.
How do I handle long texts exceeding 4096 characters?
Split your text into chunks of up to 4096 characters. Send each chunk as a separate POST request to the speech endpoint. Receive the audio file for each request. Finally, join these audio files sequentially. This ensures all text is synthesized correctly without hitting the per-request character limit.
What happens if I exceed the rate limit?
The rate limit is 60 requests per minute per key. If you exceed this, requests may wait in a queue or fail. New accounts start with a 10 requests per minute limit. Requests are processed sequentially under load. Failed requests do not incur charges, but successful ones do.
First request
curl
curl https://api.ktvsuper.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.ktvsuper.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.ktvsuper.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
To access the EchoWave API, include your secret key in the Authorization header of every request. The standard format is Bearer tts-..., ensuring your account remains secure during synthesis operations.
Keys are managed directly from your dashboard at /get-api-key/. You can generate a new key at any time; once issued, the previous key becomes invalid immediately, allowing for key rotation.
Using Bearer tokens in headers
Pass the API key as a Bearer token in the Authorization header. This method is compatible with standard HTTP clients and the OpenAI SDK, requiring only the base_url adjustment to https://api.ktvsuper.info/v1.
- Header:
Authorization: Bearer tts-YOUR_KEY_HERE - Supported by official OpenAI SDKs via
base_urloverride - Works with standard HTTP libraries (requests, axios, curl)
Generating and rotating API keys
Navigate to the dashboard to generate a new key. This action instantly invalidates the existing key, ensuring that only the current active key is valid. This is useful for revoking access from a compromised or legacy script.
- Generate new key via the dashboard interface
- Old key stops working immediately upon generation
- One active key per account policy enforced
One active key per account policy
Each account maintains a single active API key. If you need a fresh credential, issue a new one from the dashboard. The old key ceases to function immediately, preventing any concurrent usage with the previous token.
Endpoints Overview
The EchoWave API provides three primary endpoints for text-to-speech integration. The POST /v1/audio/speech endpoint handles the core synthesis task, accepting JSON payloads to generate audio files. This endpoint mirrors the OpenAI speech endpoint structure, allowing developers to use standard SDKs by simply adjusting the base URL to https://api.ktvsuper.info/v1.
POST /v1/audio/speech for generation
This endpoint accepts your text input and voice selection parameters to produce audio. It returns the audio file directly in the response, supporting formats like MP3, WAV, Opus, FLAC, and PCM. You must specify a model (tts-1 or tts-1-hd) and a voice from the available presets.
- Accepts JSON body with model, input, and voice fields.
- Returns binary audio data or error details.
- Supports up to 4096 characters per request.
GET /v1/voices for catalog listing
Use this endpoint to retrieve the full catalog of available voices, languages, and supported formats. It returns metadata for all eight voice presets, including their characteristics and available languages. This allows you to programmatically select a voice for your stream or application without hardcoding values.
- Lists all 8 voice presets with descriptions.
- Shows supported languages and audio formats.
- Provides real-time availability status.
GET /v1/models for model info
The models endpoint returns details about the available synthesis engines. It confirms the two models: tts-1 and tts-1-hd. Both models use the same underlying engine and pricing, so you can switch between them without changing your integration logic,
- Returns model ID, name, and type.
- Confirms pricing parity between models.
Request Parameters
To generate audio, you must provide the model (either tts-1 or tts-1-hd), the input text, and a voice preset. The API accepts text up to 4096 characters per request. For longer content, split the text into chunks and join the resulting audio files sequentially.
Optional parameters allow fine-tuning: response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0), and language (ISO code). While Latin script defaults to English, explicitly setting language ensures accuracy for non-English texts. Failed requests incur no charge.
Required fields: model, input, voice
The model field accepts tts-1 or tts-1-hd, both using the same engine and pricing. The input field takes your text string, while voice selects one of the eight available presets like aria or atlas.
Ensure your text does not exceed the 4096-character limit. If your script is longer, split it into multiple requests and concatenate the returned audio files to maintain continuity.
- model: "tts-1" or "tts-1-hd"
- input: string (max 4096 chars)
- voice: one of 8 presets
Optional fields: response_format, speed, language
Use response_format to specify output as mp3, wav, opus, flac, or pcm. Adjust speed between 0.25 and 4.0 to match your stream's pacing. The language field accepts ISO codes to override auto-detection.
Setting language is recommended for non-English Latin script text to prevent defaulting to English. This ensures accurate pronunciation for voices like nova or milo in specific languages.
- response_format: mp3, wav, opus, flac, pcm
- speed: 0.25 to 4.0
- language: optional ISO code
Character limit: 4096 per request
Each API call processes a maximum of 4096 characters. Spaces and punctuation count toward this limit. Exceeding this threshold will result in an error.
For extended narration, split your text into chunks of 4096 characters or less. Generate each chunk separately and join the audio files to create a seamless output.
Speed and Language Settings
Adjusting speech rate and language ensures synthetic voices match your specific content needs. The API allows precise control over playback speed and explicit language declaration to prevent mispronunciation.
Speed range: 0.25 to 4.0
You can modify the playback speed from 0.25x to 4.0x. This flexibility lets you slow down complex technical explanations or speed up short stream alerts without altering the voice character.
ISO language code specification
Provide an ISO language code to ensure accurate pronunciation. While the system supports 23 languages including Arabic, Chinese, and Hindi, explicitly setting the language is crucial for non-English texts.
- 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 for Latin script text
If you omit the language field, the API guesses the language based on the script. Latin script text defaults to English. For other languages using Latin characters, such as German or Dutch, always set the language parameter explicitly.
Audio Formats
The API supports five audio formats: MP3, WAV, Opus, FLAC, and PCM. Select the format that best matches your downstream processing needs. Each format offers different trade-offs between file size, quality, and compatibility.
MP3, WAV, Opus, FLAC, PCM options
MP3 provides efficient compression suitable for web streaming. WAV offers uncompressed, high-quality audio ideal for local editing. Opus delivers excellent quality at low bitrates, perfect for VoIP or chat applications. FLAC provides lossless compression, retaining all audio data without size bloat. PCM is raw, uncompressed data, useful for direct DSP processing.
Choosing format based on use case
For VTuber streams, MP3 or Opus minimizes bandwidth usage while maintaining clear voice quality. For indie game assets, WAV or FLAC ensures no quality loss during repeated in-game playback. Use PCM if your engine requires raw audio samples for real-time pitch shifting or effects.
- MP3: Suitable for web delivery and streaming.
- WAV: Suitable for high-fidelity local storage.
- Opus: Suitable for low-latency chat apps.
File size differences between formats
Uncompressed formats like WAV and PCM result in significantly larger files compared to lossy codecs like MP3 or Opus. FLAC offers a middle ground with lossless compression. Choose MP3 or Opus when storage or bandwidth is a constraint for your stream or game.

Rate Limits
The API enforces a standard rate limit of 60 requests per minute per key. This capacity supports steady generation for most indie development workflows.
60 requests per minute per key
Once your account is active, you can process up to 60 requests per minute. This limit applies to each API key individually, allowing you to manage concurrency based on your specific deployment needs.
10 requests per minute before first top-up
New accounts start with a reduced limit of 10 requests per minute. This threshold increases to 60 requests per minute automatically after your first top-up via USDT (TRC-20).
Handling rate limit errors
When the limit is reached, the API returns a 429 Too Many Requests error. Implement exponential backoff in your integration to handle retries gracefully without overwhelming the service.
- Check the
Retry-Afterheader for recommended wait times - Implement client-side queuing for batch processing tasks
Error Handling
Handling API errors correctly ensures smooth integration for your TTS workflows. Understanding response codes and specific error messages helps you debug issues quickly without unnecessary delays.
Common HTTP error codes
A 401 Unauthorized error indicates an invalid or expired API key. Ensure your Authorization header uses the correct Bearer token format. A 429 Too Many Requests signal means you have exceeded the rate limit of 60 requests per minute.
- 401: Invalid or missing API key
- 429: Rate limit exceeded (60 req/min)
- 500: Internal server error during synthesis
Invalid voice or model errors
Errors occur if you specify a voice not in the eight presets or a model outside 'tts-1' and 'tts-1-hd'. Verify your voice parameter against the GET /v1/voices endpoint to ensure compatibility with your selected language and format.
- Check voice names against the catalog
- Use only 'tts-1' or 'tts-1-hd' models
- Ensure voice supports the specified language
Input text too long errors
Each request accepts a maximum of 4096 characters in the input field. Exceeding this limit results in a 400 Bad Request error. Split longer texts into smaller chunks and concatenate the resulting audio files manually.
- Limit: 4096 characters per request
- Split long texts manually
- Concatenate audio files after generation
Code Examples
The API accepts standard JSON payloads, making integration straightforward for developers familiar with HTTP requests. Below are practical examples for generating speech using common tools.
These snippets demonstrate sending text to the tts-1 model with specific voice and format parameters, ensuring immediate usability in your workflow.
Basic cURL request example
Use this command to generate speech directly from your terminal. Replace YOUR_API_KEY with your actual key and adjust the voice or format as needed.
The request sends the text payload to the speech endpoint and saves the resulting audio file to output.mp3. This method is ideal for quick testing or shell scripts.
- Replace
YOUR_API_KEYwith your generated key. - Adjust
voiceto one of the 8 available presets. - Change
response_formattowav,opus,flac, orpcmif required.
Python code using OpenAI SDK
Install the official OpenAI SDK and configure the base URL to point to our API. This allows you to use familiar Python methods for TTS generation.
The code snippet initializes the client with your base URL and key, then calls the speech method with your text and desired parameters.
base_url="https://api.ktvsuper.info/v1"api_key="YOUR_API_KEY"model="tts-1"
Node.js integration example
For JavaScript environments, use the OpenAI Node.js package with the same base URL configuration. This ensures consistent behavior across your full-stack applications.
Initialize the client with your API key and base URL, then invoke the speech creation function to receive the audio buffer or file path.
baseURL: 'https://api.ktvsuper.info/v1'apiKey: 'YOUR_API_KEY'model: 'tts-1'
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Each request is processed individually; under load, requests may queue, taking a few seconds for short phrases or roughly real-time for longer texts.
23 languages
Any voice speaks any of these languages.
