Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.playcv99.com/v1. You configure this in your client settings or by setting the base_url parameter. All requests, including speech synthesis and voice listing, are routed through this endpoint. Ensure your Authorization header uses your specific API key for authentication.
How do I install the OpenAI SDK?
Install the official OpenAI SDK using your preferred package manager, such as pip install openai for Python or npm install openai for Node.js. Once installed, configure the client to point to our base URL. The SDK handles request formatting automatically, requiring only your API key and standard parameters.
What happens if I exceed the rate limit?
You are limited to 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a 10 requests per minute limit until the first top-up. Exceeding the limit does not incur extra charges; it simply delays processing until capacity is available.
Can I use custom speed values?
Yes, you can set the speed parameter between 0.25 and 4.0. This allows fine-tuning of the voice-over pace for different ad lengths. Values outside this range will result in an error. Adjusting speed helps match the tone of your video or radio spot precisely.
How do I specify a language?
Include the optional language field with an ISO code in your request body. If omitted, the system guesses the language based on the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate pronunciation for non-English content, such as German or Japanese.
Is the API compatible with other SDKs?
The API follows the same request shape as the OpenAI speech endpoint. Any SDK that supports OpenAI’s format works by changing the base_url. You can use the official OpenAI SDKs or plain HTTP requests. No proprietary SDK is required for integration into your production pipeline.
What is the maximum text length?
Each request supports up to 4096 characters of input text. For longer scripts, split the text into parts of this size and join the resulting audio files. This ensures consistent processing speed and prevents timeout issues during bulk synthesis for longer radio spots or video voice-overs.
Do I need to handle audio decoding?
No, the API returns the audio file directly in the response body. You receive the binary data. The response format matches the requested output type, such as mp3, wav, opus, flac, or pcm.
How do I generate multiple voices?
Specify the desired voice preset in the voice field of each request. You can choose from eight options like aria, nova, or atlas. Each request generates audio for one voice. To create a multi-voice scene, send separate requests for each character and edit the audio files together.
What is the status code for success?
A successful synthesis returns an HTTP 200 OK status code along with the audio data. If the request fails, you receive an error code and potentially a refund. Failed requests do not consume your character balance, ensuring you only pay for successfully generated audio files.
Can I retry failed requests?
Yes, you can retry failed requests immediately. Since failed requests are free, retrying does not incur additional costs. This allows you to regenerate audio if a synthesis error occurs without worrying about wasting your character balance. Simply resend the same payload with the correct parameters.
Do you support async processing?
The API processes requests synchronously. Requests are handled one after another, so under load, a request may wait in a queue. There is no asynchronous webhook or polling endpoint for status updates. You receive the audio file directly in the response once processing is complete.
How do I rotate my API key?
Issue a new API key from your account dashboard at any time. The old key stops working immediately upon issuing the new one. This allows seamless rotation without downtime. You can manage your active key and view usage details directly on the /get-api-key/ page.
What format is the audio response?
You can choose from mp3, wav, opus, flac, or pcm formats. The response delivers the audio file in the specified format. MP3 is suitable for web playback, while WAV or FLAC offers higher quality for professional editing. Select the format that best fits your production workflow.
First request
curl
curl https://api.playcv99.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playcv99.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.playcv99.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 | |
|---|---|
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
Access the API by creating an account at /get-api-key/. You can sign up using Google or an email and password. The dashboard displays your single active API key, current balance, and usage statistics.
Include the key in every request header. You can rotate keys at any time; the old key stops immediately upon issuing a new one.
Generate API key
Navigate to the /get-api-key/ page on playcv99.com. Sign up via Google or email/password to receive your unique key.
Bearer token format
Include your key in the HTTP header as: Authorization: Bearer tts-<your_key>. This standard format works with the OpenAI SDKs.
Key rotation
Issue a new key from the dashboard whenever needed. The previous key becomes invalid immediately, ensuring tight control over your ad agency's access.
Endpoint structure
The synthesis endpoint accepts text and returns audio files directly. You send a POST request to /v1/audio/speech with your API key in the Authorization header. This single endpoint handles all generation tasks, from short phrases to full voice-over scripts.
The service returns binary audio data or an error JSON object. There are no separate endpoints for streaming or status checks; the process is synchronous. You receive the complete file only when generation finishes, ensuring predictable file sizes for your ad production pipeline.
POST /v1/audio/speech
Send text to this endpoint to generate audio. The request must include a valid Bearer token. The service processes requests sequentially, so high-volume campaigns may queue during peak usage.
The endpoint relies on POST for all synthesis operations. Ensure your client handles binary responses correctly to avoid audio file corruption.
- Base URL: https://api.playcv99.com/v1
- Method: POST
- Content-Type: application/json
JSON request body
Structure your request with the model, input, and voice fields. The input field accepts up to 4096 characters. Any text exceeding this limit must be split by your application before sending.
Optional fields like speed and response_format allow fine-tuning. The language parameter is optional but recommended for non-English Latin text to ensure accurate pronunciation. Failed requests return a JSON error object with a code and message.
OpenAI compatibility
The endpoint mirrors the OpenAI speech API structure. You can use the official OpenAI SDKs by changing the base_url to https://api.playcv99.com/v1. This allows easy integration into existing workflows without rewriting HTTP clients.
Key differences include the voice presets and pricing model. The SDK handles authentication and serialization automatically, reducing boilerplate code for your development team.
Parameters
Configure synthesis parameters to match your creative needs. The API accepts standard fields for model quality, voice selection, and playback speed, ensuring precise control over the final audio output for your voice-over projects.
Model selection
Choose between "tts-1" for standard quality or "tts-1-hd" for higher fidelity. Both use the same engine and pricing, allowing you to upgrade quality without changing your integration logic.
Voice presets
Select from eight distinct voice presets, ranging from warm narrators to energetic promo voices. Each voice supports all 23 languages, though you should specify the language for non-English Latin text to ensure accurate pronunciation.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Speed and language
Adjust playback speed from 0.25 to 4.0 to fit timing constraints. The API guesses language from script but prefers explicit ISO codes for accuracy, supporting languages like Arabic, Japanese, and Swahili alongside major European tongues.
Response formats
The API returns audio files in the format specified by the response_format field in your request. Supported formats include MP3, WAV, Opus, and FLAC, allowing you to choose the optimal balance between file size and quality for your production pipeline.
MP3 is the default and most widely compatible format for web and radio delivery. WAV provides uncompressed lossless audio, ideal for final master files. Opus and FLAC offer efficient compression with high fidelity, suitable for archives or further processing. PCM is also supported.
MP3 output
MP3 is the default format and provides a good balance between file size and audio quality. It is widely supported by video editing software and radio broadcast systems, making it the standard choice for most voice-over projects.
WAV output
Select wav for uncompressed, lossless audio. This format preserves the full fidelity of the synthesis engine, making it ideal for final master files or when you plan to apply additional audio effects in post-production without generation loss.
Opus and FLAC options
Opus provides efficient compression with high quality, suitable for storage-efficient archives. FLAC offers lossless compression, reducing file size while retaining all audio data. Both are valid options depending on your storage and bandwidth constraints.
Error handling
The API returns standard HTTP status codes to indicate request outcomes. Most errors are immediate and self-correcting, allowing your automation scripts to handle retries or user notifications efficiently.
Understanding these error types helps you maintain steady voice-over production workflows without unexpected downtime or wasted credits on failed synthesis attempts.
Rate limit errors
Requests are limited to 60 per minute per key. New accounts start with a stricter limit of 10 requests per minute until the first top-up is processed.
If you exceed this threshold, the API returns a 429 status code. You must wait before sending the next request to avoid queueing delays.
- Status: 429 Too Many Requests
- Limit: 60 req/min (10 req/min initially)
- Action: Wait and retry
Invalid character count
Each request supports a maximum of 4096 characters in the input field. If your script sends longer text without splitting, the API rejects the request.
Characters include spaces and punctuation. You must split longer texts into multiple requests and join the resulting audio files manually.
- Max length: 4096 characters
- Includes spaces and punctuation
- Split text for longer scripts
Server errors
Internal server errors (5xx) are rare but may occur during peak load. These errors do not consume your balance.
Failed synthesis requests are free, so you can safely retry them without worrying about credit deduction.
- 5xx errors: No charge
- Retry safely
- Check status codes

