TTS API Documentation: Quickstart, cURL, and SDK Guide

By WordCaster editorial team · Updated 2026-11-18

This guide provides the essential reference for integrating the WordCaster text-to-speech API into your applications. It covers authentication, available endpoints, and request parameters with concrete cURL examples. You will also find instructions for using the OpenAI SDK with our compatible base URL, ensuring a smooth setup for indie developers and no-code builders who need reliable audio generation without complex infrastructure.

The documentation details how to handle response formats like MP3 and WAV, manage rate limits, and interpret error codes. It explains key rotation, voice selection, and language support across 23 languages. Whether you are generating short phrases or long-form content, this page gives you the specific technical details needed to convert text into audio efficiently using a transparent, pay-as-you-go model.

TTS API Documentation: Quickstart, cURL, and SDK Guide

Frequently asked questions

What is the API endpoint?

Send a POST request to https://api.playtoto155.com/v1/audio/speech with a JSON body containing your text and parameters. You can also use GET /v1/voices to list available voices and GET /v1/models to check model details. This endpoint structure mirrors the OpenAI speech API for easy integration.

How do I authenticate?

Include your API key in the request header as Authorization: Bearer tts-... . Each account holds one active key; issuing a new one immediately invalidates the old one. You can generate and view your key on the /get-api-key/ page after signing in with Google or email.

Which models are available?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing structure. Select either based on your quality needs, as the underlying synthesis process is identical. The model parameter is required in your JSON request body to specify which version to use.

What is the character limit?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, split your content into chunks of 4096 characters or less and join the resulting audio files. Failed requests do not consume this limit or incur charges.

How do I set the language?

Pass the optional language parameter with an ISO code, such as en, es, or de. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accuracy for non-English Latin-script texts like French or Dutch.

Can I change the speed?

Yes, use the speed parameter with a value between 0.25 and 4.0. The default speed is 1.0. Adjusting this allows you to make speech faster or slower to fit your project’s timing needs. This parameter works with all available voices and models without affecting audio quality significantly.

What happens if I exceed rate limits?

The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. If you exceed this, requests may queue or fail. Failed requests are free: if synthesis fails, the charge is returned in full.

Does the API return metadata?

The response returns the generated audio file directly. Request metadata like time, characters, and status is kept for billing purposes but is not included in the audio response. You can track usage and balance on the /get-api-key/ page. Generated audio is not stored after the response.

How do I handle large texts?

Split your text into parts of up to 4096 characters each. Send each part as a separate request and join the resulting audio files. This ensures you stay within the character limit per request. The system processes requests sequentially, so plan your queue accordingly for long documents.

Is the OpenAI SDK compatible?

Yes, the endpoint shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playtoto155.com/v1 and using your site’s key. This allows you to leverage existing code and libraries without significant refactoring for your text-to-speech integration.

What audio formats are supported?

You can choose from mp3, wav, opus, flac, and pcm via the response_format parameter. Select the format that best suits your application’s requirements. All formats are generated from the same engine. The choice does not affect the price or the character count charged to your account.

How do I rotate my API key?

Issue a new key from the /get-api-key/ page. The new key becomes active immediately, and the old one stops working at once. This ensures secure access management. You can generate a new key as often as needed without any additional cost or downtime for your applications.

What is the default voice?

You must provide a voice parameter from the eight presets. Common choices include aria for narration or atlas for news. If you omit the voice parameter, the behavior depends on the SDK implementation, but specifying it is recommended.

Can I use custom voices?

No, custom voice cloning is not offered. You must choose from the eight available presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices are based on licensed recordings from LibriTTS-R and LibriVox. You cannot upload your own voice or design custom voices for your projects.

First request

curl

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

The WordCaster API uses standard Bearer token authentication. Include your unique API key in the request header as Authorization: Bearer tts-... for every call.

Each account maintains one active key. You can generate a new key at any time, and the previous key becomes invalid immediately.

Bearer token usage

Bearer token usage

Pass your key via the Authorization header. The format is Bearer tts-<your-key>. This works with the OpenAI SDK by setting the base URL to https://api.playtoto155.com/v1.

Key management

