Cloud TTS API: Quickstart and Integration Guide

By WebSpeech Notes editorial team · Updated 2026-11-18

This guide helps indie developers integrate WebSpeech Notes’ cloud text-to-speech API into web applications. You will learn how to authenticate with a Bearer token, structure JSON requests, and handle responses for audio synthesis. The documentation covers practical details like rate limits, voice selection, and error handling, ensuring you can build reliable voice features without guesswork.

Readers will find concrete examples for the OpenAI SDK compatibility, including base URL configuration and code snippets. We explain how to manage keys, understand pricing per character, and troubleshoot common issues. This resource is designed for developers who need clear, factual information to implement TTS efficiently in their projects.

Cloud TTS API: Quickstart and Integration Guide

Frequently asked questions

How do I authenticate my API requests?

Include your unique API key in the request header as Authorization: Bearer tts-.... Each account holds one active key at a time. If you issue a new key, the previous one stops immediately. This ensures secure access to the speech synthesis endpoint.

What is the maximum text length per request?

Each request supports up to 4096 characters of input text. For longer content, split your text into chunks of this size and join the resulting audio files. This limit applies to the input field in the JSON body, ensuring consistent processing times and predictable billing calculations for your application.

Can I change the speed of the speech?

Yes, you can adjust the playback speed between 0.25 and 4.0 using the speed parameter. This allows you to slow down narration for clarity or speed up content for brevity. The default speed is 1.0.

Which audio formats are supported?

You can choose from mp3, wav, opus, flac, or pcm via the response_format field. MP3 offers efficient compression, while WAV and FLAC provide lossless quality. PCM is raw audio data. Select the format that best fits your storage constraints and playback requirements for the generated speech files.

How do I list available voices?

Send a GET request to /v1/voices to retrieve all available voice presets, languages, and formats. This endpoint provides the necessary metadata to configure your application correctly. You can then select from eight distinct voices, including female and male options.

What happens if I exceed the rate limit?

The standard limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a lower limit of 10 requests per minute until the first top-up. Exceeding limits does not incur extra charges but may delay audio generation.

Do I need to install a specific SDK?

No specific SDK is required. You can use the official OpenAI SDKs by changing the base_url to https://api.playv57.com/v1. Alternatively, use any standard HTTP client to send JSON requests. This flexibility allows integration with existing infrastructure without needing to install proprietary libraries or manage complex dependencies.

Is the API endpoint stable?

The endpoint https://api.playv57.com/v1/audio/speech uses a standard versioned path. Requests follow a consistent JSON shape similar to OpenAI’s speech endpoint. No SLA is guaranteed. Use the documented fields to ensure compatibility across updates without breaking changes.

Can I send multiple texts in one request?

No, each request processes a single input string up to 4096 characters. To generate audio for multiple texts, send separate requests. You can parallelize these requests if your rate limit allows, or process them sequentially. This design ensures precise control over each audio segment’s parameters and formatting.

How do I handle audio file responses?

The API returns the audio file directly in the response body. Save this binary data to your desired storage or stream it to the user. The file includes an inaudible watermark marking it as synthetic. Ensure your client handles the specific response_format you requested, such as MP3 or WAV.

What is the default voice if none is specified?

If you do not specify a voice, the system uses a default voice. The available voices include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Explicitly setting the voice ensures consistent output. Defining the voice parameter is recommended for predictable results.

Can I specify a language explicitly?

Yes, use the optional language field with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate pronunciation for non-English texts.

Are there any version constraints?

The API uses version v1 in the endpoint path. Models tts-1 and tts-1-hd are supported. There are no complex version constraints beyond the standard API structure. Ensure your client sends requests to the correct base URL. The endpoint format remains consistent, allowing straightforward integration without frequent updates.

How do I test the API before buying?

Sign up with Google to receive a $0.50 free trial credit, valid for 7 days. This allows approximately 50,000 characters of generation. You can test voices, formats, and speed settings without immediate payment. Email-based accounts start without this trial credit, so consider using Google sign-in for initial testing.

First request

curl

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