SDK integration
Integrate our API using standard OpenAI SDKs by adjusting the base URL. This allows you to leverage familiar client libraries for Python and Node.js while directing requests to our infrastructure.
Ensure your SDK configuration points to the correct endpoint. The official OpenAI clients work seamlessly once the base URL is updated to our API domain.
OpenAI Python SDK
Install the openai package and configure the base URL to https://api.playcv99.com/v1. Use your API key for authentication. The client handles the JSON payload construction for tts-1 or tts-1-hd models.
- Install via pip install openai
- Set
base_urltohttps://api.playcv99.com/v1 - Use standard
AudioResponsemethods
OpenAI Node SDK
For JavaScript environments, install the OpenAI Node package. Configure the client with the custom base URL and your Bearer token. The SDK manages the request lifecycle.
- Install via npm install openai
- Configure
baseURLin client options - Handle audio stream or buffer output
Base URL configuration
Set the base URL to https://api.playcv99.com/v1 in your SDK client settings. This redirects all API calls to our service while maintaining compatibility with the OpenAI request shape.
Curl example
Generate audio files directly from the command line to test your workflow before integrating into your video editing pipeline. The API accepts standard JSON payloads, making it easy to automate voice-over generation for radio spots or social media ads.
Use these examples to verify your API key and understand how parameters like voice selection and speed affect the final audio output. Each request returns a binary audio file that you can immediately save or pipe into your production tools.
Basic request
Send a simple request to generate a standard voice-over clip. Replace YOUR_API_KEY with your secret key from the dashboard.
```bash curl -X POST https://api.playcv99.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "voice": "nova", "input": "Hello, this is a test ad.", "response_format": "mp3"}' \ -o output.mp3 ```
This command uses the "nova" voice, which is bright and upbeat, suitable for energetic promotional content. The output is saved as an MP3 file.
With speed control
Adjust the speech rate to fit your video timing. The speed parameter accepts values from 0.25 to 4.0, where 1.0 is normal pace.
```bash curl -X POST https://api.playcv99.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "voice": "atlas", "input": "Breaking news: sales end today.", "response_format": "wav", "speed": 1.5}' \ -o fast_news.wav ```
This example uses "atlas" for a neutral, news-style delivery at 1.5x speed, ideal for quick updates or time-sensitive announcements.
With language code
Explicitly set the language to ensure accurate pronunciation, especially for non-English text. Without this, the API guesses based on script.
```bash curl -X POST https://api.playcv99.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1-hd", "voice": "luna", "input": "Bem-vindo ao nosso programa.", "response_format": "opus", "language": "pt"}' \ -o brazilian_portuguese.opus ```
Here, the Portuguese language code "pt" guides the "luna" voice to deliver a soft, storytelling tone in Brazilian Portuguese.
Limits and quotas
To handle bulk voice-over production, the API enforces a rate limit of 60 requests per minute per key. This ensures stable processing for ad agencies generating radio spots in volume without overwhelming the synthesis queue.
New accounts start with a 10 requests-per-minute limit until the first top-up is processed. This threshold prevents initial spam and stabilizes service before full-scale usage begins.
60 requests per minute
After funding your account, you can generate up to 60 audio files every minute. This throughput is sufficient for most mid-sized ad agency workflows producing daily radio or video voice-overs.
10 requests before top-up
Until you add credit via USDT (TRC-20), your account is capped at 10 requests per minute. This allows testing the API with your trial credit before committing to bulk synthesis.
Once your top-up clears, typically within minutes, the limit automatically upgrades to 60 requests per minute.
4096 character limit
Each API call accepts a maximum of 4096 characters, including spaces and punctuation. For longer scripts, split the text into parts and concatenate the resulting audio files.
Splitting allows you to maintain control over pacing and ensures each segment processes within the standard queue time.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence.
23 languages
Any voice speaks any of these languages.