Key management

Your key is visible on the /get-api-key/ dashboard alongside your balance. There is no limit to how many keys you can issue, but only the most recently generated one remains active.

Key rotation

Generate a new key from your dashboard when needed. The old key stops working instantly, ensuring no overlap or confusion during deployment changes.

Endpoints

Sound wave illustration for: Endpoints

The API exposes three primary endpoints for generating audio, listing available voices, and checking model versions. Each endpoint follows a standard RESTful pattern, allowing you to integrate directly with your preferred HTTP client or SDK.

Requests are authenticated via the Authorization header. Ensure your key is valid and has sufficient balance before sending requests.

Speech generation endpoint

Send POST requests to /v1/audio/speech with your text and voice selection. The endpoint returns audio files in formats like MP3, WAV, or Opus. Text is limited to 4096 characters per request.

Failed requests do not incur charges. The API processes requests sequentially, so high load may introduce slight delays in generation.

  • Endpoint: POST /v1/audio/speech
  • Response formats: mp3, wav, opus, flac, pcm
  • Max input: 4096 characters

Voices list endpoint

Use GET /v1/voices to retrieve all 8 voice presets, supported languages, and available formats. This helps you select the right voice for your project before generating audio.

Voices are compatible with all listed languages. If no language is specified, the API guesses based on the text script.

  • Endpoint: GET /v1/voices
  • Returns voice IDs, languages, and formats
  • 8 presets: aria, nova, luna, sage, felix, milo, atlas, orion

Models endpoint

Call GET /v1/models to verify available TTS models. Currently, tts-1 and tts-1-hd are supported, offering the same engine and pricing.

This endpoint confirms the current model versions available for your account, ensuring compatibility with your integration.

  • Endpoint: GET /v1/models
  • Models: tts-1, tts-1-hd
  • Same engine and pricing

Request parameters

Sound wave illustration for: Request parameters

To generate speech, specify the model as "tts-1" or "tts-1-hd"; both use the same engine and pricing. Your input text must not exceed 4096 characters per request, with spaces and punctuation counted toward the limit. For longer texts, split the content and join the resulting audio files manually.

Model selection

The API accepts "tts-1" or "tts-1-hd" in the model field. Both options utilize the identical synthesis engine and incur the same charge of $10 per million characters, regardless of which model you select.

Input text limits

Each request supports a maximum of 4096 characters. This limit includes all spaces, punctuation, and special characters. If your text exceeds this length, divide it into smaller chunks and concatenate the resulting audio files after generation.

Voice and language fields

Select one of eight preset voices via the voice parameter. The language field is optional; if omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accuracy for non-English Latin-script inputs.

Available voices include female presets like Aria and Nova, and male presets like Felix and Milo. These voices can speak any of the 23 supported languages, including Arabic, Chinese, and Swahili.

  • Aria: warm, clear narrator
  • Felix: energetic, promo
  • Nova: bright, upbeat
  • Atlas: neutral, news

Response formats

Sound wave illustration for: Response formats

The API returns audio files in various formats depending on your response_format parameter. You can choose between MP3, WAV, Opus, or FLAC. Each format serves different use cases, from web delivery to high-fidelity storage.

Selecting the right format balances file size and quality. MP3 offers compression for easy web sharing, while WAV and FLAC preserve lossless audio for professional applications. Opus provides efficient compression for modern web standards.

MP3 output

MP3 is the default format for most web applications. It provides good audio quality with smaller file sizes. This makes it ideal for delivering speech to browsers or mobile apps without excessive bandwidth usage.

WAV output

WAV files are uncompressed and preserve the full audio quality. They are suitable for editing software or voiceovers requiring lossless audio. Use this format when you need the original audio data without compression artifacts.

Opus and FLAC support

Opus offers efficient compression suitable for modern web standards. FLAC provides lossless compression, reducing file size while maintaining audio integrity. Both formats are valid options depending on your storage and playback needs.

cURL example

Sound wave illustration for: cURL example

Use cURL to test the API directly from your terminal. The endpoint accepts a JSON payload with your text, chosen voice, and desired audio format.

This method is ideal for quick validation before integrating into your no-code workflows or custom scripts.

