API Documentation: Generate Audio with TTS-1

By VoiceSwitch editorial team · Updated 2026-11-18

This documentation provides a practical, step-by-step guide for YouTube creators and freelancers migrating from legacy providers like Amazon Polly or Natural Reader. You will find concrete examples for generating professional voiceovers using our modern, cost-effective TTS-1 API. The guide covers authentication, quickstart commands, and SDK integration to help you start generating audio in minutes.

Learn how to structure requests, select from eight distinct voice presets, and handle long-form content efficiently. We explain rate limits, supported audio formats, and error handling with specific numbers relevant to your workflow. Whether you are building a custom pipeline or scripting automated uploads, this page gives you the exact code and facts needed to integrate VoiceSwitch immediately.

API Documentation: Generate Audio with TTS-1

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.play88f.com/v1. You can use the official OpenAI SDKs by changing the base_url to this address and providing your site-specific key. This allows you to use familiar client libraries for making requests to the speech endpoint without needing custom integration code.

Do I need to install a specific SDK?

No proprietary SDK is required. The API follows the same request shape as the OpenAI speech endpoint, so you can use the official OpenAI SDKs by adjusting the base_url. Alternatively, you can make standard HTTP POST requests using any preferred programming language or tool.

How do I set the language parameter?

Include the optional language field with an ISO code in your request JSON. If omitted, the system guesses the language from the script, defaulting Latin text to English. For non-English Latin-script text, always set the language explicitly to ensure correct synthesis and avoid mispronunciation.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so exceeding the limit or high load may cause your request to wait in a queue. Failed requests do not incur charges, but successful ones do.

Can I use the same key for multiple projects?

Yes, each account has one active key that can be used across multiple projects. You can issue a new key at any time, which immediately invalidates the old one. This allows you to rotate keys for security or separate tracking without creating multiple accounts.

Is the API synchronous or asynchronous?

The API is synchronous. You send a POST request and receive the audio file in the response. Requests are processed one after another, so under load, a request may wait in a queue before being synthesized. There is no WebSocket or streaming endpoint for partial audio.

How do I specify the voice name?

Include the voice field in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices are based on licensed recordings from LibriTTS-R and LibriVox. You can view the full list and details via the GET /v1/voices endpoint.

Does the API support streaming audio?

No, the API does not support streaming, WebSocket, or real-time partial audio. You receive the complete audio file in the response body after synthesis is complete. For long texts, you must split the input into parts, generate each file, and join them client-side.

What is the character limit per request?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For texts longer than 4096 characters, you should split the text into smaller parts, generate audio for each part, and join the resulting audio files together.

How do I handle audio file encoding?

Specify the response_format field in your request with one of these values: mp3, wav, opus, flac, or pcm. The API returns the audio file in the requested format directly in the response body. This allows you to choose the best balance between quality and file size.

Is there a delay for long texts?

Yes, synthesis takes time. Typical speed is roughly real-time (about 25 characters of text per second of generation); short phrases take a few seconds. Since requests are processed sequentially, long texts or high load may cause additional delay as requests wait in the queue before being synthesized.

Can I use custom pronunciation dictionaries?

No, the API does not support custom pronunciation lexicons or phoneme dictionaries. You cannot upload your own pronunciation rules. The system uses standard synthesis based on the selected voice preset. For specific pronunciation needs, you may need to adjust the input text spelling before sending it.

How do I test the API before paying?

Sign in with Google to receive a free trial credit of $0.50, valid for 7 days. This provides about 50,000 characters for testing. Accounts created with email and password start without trial credit. Failed requests are free, allowing you to test error handling without cost.

What format is the response body?

The response body contains the audio file directly in the requested format (mp3, wav, opus, flac, or pcm). The request is a standard POST to the /v1/audio/speech endpoint. You do not receive a JSON object with a URL; the binary audio data is returned immediately upon completion.

First request

curl

curl https://api.play88f.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.play88f.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.play88f.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 and Keys

Sound wave illustration for: Authentication and Keys

Access the VoiceSwitch API using a Bearer token included in your request headers. This key authenticates your account and tracks usage against your balance. You can retrieve your active key from the dashboard on the /get-api-key/ page, where it is displayed alongside your current balance and character count.

Generate your Bearer token

Generate your Bearer token

