TTS API Documentation: Integration Guide for Developers

By StreamVoice editorial team · Updated 2026-11-19

This guide helps VTubers and streamers integrate VocalShift’s text-to-speech API into their no-code workflows. You will learn how to generate consistent, expressive narration using simple HTTP requests or the OpenAI SDK. We cover everything from obtaining your API key to handling responses, so you can focus on your content without worrying about the technical details.

We provide concrete examples for common use cases, including voice selection, speed adjustment, and handling long texts. Whether you are automating stream alerts or creating video voiceovers, this documentation gives you the specific steps and parameters needed to get started quickly. All technical details are based on the actual API capabilities available at api.cx882.info.

TTS API Documentation: Integration Guide for Developers

Frequently asked questions

How do I get my API key?

Sign up on the /get-api-key/ page using Google or email and password. Your account page displays your active API key, balance, and usage statistics. Accounts created with email do not receive the free trial credit, while Google sign-ins get $0.50 valid for seven days.

Can I use the OpenAI SDK with this API?

Yes. The request shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.cx882.info/v1 and providing your VocalShift key. This allows seamless integration into existing codebases without rewriting HTTP clients.

What is the base URL for the API?

The API base URL is https://api.cx882.info/v1. You send POST requests to https://api.cx882.info/v1/audio/speech for speech generation. Other endpoints like /v1/voices and /v1/models are also available at this base path for retrieving configuration details.

How many characters can I send in one request?

Each request supports up to 4096 characters in the input field. For longer texts, you must split the content into chunks of this size and join the resulting audio files. Spaces and punctuation count toward this character limit.

What audio formats are supported?

You can request audio in mp3, wav, opus, flac, or pcm formats via the response_format parameter. These options cover various quality and compression needs, allowing you to choose the format that fits your streaming or recording workflow.

What are the rate limits for the API?

The limit is 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up is processed. Requests are processed sequentially, so high load may cause queuing delays during synthesis.

How do I handle failed requests?

Failed requests are free; the charge is returned in full if synthesis fails. You do not need to manually refund or credit yourself. Simply retry the request or adjust parameters like speed or voice if the error persists.

Can I change the voice speed?

Yes, the speed parameter accepts values between 0.25 and 4.0. This allows you to adjust the pacing of the narration to suit different content types, from slow storytelling to fast-paced commentary, without altering the voice preset.

Do I need to specify the language for every request?

No, but it is recommended for non-English Latin text. If omitted, the system guesses the language, defaulting to English for Latin scripts. Explicitly setting the language ISO code ensures accurate pronunciation for the 23 supported languages.

How are long texts handled?

You must split texts exceeding 4096 characters into smaller parts. Generate audio for each part separately and then join the audio files. This ensures each request stays within the character limit while delivering a complete final output.

Is the API key secure?

Each account has one active key used for authentication via the Authorization header. You can rotate this key at any time via the dashboard. When a new key is issued, the old one stops immediately, ensuring secure access.

Can I rotate my API key?

Yes, you can issue a new key at any time from your account page. The previous key becomes invalid immediately upon issuing the new one. This allows you to revoke access quickly if a key is compromised.

What happens if I exceed the rate limit?

Requests are processed sequentially, so under load a request may wait in a queue. New accounts start with 10 requests per minute, increasing to 60 after the first top-up. You can monitor your usage and balance directly on the dashboard.

How do I know which voice to use?

Use the GET /v1/voices endpoint to list all 8 presets. Voices include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Each has a distinct tone, such as warm narration or energetic promo, to match your content style.

First request

curl

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

Getting Your API Key

Sound wave illustration for: Getting Your API Key

Get your API key via /get-api-key/ using Google or email. Google sign-ins start with $0.50 trial credit valid for 7 days; email accounts begin with zero balance. You’ll see your active key, usage stats, and a ready curl example immediately after logging in.

Sign Up Process

Sign Up Process

Visit the sign-up page and choose Google or email authentication. Google accounts receive $0.50 trial credit (approx. 50,000 characters) valid for 7 days. Email accounts start without trial credit but can top up immediately.

Key Management

Key Management

Each account holds one active API key. View your key, balance, and usage details directly on the dashboard. Keys are used via the Authorization: Bearer header in all requests.

  • One active key per account
  • View balance and character count on dashboard
  • Use Bearer header for auth

Key Rotation Policy

You can issue a new key at any time. When you generate a new key, the old one stops working immediately. This ensures secure access without downtime if you rotate keys frequently.

First Request with Curl

Sound wave illustration for: First Request with Curl

