Developer Guide for Our Text-to-Speech API

By StreamVoice editorial team · Updated 2026-11-18

This guide explains how to integrate the VocalFlow text-to-speech API into your VTuber tools or streaming overlays. You will learn to generate clear, licensed speech for VODs, intros, and emote reactions using standard HTTP requests or the OpenAI SDK. No custom code or complex setups are required.

Follow these steps to manage your API key, select voices, and handle audio formats like MP3 and WAV. The documentation covers rate limits, error handling, and long-text splitting to ensure reliable generation for your live streams. Start by creating your account to get a free trial credit.

Developer Guide for Our Text-to-Speech API

Frequently asked questions

What is the base URL for the API?

The base URL is https://api.playb77.com/v1. Send POST requests to https://api.playb77.com/v1/audio/speech for synthesis. Other endpoints include GET /v1/voices and GET /v1/models. This structure matches the OpenAI speech endpoint, allowing you to use existing OpenAI SDKs by simply updating the base_url configuration in your client.

Does the API support streaming audio?

No, the API does not support streaming, WebSocket connections, or real-time partial audio. It is a synchronous endpoint that returns the complete audio file once synthesis is finished. For live streams, you must generate the audio file beforehand or handle buffering in your application logic after receiving the full response.

Can I use the OpenAI Python SDK?

Yes. The official OpenAI SDKs work because the request shape is identical. Change the base_url to https://api.playb77.com/v1 and use your API key (tts-...). This applies to Python, JavaScript, and other supported SDKs. Since the endpoint structure matches, you can reuse existing code with minimal configuration changes.

What is the maximum character limit?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, split the content into parts of 4096 characters or fewer, generate audio for each segment, and then join the resulting files. This ensures successful synthesis without exceeding the per-request constraint.

How do I specify the language?

Include the optional language field in your JSON body with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly set the language to ensure accurate pronunciation across the 23 supported languages.

Is SSML supported in the JSON body?

No, the API does not support SSML. Input is plain text only, with no phoneme dictionaries, custom pronunciation lexicons, or emotion tags. You control pacing via the speed parameter (0.25–4.0). For emphasis, insert pauses or adjust text phrasing directly in your input string rather than relying on markup tags.

What happens if the rate limit is exceeded?

Requests are processed sequentially, so under load, a request may wait in a queue. If you exceed the limit of 60 requests per minute (or 10 before your first top-up), you will receive a 429 error. Simply retry after a short delay. Since synthesis takes time, long texts are split into parts, which naturally helps manage the rate limit.

Can I generate multiple voices at once?

Yes, but each API request produces audio for only one voice. To create a multi-voice track, send separate POST requests for each preset. You can run these requests in parallel to reduce total generation time, as each request is independent. Simply split your script into individual calls for Aria, Nova, Felix, etc., and combine the resulting audio files.

How do I handle errors in my code?

The API returns standard HTTP status codes with a JSON error body. Failed synthesis requests are free, and the charge is returned in full if the process fails. Check the status code to determine if the request succeeded or if you need to retry, such as after hitting a rate limit.

Is the API synchronous or asynchronous?

The API is synchronous: you send a request and receive the complete audio file in the response. There is no webhook or polling mechanism. For long texts, you must split the input into chunks of up to 4,096 characters, wait for each chunk’s response, and then assemble the final audio files.

Do I need to install a specific library?

No. You can use the official OpenAI SDK or plain HTTP requests. Since our API endpoint shape matches OpenAI’s, any standard HTTP client or SDK supporting JSON bodies and Bearer token authentication works. Just change the base URL to https://api.playb77.com/v1 and use your API key. No specific library from us is required.

Can I use custom pronunciation lexicons?

No, custom pronunciation lexicons are not supported. The API uses fixed voice presets based on licensed recordings. You cannot upload custom phoneme dictionaries or define specific pronunciations for words. Pronunciation is determined by the selected voice and the standard text input provided in the request.

What is the response format?

The API returns the generated audio file directly in the response body, matching the format you specify via the response_format field. Supported formats include mp3, wav, opus, flac, and pcm. This direct delivery allows you to easily save the audio for your VTuber streams without additional processing steps.

How do I renew my API key?

You can issue a new API key at any time from your account dashboard. When a new key is generated, the old one stops working immediately. This allows you to rotate keys for security without downtime. You can manage your keys and view usage details on the /get-api-key/ page.

First request

curl

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

Get Your API Key

Sound wave illustration for: Get Your API Key

Access the /get-api-key/ page on playb77.com to obtain your API credentials. You can authenticate instantly using your Google account or register with a standard email and password combination.

Sign Up with Google

Sign Up with Google