Your API key starts with the prefix tts- and is issued when you sign up via Google or email. Use this key in the Authorization: Bearer tts-... header for all API calls. Keep this token secure, as it provides direct access to your account and billing.

One active key per account

One active key per account

Each account maintains exactly one active API key at any given time. There are no multiple keys or seat-based licenses. If you need to rotate your key, issuing a new one immediately invalidates the previous one, ensuring only one valid token is active.

Revoke old keys instantly

Revocation happens automatically when you generate a new key. The old key stops working immediately, so there is no delay or grace period. This ensures that if a key is compromised, you can secure your account by simply issuing a fresh key from the dashboard.

Quickstart with cURL

Sound wave illustration for: Quickstart with cURL

Generate your first audio file using a simple cURL command. This quickstart demonstrates the core request flow for VoiceSwitch’s TTS API, allowing YouTube creators to test voice generation immediately without installing additional libraries.

Send a POST request to the speech endpoint with your API key and desired parameters. The system processes the text and returns the synthesized audio file directly in the response body.

POST to /v1/audio/speech

Direct your request to https://api.play88f.com/v1/audio/speech. Include your authentication token in the header as Authorization: Bearer YOUR_API_KEY. This endpoint accepts standard JSON payloads for text-to-speech synthesis.

  • Method: POST
  • Endpoint: /v1/audio/speech
  • Auth: Bearer token

JSON body structure

The request body must contain the model, input text, and voice preset. You can optionally specify response_format, speed, and language. Ensure the input text does not exceed 4096 characters per request.

  • model: "tts-1" or "tts-1-hd"
  • input: string (max 4096 chars)
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, or pcm

Receive audio file response

On success, the API returns the audio file directly in the response body. The file format matches your requested response_format. Failed requests incur no charge, ensuring you only pay for successful synthesis.

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

The official OpenAI SDKs work seamlessly with our API by simply adjusting the base_url. Point your client to https://api.play88f.com/v1 and use your VoiceSwitch key. This allows you to keep your existing code structure while switching providers.

This approach ensures compatibility with standard request shapes. You can generate audio files using the same methods you are already familiar with, minimizing integration friction for your YouTube or freelance workflow.

Change base_url to our endpoint

Update your SDK configuration to point to https://api.play88f.com/v1. This single change directs all requests to our cloud infrastructure while maintaining the standard OpenAI compatibility layer.

Use official SDKs seamlessly

Leverage the official OpenAI Python or Node.js libraries without needing a custom client. Authentication is handled via the Authorization: Bearer header using your unique API key issued from the dashboard.

Standard request shape

Send a POST request to /v1/audio/speech with a JSON body containing model, input, voice, and response_format. The engine accepts tts-1 or tts-1-hd models, returning the audio file directly in the response body.

Ensure your input text does not exceed 4096 characters. The SDK handles the JSON serialization automatically, allowing you to focus on your content creation rather than protocol details.

  • Use tts-1 or tts-1-hd for the model field
  • Set input to your script text (max 4096 chars)
  • Specify voice from the 8 available presets
  • Choose response_format from mp3, wav, opus, flac, or pcm

Available Voices and Models

Sound wave illustration for: Available Voices and Models

VoiceSwitch provides eight distinct voice presets designed for YouTube creators and freelancers. Each voice is based on licensed recordings from LibriTTS-R and LibriVox.

Select from 8 presets

Choose from four female voices: Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (calm instruction). Male options include Felix (energetic promo), Milo (conversational), Atlas (neutral news), and Orion (deep documentary).

All voices support 23 languages, including English, Spanish, German, and Japanese. You can set the language explicitly or let the API guess it from the text script.

  • 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

tts-1 and tts-1-hd models

Both 'tts-1' and 'tts-1-hd' use the same underlying engine. There is no quality difference between them, and they share the same pricing structure.

Consistent engine quality

Generated audio files include an inaudible watermark marking them as synthetic speech. Input text is used only for generation and not for training models.

Supported Audio Formats

Sound wave illustration for: Supported Audio Formats

Choose the output format that best fits your production workflow. We support standard formats for web, broadcast, and raw processing, ensuring your audio files are ready for immediate use or further editing.

MP3 for web delivery

MP3 is a common choice for web delivery. It offers high compression with minimal quality loss, making it ideal for YouTube uploads, websites, and mobile apps where bandwidth matters.