Start by generating your API key on the /get-api-key/ page. You can sign up with Google or an email account to receive your credentials instantly. Keep this key secure, as it authenticates all your requests.

Basic Syntax

Send a POST request to https://api.cx882.info/v1/audio/speech. The body must be JSON containing your text and voice selection. The API returns the audio file directly in the response.

Required Parameters

You must provide the model ("tts-1" or "tts-1-hd"), the input text (up to 4096 characters), and a voice preset like "aria" or "felix". Optional fields include response_format, speed, and language.

  • model: "tts-1" or "tts-1-hd"
  • input: your text string
  • voice: e.g., "nova", "atlas"
  • response_format: mp3, wav, opus, flac, or pcm

Response Handling

The API returns the audio file directly. Save the binary output to a file on your server or stream it to your application. Failed requests are free: if synthesis fails, the charge is returned in full.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Connect your preferred OpenAI SDK to VocalShift by simply overriding the base URL. This allows you to use familiar libraries without rewriting your integration logic, fitting seamlessly into your existing no-code or low-code streaming workflows.

The SDK compatibility is broad because we mirror the standard request shape. You only need to point the client to our API endpoint and supply your generated key.

### Base URL Configuration Set the base_url parameter in your SDK client to https://api.cx882.info/v1. This directs all subsequent calls to our infrastructure while maintaining standard OpenAI-compatible behavior. ### SDK Compatibility The official OpenAI SDKs work by changing base_url to https://api.cx882.info/v1 and using the site's key. Since our endpoint mimics the official speech structure, you can swap the URL and keep your existing code structure intact. ### Example Code Snippet ```python from openai import OpenAI client = OpenAI( base_url="https://api.cx882.info/v1", api_key="tts-your-api-key-here" ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Hello streamers, welcome to the show!" ) response.stream_to_file("output.mp3") ```

Available Voices and Models

Sound wave illustration for: Available Voices and Models

VocalShift offers eight distinct voice presets designed for consistent, expressive narration in VTuber and streaming workflows. You can choose from female voices like Aria for warm narration or Nova for upbeat energy, and male voices like Felix for energetic promos or Orion for deep, documentary-style delivery. Every voice supports all 23 languages, ensuring your content sounds natural regardless of the target audience.

Voice Preset List

The eight voices are built from licensed recordings, providing a reliable audio foundation. Select from Aria, Nova, Luna, and Sage for female tones, or Felix, Milo, Atlas, and Orion for male tones. Each voice has a specific character, from calm and instructional to bright and conversational, allowing you to match the tone of your stream or video.

  • Female: Aria, Nova, Luna, Sage
  • Male: Felix, Milo, Atlas, Orion

Model Options

Both "tts-1" and "tts-1-hd" models use the same engine and pricing. You can switch between them based on your quality preference without any change in cost or character limits. The API handles the audio generation efficiently, ensuring consistent output for your no-code integrations.

Language Support

We support 23 languages, including English, Japanese, Spanish, and German. Any voice can speak any of these languages. If you do not specify a language, the system guesses it from the script, defaulting to English for Latin text. For non-English Latin scripts, always set the language parameter to ensure accuracy.

  • 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 to suit different streaming and editing workflows. MP3 is the default and most efficient choice for general use, offering a good balance between file size and quality. It is ideal for real-time playback in stream overlays or VODs where bandwidth matters.

MP3 Support

MP3 is the standard format for most integrations. It provides consistent audio quality while keeping file sizes small, making it perfect for quick API calls and seamless playback in OBS or Streamlabs.

WAV Format

WAV offers uncompressed, lossless audio. Use this format when you need pristine quality for video editing or when your software requires raw PCM data. It is larger but ensures no compression artifacts affect your stream's audio.

Other Audio Options

You can also request Opus, FLAC, or PCM. Opus is one of the supported response formats (mp3, wav, opus, flac, pcm). FLAC provides lossless compression for archiving. PCM gives raw audio data. Choose based on your specific encoding needs.

Response Formats

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

The API enforces a strict rate limit of 60 requests per minute per active key. This limit ensures fair usage and stable performance for all VTubers and streamers integrating the service into their no-code workflows. Each request counts toward this quota, regardless of text length or audio format selected.

It is crucial to monitor your usage to avoid temporary throttling, especially when automating content generation for live streams or pre-recorded videos. Understanding these constraints helps maintain smooth audio delivery without unexpected interruptions during peak usage times.

Requests Per Minute

You are allowed a maximum of 60 requests per minute for your active API key. This limit applies to all standard speech synthesis endpoints. If you exceed this threshold, subsequent requests will be rejected until the window resets.