Google sign-up provides immediate access with a $0.50 trial credit valid for 7 days. This credit covers approximately 50,000 characters of generated audio.

Email and Password Option

Accounts created via email do not receive trial credit upon registration. You must top up manually using USDT (TRC-20) to begin generating speech.

Key Management

The dashboard displays your active API key, current balance, and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one.

  • Authorization header format: Bearer tts-...
  • One active key per account
  • Old keys stop immediately upon reissuing

First Request (cURL)

Sound wave illustration for: First Request (cURL)

Use cURL to send a POST request to the API endpoint. The body must be JSON containing the text, voice, and model. This method works for the 23 supported languages and formats supported by the API. You can test the endpoint directly from your terminal or script environment.

The request requires specific fields to generate audio correctly. Missing parameters will cause the request to fail. Ensure your text does not exceed 4096 characters. The API returns the audio file directly in the response body.

Basic JSON Body

Send a POST request to https://api.playb77.com/v1/audio/speech. The body must be a valid JSON object containing the text to be spoken, the voice preset, and the model identifier. The API expects standard fields compatible with the OpenAI speech endpoint structure.

Include the input field with your text string, voice for the chosen preset, and model as either tts-1 or tts-1-hd. You can optionally specify response_format and speed. The request must be authenticated with your Bearer token in the header.

  • model: "tts-1" or "tts-1-hd"

Required Fields

The model and input fields are mandatory. The voice field is required to specify which preset voice generates the audio, unless a default is implied by the language (though a voice is still recommended). The input text must be a string with a maximum length of 4096 characters. Spaces and punctuation count toward this limit.

If you do not provide a language code, the API guesses the language from the script. For non-English Latin text, explicitly set the language to avoid incorrect synthesis. The response_format defaults to mp3 if not specified.

Response Handling

On success, the API returns the audio file in the requested format (mp3, wav, opus, flac, or pcm). Failed requests are free, but the response body format for errors is not guaranteed to be JSON for all failure types. Network errors or 500s may not return a structured JSON object.

Handle the response by saving the binary data to a file. Check the HTTP status code to confirm success. If the synthesis fails, no charge is applied to your balance. Ensure your client handles binary streams correctly for audio output.

First Request (cURL)

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

The OpenAI SDKs work seamlessly with our API by simply changing the base_url. This ensures you benefit from the SDK’s built-in error handling and retry logic while accessing our TTS engine. Our implementation accepts the same parameters and returns audio files in standard formats, ensuring compatibility with tools already built for OpenAI’s speech endpoint.

This approach lets you integrate TTS into your VTuber stream overlays or VOD processing pipelines without rewriting your entire request logic. This is the only configuration change required to route requests to our infrastructure.

Change Base URL

Set the client's base_url to https://api.playb77.com/v1 and use your API key. The request shape matches the OpenAI speech endpoint exactly.

Use Official SDK

The official OpenAI SDKs for Python, Node.js, Go, and Ruby work with this API. These libraries handle authentication and serialization automatically, reducing boilerplate code for streamers using no-code or low-code setups.

Example Code

Initialize the client with your key and base URL. Call audio.speech.create with your model, voice, input text, and desired response format. The method returns a binary response object.

Use the write_to_file method to save the generated audio directly to your local drive or streaming directory. This ensures reliable file handling for VOD archives.

  • Use response.write_to_file("output.mp3") to save the file.
  • Set base_url to https://api.playb77.com/v1.
  • Pass model="tts-1" or tts-1-hd.

Available Voices

Sound wave illustration for: Available Voices

VocalFlow provides eight preset voices designed for VTuber avatars and live stream overlays. Each voice is generated from licensed recordings (LibriTTS-R, CC BY 4.0) derived from LibriVox public-domain audiobook readings. Every audio file includes an inaudible watermark marking it as synthetic speech.

The API accepts one of eight voice identifiers: aria, nova, luna, sage, felix, milo, atlas, or orion. All voices support any of the 23 supported languages, eliminating the need to select different voices for different languages.

8 Preset Voices

Female voices include aria (warm, clear narrator), nova (bright, upbeat), luna (soft, storytelling), and sage (calm, instructional). Male options feature felix (energetic, promo), milo (friendly, conversational), atlas (neutral, news), and orion (deep, documentary).

Male and Female Options

Select voices based on your avatar’s personality or stream segment type. Use atlas for neutral news updates or milo for conversational chat interactions. Choose orion for deep documentary-style intros or nova for upbeat segment transitions.

Voice Selection Logic

Any voice can speak any of the 23 supported languages. If the language field is omitted, the system guesses the language from the text script (Latin defaults to English). For non-English Latin-script text, explicitly set the language parameter to ensure accurate pronunciation.

