Cloud Text-to-Speech API: Integration Guide for Developers

By EchoVocal editorial team · Updated 2026-11-18

This guide provides the technical specifications for integrating EchoVocal’s cloud text-to-speech API into your VTuber and streamer workflows. You will find precise details on authentication, request structures, and rate limits to ensure reliable audio generation for your indie projects. The documentation is designed for developers who need to deliver broadcast-ready synthetic voices that respect creator rights without requiring complex infrastructure.

We cover essential endpoints, including voice selection and language support, along with code examples for both cURL and the OpenAI SDK. Whether you are building a pre-recorded content pipeline or generating pre-recorded content, these specs help you choose the right preset voices and formats. Read on to understand character limits, error handling, and how to rotate your API keys effectively.

Cloud Text-to-Speech API: Integration Guide for Developers

Frequently asked questions

How do I get an API key?

Sign up at https://playabcd1234.com/get-api-key/ using Google or email. Google sign-ins receive a $0.50 trial credit valid for 7 days. Email accounts start without trial credit. Your active key is displayed on the dashboard alongside balance and usage statistics.

What is the base URL?

The API base URL is https://api.playabcd1234.com/v1. Use this for all requests, including the speech endpoint at /v1/audio/speech. You can also fetch available voices and models via GET /v1/voices and GET /v1/models respectively.

Does it work with OpenAI SDK?

Yes. The request shape matches the OpenAI speech endpoint. Configure your OpenAI SDK by changing the base_url to https://api.playabcd1234.com/v1 and providing your EchoVocal API key. This allows you to use official OpenAI SDKs seamlessly.

What formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. Specify the desired format using the response_format field in your request body. This allows you to choose the best audio quality or file size for your specific VTuber or streaming workflow.

What is the character limit?

Each request supports up to 4096 characters of input text. For longer texts, split them into parts of this limit and join the resulting audio files. Spaces and punctuation count toward the character total used for billing and limits.

What are the rate limits?

You are limited to 60 requests per minute per API key. Before your first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so high load may cause queuing delays during synthesis.

How do I rotate my API key?

Issue a new key at any time via your account dashboard. The new key becomes active immediately, and the previous key stops working at once. This allows you to revoke access to old keys instantly without downtime.

What happens on error?

If synthesis fails, the charge is returned in full. Failed requests are free, ensuring you only pay for successfully generated audio. Check your dashboard for usage details and status logs to troubleshoot any issues with your requests.

First request

curl

curl https://api.playabcd1234.com/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.playabcd1234.com/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.playabcd1234.com/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

Authentication is managed via a single active API key issued to your account. This key authorizes all requests to the EchoVocal TTS engine and must be included in every call.

API key format

API key format

Your API key is a string starting with the prefix tts-. It is displayed on your dashboard after signing in with Google or creating an email account.

  • Format: tts-...
  • One active key per account

Bearer token usage

Bearer token usage

Include the key in the HTTP header as a Bearer token. This ensures the API identifies your account and applies your specific rate limits and balance.

  • Header: Authorization: Bearer tts-...

Key rotation

Issue a new key from the dashboard at any time. The old key stops working immediately, ensuring secure access management without downtime for existing integrations.

Endpoint: /v1/audio/speech

Sound wave illustration for: Endpoint: /v1/audio/speech

Send a POST request to https://api.playabcd1234.com/v1/audio/speech with your bearer token. The endpoint accepts JSON to generate audio from text, returning the file directly in the response body for immediate playback or download by your stream overlay or VOD editor.

POST request structure

The request body must be valid JSON containing the synthesis parameters. The API processes the text synchronously, returning the audio file once generation completes or fails.

Required fields

You must provide the model (either tts-1 or tts-1-hd), the input text (up to 4096 characters), and the voice preset ID. These three fields are mandatory for every synthesis job.

Optional parameters