Authentication is handled via a Bearer token passed in the Authorization header. This single key grants access to all endpoints and is tied to your account balance.

Bearer token in header

Bearer token in header

Include Authorization: Bearer tts-... in every request. The token authenticates your identity and deducts usage from your available credit.

One active key per account

One active key per account

Each account maintains only one active API key at a time. This simplifies credential management for indie developers and small teams.

Revoke and issue new keys

You can issue a new key at any time from the dashboard. The previous key stops working immediately, ensuring no overlap or security gaps.

  • No downtime during rotation
  • Immediate invalidation of old key
  • Manage keys via /get-api-key/

Speech Endpoint

Sound wave illustration for: Speech Endpoint

The core of the API is the speech generation endpoint. You send text data to this specific route to receive synthesized audio files. It follows the same request shape as the OpenAI speech endpoint, allowing you to use standard HTTP clients or the official OpenAI SDK by simply adjusting the base URL.

This endpoint handles the conversion of your input text into audio. It is designed for reliability and straightforward integration into web applications and scripts.

POST /v1/audio/speech

Send a POST request to https://api.playv57.com/v1/audio/speech. This is the only endpoint required for generating audio files from text inputs.

The endpoint accepts standard JSON payloads and returns binary audio data directly in the response body.

JSON request body

The request body must include the input text (up to 4096 characters), a model (tts-1 or tts-1-hd), and a voice preset. Optional fields include response_format, speed, and language.

Ensure you provide a valid API key in the Authorization header. The system processes requests sequentially, so longer texts may queue under load.

  • model: "tts-1" or "tts-1-hd"
  • input: string, max 4096 chars
  • voice: one of 8 presets
  • response_format: mp3, wav, opus, flac, pcm
  • speed: 0.25–4.0
  • language: optional ISO code

Returns audio file

On success, the API returns the audio file in the requested format. Failed requests are free, meaning no charge is applied if synthesis fails.

You can save the response directly to a file or pass it to your application's audio player.

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts text up to 4,096 characters per request. For longer content, split the text into chunks and join the resulting audio files. This limit applies to every call, regardless of the model chosen.

Model selection (tts-1, tts-1-hd)

Choose between "tts-1" and "tts-1-hd". Both use the same engine and pricing, so the decision depends on your audio quality preference rather than cost differences.

Input text limit

Send up to 4,096 characters in the input field. Spaces and punctuation count toward this limit. If your content exceeds this, process multiple requests and concatenate the output files.

Voice and language settings

Select one of eight preset voices, such as aria or atlas. You can optionally specify a language ISO code. If omitted, the system guesses the language, defaulting to English for Latin script text.

Setting the language explicitly is recommended for non-English Latin-script inputs to ensure accurate pronunciation.

Response Formats

Sound wave illustration for: Response Formats

The API returns synthesized audio in the requested format, allowing you to choose the optimal balance between file size and quality for your web app. All formats are delivered as binary data in the response body, ready to be saved or passed to the user’s player.

Choosing the right format ensures efficient bandwidth usage and broad compatibility across different devices and browsers without requiring additional conversion steps on your server.

MP3 support

MP3 is the default and most widely supported format for web playback. It offers a good balance between audio quality and file size, making it ideal for general use cases where storage efficiency matters.

  • Compatible with all major browsers

WAV support

WAV provides uncompressed, high-fidelity audio. Use this format when you need maximum quality for professional applications or when further processing of the audio file is required without compression artifacts.

  • Uncompressed audio quality

OPUS and FLAC options

OPUS offers superior compression efficiency, ideal for mobile data conservation. FLAC provides lossless compression, preserving exact audio quality while reducing file size compared to WAV, suitable for archival purposes.

  • Optimized for mobile data
  • Lossless audio preservation

Rate Limits

Sound wave illustration for: Rate Limits

Rate limits protect service stability during peak usage. Each API key allows up to 60 requests per minute once your account is funded. This limit applies per key, so you can manage throughput by distributing requests across multiple keys if needed.

60 requests per minute

Once your balance is active, you can send 60 synthesis requests per minute. This throughput is sufficient for most batch processing or moderate real-time applications. Requests are processed sequentially, so high concurrency may introduce slight delays.