Basic request structure

Send a POST request to https://api.playtoto155.com/v1/audio/speech with your Bearer token in the header.

Include the model (e.g., "tts-1"), input text, voice, and response_format in the JSON body.

Ensure the text does not exceed 4096 characters.

  • Authorization: Bearer tts-...

Sending audio data

Specify your preferred output format such as mp3, wav, opus, or flac.

The API returns the audio file directly in the response body.

Longer texts should be split into chunks under the character limit to ensure proper synthesis.

Handling responses

A successful response contains the audio binary data.

If synthesis fails, the charge is returned, and an error code is provided.

Save the response body to a file to verify the generated speech.

cURL example

OpenAI SDK integration

Sound wave illustration for: OpenAI SDK integration

Integrate the WordCaster API into your projects using the official OpenAI SDKs by simply overriding the base URL. This allows you to leverage familiar code structures while accessing our text-to-speech engine without learning a new client library.

Configure the client to point to https://api.playtoto155.com/v1 and provide your API key. The SDK handles the HTTP requests, letting you focus on passing text and voice parameters.

Base URL configuration

Set the base_url parameter in your SDK client to https://api.playtoto155.com/v1. This directs all API calls to our infrastructure while maintaining compatibility with the standard OpenAI request shape.

Client initialization

Initialize the SDK client using your API key (starting with tts-...). Pass the configured base URL during initialization. This single setup step enables all subsequent speech generation calls.

Method usage

Call the audio.speech.create method with your text, selected voice, and desired format. The SDK returns the audio file directly, allowing you to save it immediately.

  • Use model set to "tts-1" or "tts-1-hd"
  • Specify voice from the 8 available presets
  • Set response_format to mp3, wav, opus, flac, or pcm

Error handling

Sound wave illustration for: Error handling

The API returns standard HTTP status codes to indicate success or failure. A 200 OK response contains the audio file, while other codes signal specific issues. You should check the response body for a JSON object containing a code and message field to understand the exact cause of the failure.

Handling errors gracefully ensures your application remains robust during synthesis. By checking for specific error codes, you can decide whether to retry the request, adjust parameters, or alert the user. This section outlines the most common issues you might encounter.

Common error codes

The API uses standard HTTP status codes. A 400 Bad Request indicates invalid parameters, while a 401 Unauthorized means your API key is missing or incorrect.

  • 400: Bad Request - Invalid JSON or missing fields.
  • 401: Unauthorized - Invalid or expired API key.
  • 500: Internal Server Error - Temporary service issue.

Rate limit errors

You are limited to 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a limit of 10 requests per minute until the first top-up is processed.

  • 429: Too Many Requests - Exceeded rate limit.
  • Retry-After header indicates seconds to wait.

Invalid input errors

Input text must not exceed 4096 characters. If the text is too long, you will receive a 400 error. Ensure the voice ID is one of the eight available presets and the language code is valid if specified.

  • 400: Text exceeds 4096 characters.
  • 400: Invalid voice ID or language code.

Rate limits

Sound wave illustration for: Rate limits

Understanding request volume helps you plan your integration strategy. Our API enforces strict rate limits to ensure stable performance for all users, especially when processing bulk text-to-speech tasks.

60 requests per minute

Each API key is limited to 60 requests per minute. This cap applies to the /v1/audio/speech endpoint and ensures fair usage across the network.

Initial 10 requests limit

New accounts without a top-up start with a lower limit of 10 requests per minute. This allows you to test the service before scaling up your usage.

Queue behavior

Requests are processed sequentially. Requests are processed sequentially, so under load a request may wait in a queue.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Each voice is based on licensed recordings from LibriVox, ensuring clear, professional audio without licensing complexity.

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. LibriTTS-R corpus (OpenSLR 141)
  3. W3C WAI: making audio and video accessible
  4. FFmpeg documentation
  5. ISO 639 language codes
  6. Tether (USDT)
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. IETF RFC 7845: Ogg Opus
  9. openai-node on GitHub
  10. OpenAI API reference: create speech
  11. LibriVox public-domain audiobooks
  12. Python documentation

More on this site