Include response_format (mp3, wav, opus, flac, pcm) to specify output type. Use speed (0.25–4.0) to adjust playback rate. The language parameter accepts an ISO code to guide synthesis; otherwise, the system guesses from the script.

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts two model variants, tts-1 and tts-1-hd, which utilize the same underlying engine and pricing structure. Developers can switch between them without changing their integration logic, allowing for quick A/B testing of output quality against the fixed rate of $10 per 1 million characters.

Text input is capped at 4,096 characters per request. For longer scripts, split the text into chunks and join the resulting audio files. Short phrases typically take a few seconds to generate, while longer texts process at roughly real-time speed (25 characters per second).

Model selection (tts-1, tts-1-hd)

Both tts-1 and tts-1-hd use the same engine and price. You can swap them in the model field without altering your request structure, enabling easy quality comparisons for VTuber assets.

Pricing remains identical at $10 per 1 million characters. This uniformity simplifies cost forecasting for streaming pipelines where audio length directly correlates with budget.

  • Use tts-1 for standard latency needs.
  • Choose tts-1-hd for higher fidelity requirements.
  • Both models share the same pricing tier.

Input text limits (4096 chars)

Each POST request supports a maximum of 4,096 characters for the input field. Spaces and punctuation count toward this limit. Exceeding this requires client-side splitting logic before sending the payload.

Processing is sequential; under load, requests may queue. Typical generation speed matches real-time playback, approximately 25 characters per second. Plan your burst limits accordingly to avoid latency spikes during live streams.

  • Max input: 4096 characters.
  • Spaces and punctuation count.
  • Sequential processing applies.

Voice presets

Select from eight licensed presets based on recordings from LibriTTS-R (CC BY 4.0). Each voice is designed for specific broadcast contexts, from warm narration to energetic promo. All voices support all 23 listed languages.

Set the voice parameter to one of the eight options: aria, nova, luna, sage, felix, milo, atlas, or orion. The language field is optional but recommended for non-English Latin script text to ensure accurate pronunciation.

  • 8 presets available.
  • All voices support 23 languages.
  • Based on LibriTTS-R CC BY 4.0.

Response Formats

Sound wave illustration for: Response Formats

The API returns generated audio directly in the response body, allowing seamless integration into VTuber streaming pipelines or VOD processing workflows. Choose from mp3, wav, opus, flac, or pcm based on your latency and quality needs. Each file carries an inaudible watermark to identify synthetic speech.

For quick prototyping, pcm provides raw data, while opus offers efficient compression for live streams. WAV is ideal for lossless archival, and mp3 remains the standard for broad compatibility. Select the format that best balances bandwidth and audio fidelity for your specific broadcast requirements.

Supported formats: mp3, wav, opus, flac, pcm

Specify your preferred format in the response_format field. The service supports mp3, wav, opus, flac, and pcm. This flexibility allows you to optimize for either file size or audio quality depending on whether you are generating content for immediate playback or long-term storage.

  • mp3: Compact, widely supported
  • wav: Uncompressed, lossless
  • opus: High efficiency for streaming
  • flac: Lossless compression
  • pcm: Raw audio data

Audio file delivery

Audio files are delivered directly in the HTTP response body. For texts exceeding 4096 characters, the API splits the input, generates segments, and joins them into a single audio file. You receive one continuous output file containing the complete synthesis result.

Generated audio is not stored on our servers; it is returned immediately in the response. This ensures privacy and reduces latency, which is critical for real-time VTuber voice triggering or dynamic VOD generation workflows.

Error responses

If synthesis fails, you receive a JSON error object with a status code and message. Failed requests are free, and the charge is returned in full. Check the response body for details on why the request failed, such as invalid parameters or rate limits.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Configure the OpenAI SDK’s base_url to https://api.playabcd1234.com/v1 and provide your tts-... API key. This redirects requests to EchoVocal’s engine while keeping the standard SDK interface intact.

Base URL configuration

Set base_url to https://api.playabcd1234.com/v1 in your OpenAI SDK client initialization. Pass your unique tts-... key via the Authorization header. This ensures all SDK calls route directly to our speech endpoint without modifying the core request structure.