10 requests before top-up

New accounts start with a restricted limit of 10 requests per minute. This allows you to verify the service quality before committing funds. You can top up via USTRC20 at any time to unlock the full 60 requests/minute capacity.

Queued processing

Under heavy load, requests may wait in a queue before synthesis begins. This ensures fair resource distribution among all users. You should implement retry logic with exponential backoff in your client code to handle transient delays gracefully.

Rate Limits

Voices List

Sound wave illustration for: Voices List

Retrieve available voices, supported languages, and pricing tiers with a simple GET request. The /v1/voices endpoint provides a static list of all 8 presets, allowing you to verify availability before generating audio. This metadata includes the voice ID, gender, and style description, ensuring you select the right tone for your application.

GET /v1/voices endpoint

Send a GET request to https://api.playv57.com/v1/voices with your Bearer token. The response returns a JSON array of voice objects, detailing their capabilities and supported languages. This endpoint is ideal for populating dropdown menus in your UI dynamically.

8 preset voices

Choose from four female and four male voices, each designed for specific use cases. Options range from the warm narration of aria to the energetic promo style of felix. All voices can speak any of the 23 supported languages, allowing for flexible multilingual content.

  • Aria: Warm, clear narrator
  • Nova: Bright, upbeat
  • Luna: Soft, storytelling
  • Sage: Calm, instructional
  • Felix: Energetic, promo
  • Milo: Friendly, conversational

Voice metadata details

Each voice object includes the ID required for the voice parameter, along with gender and style tags. The response also confirms supported response formats and language capabilities. Use this data to map UI labels to the correct API IDs, ensuring seamless integration without manual lookup tables.

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate request success or failure. Understanding these codes helps you implement robust retry logic in your web applications without unnecessary delays or repeated failures.

Standard HTTP errors

Use 4xx codes for client-side issues like authentication failures or malformed JSON. Use 5xx codes for internal server errors that you can safely retry after a short delay.

Invalid input responses

If your text exceeds 4096 characters or specifies an unsupported voice, the API returns a clear error message. Ensure you validate input length and voice IDs before sending requests to avoid wasted API calls.

  • Check character count against the 4096 limit
  • Verify voice names against the /v1/voices endpoint

Rate limit exceeded messages

Exceeding 60 requests per minute returns a 429 status code. New accounts start with a 10 requests per minute limit until the first top-up is processed. Implement exponential backoff to handle these throttles gracefully.

SDK Integration

Sound wave illustration for: SDK Integration

We use the official OpenAI SDKs by simply redirecting the base URL. This allows you to leverage familiar client libraries without learning a new interface, ensuring smooth integration for indie developers already using standard TTS patterns.

OpenAI SDK compatibility

Our API mirrors the request shape of the OpenAI speech endpoint. You can use the same SDKs, sending JSON bodies with model, input, voice, and format fields. This compatibility reduces boilerplate code and testing time for your web apps.

Base URL configuration

Point your SDK client to https://api.playv57.com/v1. Replace the default OpenAI base URL with this domain. Ensure your Authorization header includes your tts-... bearer token for authentication.

Example code snippet

Here is a minimal Python example using the OpenAI SDK. It sends a short text and receives the audio bytes directly, ready for playback or storage in your application.

  • import openai
  • client = openai.OpenAI(base_url="https://api.playv57.com/v1", api_key="tts-...")
  • response = client.audio.speech.create(model="tts-1", voice="nova", input="Hello world")
  • response.stream_to_file("output.mp3")

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Creating games alone is hard work but the freedom to follow your creative vision makes every late night worth it.

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. Python documentation
  3. ISO 639 language codes
  4. MDN: Web Speech API
  5. FFmpeg documentation
  6. curl documentation
  7. openai-node on GitHub
  8. openai-python on GitHub
  9. Creative Commons Attribution 4.0
  10. OpenAI API reference: create speech
  11. LibriVox public-domain audiobooks
  12. LibriTTS-R corpus (OpenSLR 141)

More on this site