This consistency allows you to reliably automate text-to-speech tasks for your VTuber channels without worrying about sudden drops in service availability during normal operation.

  • Limit: 60 requests per minute per key
  • Applies to: All standard synthesis requests
  • Reset: Rolling 60-second window

Pre-Top-Up Limits

Before your first top-up, your rate limit is reduced to 10 requests per minute. This lower limit applies to all accounts, including those with free trial credit.

Once you top up via USDT on the TRON network (TRC-20), your limit automatically increases to the full 60 requests per minute. This ensures that paying customers get consistent performance for their content pipelines.

  • Pre-top-up: 10 requests per minute
  • Post-top-up: 60 requests per minute
  • Automatic increase upon credit receipt

Queue Handling

Requests are processed sequentially. Under heavy load, a request may wait in a queue before synthesis begins. This is normal behavior and ensures fair distribution of resources.

There is no guaranteed immediate response time during high-demand periods. Plan your content generation accordingly to avoid delays in your streaming workflow.

  • Sequential processing
  • Queuing under load

Error Handling Guide

Sound wave illustration for: Error Handling Guide

When your TTS requests encounter issues, understanding the response structure helps you resolve them quickly. This guide covers the most frequent errors and how to handle them programmatically without losing credits.

Our API returns standard HTTP status codes to indicate success or failure. Failed synthesis requests are free, so you won’t be charged for audio that didn’t generate.

Common Error Codes

We use standard HTTP status codes to communicate request states. A 200 OK means your audio is ready. A 4xx error usually indicates an authentication or input issue, such as an invalid API key or text exceeding the 4096-character limit. A 5xx error suggests a temporary server issue.

If you receive a 429 Too Many Requests, you have exceeded the rate limit of 60 requests per minute. If you haven’t topped up yet, this limit drops to 10 requests per minute. Check your balance and key validity before retrying.

  • 401 Unauthorized: Invalid or expired API key. Check your credentials.
  • 400 Bad Request: Missing required fields or invalid voice/model ID.
  • 429 Too Many Requests: Rate limit exceeded. Wait or top up.
  • 503 Service Unavailable: Temporary overload. Retry with backoff.

Retry Logic

For 5xx errors, implement an exponential backoff strategy. Start with a 1-second delay and double it for each subsequent attempt, up to three retries. This prevents overwhelming the server during brief spikes.

For 429 errors, wait until the next minute begins. Since we process requests sequentially, a queue delay might also cause timeouts. If your request takes longer than expected, consider splitting your text into smaller chunks.

  • Retry 5xx errors with exponential backoff (1s, 2s, 4s).
  • For 429 errors, wait for the rate limit window to reset.
  • Max 3 retries before alerting the user or logging the error.

Debugging Tips

Always log the full request payload and response headers. If the response is empty, check if the input field is within the 4096-character limit. Verify that your voice ID matches one of the 8 presets.

If audio generation is slow, note that long texts are processed sequentially. For streams, consider splitting text into smaller segments and joining the resulting audio files on your end. Use the /v1/voices endpoint to verify available voices and languages.

  • Check character count: max 4096 per request.
  • Verify voice IDs against /v1/voices endpoint.
  • Log request time to diagnose queue delays.
  • Ensure language code matches non-English Latin text.

Advanced Usage Tips

Sound wave illustration for: Advanced Usage Tips

Maximize efficiency by splitting input text into chunks of up to 4096 characters and joining the resulting audio files. For long narration, expect roughly real-time generation speed, though short phrases may take a few seconds due to sequential processing.

Long Text Splitting

Divide your script into segments of 4096 characters or less. Generate each part individually and concatenate the audio files to create a seamless long-form track suitable for VTuber intros or extended streams.

Speed Adjustment

Adjust playback speed between 0.25 and 4.0 to match your stream’s pacing. Use slower speeds for dramatic pauses or faster rates for quick updates, ensuring the voice remains natural across all settings.

Language Specification

Always set the language field for non-English Latin script text, as the API defaults to English. This ensures accurate pronunciation for the 23 supported languages.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Selecting the right voice ensures your content resonates with the intended audience, whether you are hyping a win or explaining a tutorial.

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. W3C WAI: making audio and video accessible
  3. openai-node on GitHub
  4. OpenAI API reference: create speech
  5. ISO 639 language codes
  6. IETF RFC 7845: Ogg Opus
  7. TRON developer hub: TRC-20
  8. Creative Commons Attribution 4.0
  9. Tether (USDT)
  10. Python documentation
  11. LibriVox public-domain audiobooks
  12. FFmpeg documentation

More on this site