Quickstart Guide to Our Text-to-Speech API

By SpotWave editorial team · Updated 2026-11-18

This guide shows ad agencies and content creators how to integrate our text-to-speech API for radio spots and video voice-overs. You will learn to send text and receive audio files using standard JSON requests, compatible with existing OpenAI SDKs. We cover authentication, parameter tuning, and error handling so you can automate bulk synthesis reliably.

Readers will find concrete examples for generating MP3, WAV, Opus, and FLAC outputs with specific voices like Aria or Atlas. We detail rate limits, character constraints, and pricing structures essential for production workflows. By the end, you will have a working curl command and understand how to manage keys and speed settings for consistent audio delivery.

Quickstart Guide to Our Text-to-Speech API

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

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

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

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

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

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

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

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

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

SDK integration

Sound wave illustration for: 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_url to https://api.playcv99.com/v1
  • Use standard AudioResponse methods

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 baseURL in 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

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

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

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. IETF RFC 7845: Ogg Opus
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. TRON developer hub: TRC-20
  5. W3C WAI: making audio and video accessible
  6. openai-node on GitHub
  7. openai-python on GitHub
  8. Tether (USDT)
  9. LibriTTS-R corpus (OpenSLR 141)
  10. Python documentation
  11. FFmpeg documentation
  12. Node.js documentation

More on this site