WAV for lossless quality

WAV provides uncompressed, studio-quality audio. Use this format when you need maximum fidelity for professional voiceovers, podcast master files, or when your editing software requires lossless input for precise cutting.

Opus, FLAC, and PCM options

Opus offers superior compression for modern web players. FLAC provides lossless compression for smaller file sizes than WAV. PCM delivers raw, uncompressed audio samples, suitable for direct DSP processing or specific hardware integrations.

  • Opus: Efficient format for web streaming
  • FLAC: Lossless compression for smaller files
  • PCM: Raw audio for DSP processing
Supported Audio Formats

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

Understanding rate limits ensures your TTS pipeline runs smoothly without unexpected interruptions. Our system caps usage at 60 requests per minute per active API key, providing a stable foundation for both occasional queries and bulk generation tasks.

Before your first top-up, you are limited to 10 requests per minute. This lower threshold allows you to test the API’s quality and performance without requiring immediate payment. Once you add credit via USDT, the limit increases to the standard 60 requests per minute.

60 requests per minute

After topping up, your account supports up to 60 requests per minute. This limit applies to each API key individually, so ensure you use a single active key to maximize throughput. Exceeding this limit will result in HTTP 429 Too Many Requests responses.

  • Limit resets every 60 seconds.
  • Applies per API key, not per account.
  • Exceeding limits returns HTTP 429.

10 requests before first top-up

New accounts or those without a recent top-up start with a reduced rate of 10 requests per minute. This allows you to verify voice quality and integration before committing funds. The limit automatically adjusts once your balance is updated.

  • Initial limit for untopped accounts.
  • Applies until the first successful USDT transfer.
  • Ensures fair usage during testing.

Queue handling under load

Requests are processed sequentially within the limit. Under high load, requests may wait in a queue. This ensures that all valid requests are eventually processed, though generation time may increase during peak usage periods.

If a request fails during synthesis, no charge is applied. You can retry failed requests without penalty, ensuring cost efficiency even during unstable network conditions.

  • Requests are queued, not dropped.
  • No charge for failed synthesis.
  • Retry failed requests freely.

Handling Long Texts

Sound wave illustration for: Handling Long Texts

The API accepts a maximum of 4,096 characters per request. To generate audio for longer scripts, split your input text into smaller chunks of this size before sending them individually.

Split text into 4096 char chunks

Divide your source text into segments of up to 4,096 characters each. Send each segment as a separate POST request to /v1/audio/speech. This ensures every request stays within the defined limit.

Join audio files programmatically

Receive each audio file sequentially from the API responses. Concatenate the resulting audio files in the correct order using your preferred media library to reconstruct the full voiceover.

Manage character limits

Remember that spaces and punctuation count toward the 4,096 character limit. Plan your splits carefully to avoid cutting mid-sentence, which helps maintain natural audio continuity when joined.

Error Codes and Debugging

Sound wave illustration for: Error Codes and Debugging

The API returns standard HTTP status codes to indicate success or failure. A 4xx error usually means the request was malformed, such as exceeding character limits or using an invalid voice ID. A 5xx error indicates a temporary server issue, often due to queueing under load. Always check the response body for a specific error message to identify the root cause quickly.

Handle HTTP 4xx and 5xx

Use 4xx codes to correct your request parameters immediately. For 5xx errors, implement a retry logic with exponential backoff, as the system processes requests sequentially and may queue your task during high traffic.

Check character limits

Each request is limited to 4096 characters. If your input exceeds this limit, the API returns a 400 error. You must split long texts into smaller chunks before sending them to ensure successful synthesis.

Verify API key validity

A 401 Unauthorized error occurs if your Bearer token is missing, expired, or invalid. Ensure your Authorization header is correctly formatted as Bearer tts-.... Remember that generating a new key instantly invalidates the previous one.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Consistent uploads build trust with your viewers and steadily grow your subscriber base over time.

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. Node.js documentation
  3. openai-python on GitHub
  4. IETF RFC 7845: Ogg Opus
  5. Tether (USDT)
  6. OpenAI API reference: create speech
  7. LibriTTS-R corpus (OpenSLR 141)
  8. ISO 639 language codes
  9. Python documentation
  10. openai-node on GitHub
  11. curl documentation
  12. FFmpeg documentation

More on this site