API Documentation for Text-to-Speech Integration

By EchoWave editorial team · Updated 2026-11-19

This documentation provides a practical guide for indie developers and streamers integrating EchoWave’s text-to-speech API. It details the request structure for generating synthetic audio files, covering essential parameters like voice selection, speed adjustments, and language codes. You will find concrete examples for cURL and the OpenAI SDK, enabling immediate implementation in your VTuber or streaming workflows without unnecessary abstraction layers.

The guide explains authentication via Bearer tokens, rate limits of 60 requests per minute, and supported audio formats including MP3, WAV, and Opus. It clarifies that the API accepts standard JSON bodies compatible with OpenAI SDKs, allowing you to swap the base URL for integration. This resource focuses on the technical specifics of character voice generation, ensuring you understand latency expectations and character limits before deployment.

API Documentation for Text-to-Speech Integration

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

Python (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
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

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

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_url override
  • Works with standard HTTP libraries (requests, axios, curl)

Generating and rotating API keys

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

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

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

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

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

Audio Formats

Rate Limits

Sound wave illustration for: 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-After header for recommended wait times
  • Implement client-side queuing for batch processing tasks

Error Handling

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

Sound wave illustration for: 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_KEY with your generated key.
  • Adjust voice to one of the 8 available presets.
  • Change response_format to wav, opus, flac, or pcm if 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.

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. Python documentation
  3. Creative Commons Attribution 4.0
  4. W3C WAI: making audio and video accessible
  5. LibriTTS-R corpus (OpenSLR 141)
  6. MDN: Web Speech API
  7. Node.js documentation
  8. OpenAI API reference: create speech
  9. TRON developer hub: TRC-20
  10. curl documentation
  11. IETF RFC 7845: Ogg Opus
  12. ISO 639 language codes

More on this site