Supported Formats

Sound wave illustration for: Supported Formats

The API supports multiple audio formats to suit different workflow needs. You can select the output format by passing the response_format parameter in your request body. Accepted values are mp3, wav, opus, flac, and pcm. Each format serves a specific purpose depending on whether you prioritize file size, quality, or compatibility.

Choose mp3 for general streaming and VODs. Use wav for lossless quality during editing. opus offers efficient compression, while flac provides lossless compression without artifacts. Select pcm for raw uncompressed data.

MP3 Output

MP3 is the default and most widely compatible format. It provides good audio quality with small file sizes, making it ideal for VTuber VODs, live stream overlays, and emote reactions. Most streaming platforms and media players support MP3.

  • - Default format for most use cases
  • - Small file size for fast uploads
  • - Supported by all major streaming platforms

WAV Lossless

WAV provides uncompressed, high-quality audio. It is suitable for editing and VOD archiving where you need to preserve every detail. Use this format if you plan to further process the audio in a DAW or video editor.

  • - Uncompressed audio quality
  • - Ideal for editing workflows
  • - Larger file size than MP3

Opus and FLAC

Opus offers efficient compression with good quality, reducing bandwidth usage. FLAC provides lossless compression, preserving audio quality while reducing file size compared to WAV. Both formats are useful for specific storage or transmission needs.

  • - Opus: efficient compression
  • - FLAC: lossless compression
  • - Suitable for specific storage needs

Rate Limits

Sound wave illustration for: Rate Limits

Your API key allows 60 requests per minute. Before your first top-up, this limit is reduced to 10 requests per minute. Each request counts as one unit, regardless of text length or output format.

60 Requests Per Minute

The standard limit is 60 requests per minute per key. New accounts without a funded balance are capped at 10 requests per minute.

Queue Behavior

Requests are processed sequentially. If you exceed the rate limit, subsequent requests will wait in a queue until slots become available. Under heavy load, generation may take longer than usual, as short phrases typically take a few seconds and long texts generate at roughly real-time speed.

Retry Logic

Implement exponential backoff for 429 Too Many Requests responses. Do not send new requests while waiting in the queue, as this will increase latency. Failed requests are free, so retrying immediately after a failure (non-rate-limit error) is safe.

  • Wait 1 second, then double the wait time for each failed attempt.
  • Check the Retry-After header if provided.
  • Avoid polling the status endpoint; use the synchronous response.

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate request outcomes. If synthesis fails, the charge is returned in full, ensuring you only pay for successful audio generation. You can monitor request status through the response headers and body to handle failures gracefully in your stream overlay or VTuber bot.

Common Error Codes

A 4xx error indicates a client-side issue, such as an invalid API key or unsupported parameters. A 5xx error suggests a server-side problem. In these cases, the request was not processed, so no characters are deducted from your balance.

  • 401: Unauthorized (invalid or missing API key)

Retry Strategy

For transient errors like 503 Service Unavailable, implement an exponential backoff strategy. Wait briefly before retrying, as requests are processed sequentially and may queue under load. Avoid rapid-fire retries to prevent overwhelming the queue.

Character Limits

Each request supports up to 4096 characters of input text. If your script exceeds this limit, split the text into smaller chunks. Process each chunk separately and join the resulting audio files to create a continuous output for your VODs or live streams.

Error Handling

Long Text Handling

Sound wave illustration for: Long Text Handling

Generate clear speech for VODs and intros without hitting hard limits. The API processes text in chunks, ensuring your stream overlays and reactions stay synchronized with your content.

4096 Character Limit

Each API request accepts up to 4,096 characters, including spaces and punctuation. This limit applies per call, so you cannot send a full novel in one go. Short phrases generate in seconds, while longer texts take time proportional to their length.

Splitting Text

Divide your input into segments of 4,096 characters or fewer before sending requests. Ensure each segment is a complete sentence or logical phrase to avoid awkward pauses in the audio output. This prevents truncation and maintains natural flow.

Joining Audio Files

The API returns individual audio files for each request. You must concatenate these files client-side to create a single continuous track. This approach keeps memory usage low and allows for flexible post-processing in your streaming software.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Create your own virtual persona with animated avatars and start streaming to your audience today.

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. OpenAI API reference: create speech
  3. MDN: Web Speech API
  4. FFmpeg documentation
  5. TRON developer hub: TRC-20
  6. Node.js documentation
  7. openai-python on GitHub
  8. Creative Commons Attribution 4.0
  9. W3C WAI: making audio and video accessible
  10. Tether (USDT)
  11. openai-node on GitHub
  12. ISO 639 language codes

More on this site