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.mp3Python (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 | |
|---|---|
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 |
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
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
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
Bearerheader 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
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
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
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
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.

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
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
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.
23 languages
Any voice speaks any of these languages.