SDK compatibility

The official OpenAI SDK works seamlessly by simply changing the base URL. It handles the HTTP POST to v1/audio/speech, returning the audio file directly for saving. No custom client code is required for standard operations.

Code examples

Initialize the client with your base URL and key. Call client.audio.speech.create() with parameters like model, input, and voice. The response contains the binary audio data ready for immediate playback or storage in your VTuber pipeline.

  • Use openai Python SDK or Node.js equivalent
  • Set base_url='https://api.playabcd1234.com/v1'
  • Pass Authorization: Bearer tts-... automatically
OpenAI SDK Integration

Curl Example

Sound wave illustration for: Curl Example

This section provides a ready-to-use cURL command to test the EchoVocal TTS API. It demonstrates a basic request to generate audio from text, covering essential headers and output handling for immediate verification.

The example uses the tts-1 model with the nova voice, generating an MP3 file. It assumes a valid API key is stored in the AUTH_KEY environment variable.

Basic request command

Use the following cURL command to send a POST request to the speech endpoint. Replace YOUR_API_KEY with your actual token from the dashboard.

```bash curl -X POST https://api.playabcd1234.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}' \ -o speech.mp3 ```

Headers setup

The Authorization header must use the Bearer scheme followed by your key starting with tts-.... The Content-Type is strictly application/json for the request body.

Ensure the key is active; new keys invalidate old ones immediately upon issuance. Incorrect keys result in a 401 Unauthorized error.

Output handling

The -o speech.mp3 flag saves the binary audio response directly to a local file. If the request fails, the JSON error object is printed to stderr.

For testing, you can omit -o to view the raw binary output in the terminal, though piping to a file is recommended for verification.

Rate Limits

Sound wave illustration for: Rate Limits

Your API key allows 60 requests per minute under normal operation. This limit applies globally to your key, so concurrent synthesis jobs share this bandwidth. If you exceed this threshold, the API returns a 429 Too Many Requests error, and further requests are rejected until the window resets.

60 requests per minute

Each successful or failed synthesis attempt counts toward this limit. Since requests are processed sequentially, high-volume streaming pipelines may experience slight queuing delays if they approach this ceiling. Plan your batch jobs accordingly to avoid unnecessary latency.

Initial limit of 10 req/min

New accounts start with a reduced limit of 10 requests per minute. This applies until you perform your first top-up. Once you add funds via USDT on the TRON network (TRC-20), the limit automatically increases to the standard 60 req/min.

  • Starts at 10 req/min
  • Increases to 60 req/min after first top-up
  • Limits apply per API key

Handling 429 errors

When you receive a 429 status code, your request was rejected due to rate limiting. Implement exponential backoff in your integration to retry after a short delay. Failed requests do not consume credit but still count toward the rate limit.

Voices and Languages

Sound wave illustration for: Voices and Languages

Retrieve available voice presets and supported languages via a simple GET request. This endpoint provides the authoritative list of options for your synthesis requests, ensuring you select the correct voice ID and language code.

GET /v1/voices endpoint

Call GET /v1/voices to receive a JSON object listing all 8 voice presets and 23 supported languages. Each entry includes the voice ID, name, gender, and compatible languages.

8 preset voices

Choose from four female voices (Aria, Nova, Luna, Sage) and four male voices (Felix, Milo, Atlas, Orion). All voices support any of the 23 languages without needing separate training.

  • Aria: Warm, clear narrator
  • Nova: Bright, upbeat
  • Luna: Soft, storytelling
  • Sage: Calm, instructional
  • Felix: Energetic, promo
  • Milo: Friendly, conversational
  • Atlas: Neutral, news
  • Orion: Deep, documentary

23 supported languages

The API supports Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish. Latin-script text defaults to English if the language is unset.

  • Arabic
  • Chinese
  • Danish
  • Dutch
  • English
  • Finnish

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. VTubers and streamers are turning our indie games into viral sensations, driving massive engagement through their unique and entertaining content.

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

More on this site