API Documentation: Get Started with Text-to-Speech

By VoiceScope editorial team · Updated 2026-11-18

This documentation outlines the integration workflow for freelance mobile developers using VoiceScope’s text-to-speech API on iOS and Android. You will find precise specifications for the POST /v1/audio/speech endpoint, including request body structures, supported audio formats, and voice selection parameters. The guide covers essential details like the 4096-character input limit, speed controls, and language overrides to ensure seamless audio generation within your app’s architecture.

Authentication relies on a single active Bearer token, with clear instructions for key rotation and rate limit handling. We provide ready-to-use cURL examples and SDK integration patterns compatible with OpenAI’s libraries, allowing you to switch the base URL and start generating speech immediately. Whether you need MP3, WAV, or FLAC output, this reference helps you implement high-quality TTS without managing infrastructure.

API Documentation: Get Started with Text-to-Speech

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playk444.com/v1. You send POST requests to https://api.playk444.com/v1/audio/speech for speech synthesis. Other endpoints like /v1/voices are also available at this base path. Ensure your Authorization header uses your Bearer token for authentication when making requests to these endpoints.

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.playk444.com/v1. Alternatively, you can use plain HTTP requests. We do not provide an official SDK, mobile SDK, or WordPress plugin, so standard HTTP libraries work perfectly.

How do I set the voice to Aria?

Include the field "voice": "aria" in your JSON request body. Aria is a female preset described as a warm, clear narrator. You can verify available voices by calling the GET /v1/voices endpoint. Aria supports all 23 languages, but you should specify the language for non-English text.

Can I send text longer than 4096 characters?

The API limits input text to 4096 characters per request. For longer texts, you must split the content into parts of up to 4096 characters. Generate audio for each part separately, then join the resulting audio files in your application. Each request counts toward your character usage and rate limits.

What happens if I send invalid JSON?

If the request body is invalid, the synthesis fails. Failed requests are free, meaning the charge is returned in full if a charge occurred. The API returns an error status code. Ensure your JSON structure matches the required fields: model, input, voice, and response_format to avoid errors.

Does the API return the audio file directly?

Yes, the generated audio is returned directly in the response body. The audio is not stored on our servers after generation. Supported formats include mp3, wav, opus, flac, and pcm. You can specify your preferred format using the response_format field in your request JSON body.

How do I handle rate limit errors?

The rate limit is 60 requests per minute per key (10 per minute before the first top-up). If you exceed this, you will receive a rate limit error. Process requests sequentially or implement exponential backoff. Requests are processed one after another, so under load, a request may wait in a queue.

Is the API compatible with OpenAI SDKs?

Yes, the request shape is the same as the OpenAI speech endpoint. You can use the official OpenAI SDKs by setting the base_url to https://api.playk444.com/v1. Use your VoiceScope API key for authentication. This allows you to integrate TTS into your existing OpenAI-based code with minimal changes.

Can I use the API with Android WebView?

Yes, you can use the API with Android WebView. Since the API is accessed via standard HTTP POST requests, it works in any environment that supports network calls. Ensure your WebView allows HTTPS requests and that you securely handle your API key to prevent unauthorized usage from your mobile app.

How do I rotate my API key?

You can issue a new API key from your account dashboard at any time. When a new key is issued, the old one stops working immediately. This ensures seamless rotation without downtime. Access your key management page to generate a new key and update your application configuration accordingly.

What is the default response format?

You can specify other formats like wav, opus, flac, or pcm using the response_format field. MP3 is suitable for most mobile applications due to its balance of quality and file size. Ensure your client can decode the chosen format correctly.

Does the API support streaming audio?

No, the API does not support streaming, WebSocket, or real-time partial audio. It returns the complete audio file in the response after synthesis is complete. Short phrases may take a few seconds, while longer texts take roughly real time. You must wait for the full response before playing audio.

How do I specify the French language?

Include the field "language": "fr" in your JSON request body. Although voices can speak any of the 23 supported languages, setting the language explicitly ensures correct pronunciation. If omitted, the API guesses the language, defaulting to English for Latin-script text. French is fully supported by all voices.

What are the valid speed values?

The valid speed range is 0.25 to 4.0. The default speed is 1.0. You can adjust this value using the speed field in your request body to make the speech faster or slower. Values outside this range will result in an error. Adjust speed to fit your app's user experience needs.

First request

curl

curl https://api.playk444.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.playk444.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.playk444.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 API Keys

Sound wave illustration for: Authentication and API Keys

To authenticate requests, include your API key in the Authorization header as a Bearer token: Authorization: Bearer tts-.... This key is issued when you sign in on /get-api-key/ and is required for all endpoints.

Bearer Token Format

Bearer Token Format

Use the exact string provided in your dashboard. The token starts with tts- and identifies your account for billing and rate limiting.

Single Active Key

Single Active Key

Each account has one active key. Issuing a new key immediately invalidates the previous one. Ensure your mobile app is updated before rotating.

Key Rotation Process

Generate a new key from the dashboard. Update your app’s configuration to use the new token. The old key stops working instantly, preventing overlap issues.

Endpoint: POST /v1/audio/speech

Sound wave illustration for: Endpoint: POST /v1/audio/speech

The /v1/audio/speech endpoint accepts POST requests to synthesize text into audio. Send your JSON payload with the required fields, including the text content, chosen voice, and desired output format. The API processes the request and returns the audio file directly in the response body.

Ensure you include the model identifier and language code if needed. The endpoint handles the conversion from text to speech, respecting your account’s rate limits and character constraints. Use this endpoint as the core of your mobile app’s audio generation workflow.

Request Body Structure

Send a JSON object with the following fields: model, input, voice, response_format, and optionally speed or language. The input field holds your text, up to 4096 characters. The voice field selects one of the 8 presets. Set response_format to mp3, wav, opus, flac, or pcm.

The speed parameter adjusts playback between 0.25 and 4.0. The language field is optional; if omitted, the system guesses from the script, defaulting to English for Latin text. Include your Bearer token in the Authorization header.

  • model: "tts-1" or "tts-1-hd"
  • input: string, max 4096 chars
  • voice: preset name (e.g., "aria")
  • response_format: mp3, wav, opus, flac, pcm
  • speed: float, 0.25–4.0
  • language: optional ISO code

Model Selection (tts-1/tts-1-hd)

Choose between tts-1 and tts-1-hd. Both models use the same underlying engine and pricing. Select tts-1-hd if you need higher fidelity. Both models use the same engine and price. The choice does not affect the character count or cost.

The API returns the audio file in the requested format. Both models support all 23 languages and 8 voices. There is no difference in voice options or language support between the two models.

Input Text Limit

Each request can contain up to 4096 characters. If your text exceeds this limit, split it into chunks and send multiple requests. Join the resulting audio files on the client side for seamless playback.

Character counting includes spaces and punctuation. The API processes requests sequentially, so under load, longer texts may experience slight delays. Ensure your app handles partial responses gracefully if a request fails.

Response Formats and Audio Output

Sound wave illustration for: Response Formats and Audio Output

The API returns synthesized audio as binary data within the HTTP response body. You receive the file directly, allowing immediate playback or storage without intermediate processing steps. This design keeps your mobile app’s network stack simple and reduces latency during audio loading.

Choose your output format based on your app’s storage constraints and playback requirements. We support common codecs for broad compatibility and high-fidelity needs alike.

Supported Formats (MP3, WAV, OPUS)

MP3 provides efficient compression for audio in mobile apps. WAV offers uncompressed quality for local playback where storage is not a constraint. OPUS delivers excellent compression at low bitrates, ideal for data-conscious users on mobile networks.

All formats preserve the voice characteristics and speed settings specified in your request. The binary data can be written directly to a file or piped to an audio player.

  • MP3: Standard compressed audio, widely supported.
  • WAV: Uncompressed, high-fidelity audio.
  • OPUS: Efficient compression for mobile data efficiency.

PCM Raw Audio

PCM returns raw 16-bit little-endian PCM data without any container wrapper. This format is useful when you need to process the audio samples directly or feed them into custom audio engines.

The raw data stream allows precise control over sample rates and channel configurations in your app’s audio pipeline.

  • Raw 16-bit little-endian PCM data.
  • No container overhead.
  • Ideal for custom audio processing.

FLAC Lossless

FLAC provides lossless compression, preserving every detail of the synthesized speech. This format is suitable for archival purposes or high-quality audio libraries where storage space is less critical than perfect fidelity.

The audio quality matches the original synthesis engine output exactly, ensuring no degradation during storage or transmission.

  • Lossless compression.
  • Perfect audio fidelity.
  • Suitable for archival storage.

Voice Selection and Parameters

Sound wave illustration for: Voice Selection and Parameters

The API accepts eight distinct voice presets, categorized by gender and tonal character. Female options include Aria (warm narrator), Nova (bright), Luna (soft storytelling), and Sage (calm instruction). Male voices offer Felix (energetic promo), Milo (friendly conversation), Atlas (neutral news), and Orion (deep documentary). Each voice supports all 23 listed languages, allowing flexible casting for mobile app interfaces.

Voice selection is determined by the voice parameter in the request body. These presets are derived from licensed LibriTTS-R recordings and LibriVox public-domain audiobook readings, ensuring consistent quality across iOS and Android deployments without requiring complex infrastructure management.

Voice Presets List

Select from eight licensed voices optimized for clear mobile audio playback. The system does not support custom voice cloning or emotion tags; choose the preset that matches your app’s tone.

All voices can speak any of the 23 supported languages. If the language field is omitted, the system guesses the language based on the script, defaulting to English for Latin text.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Speed Control (0.25–4.0)

Adjust speech pace using the speed parameter, which accepts values between 0.25 and 4.0. The default speed is 1.0. Lower values slow the narration, while higher values accelerate it, useful for quick notifications or detailed explanations.

Speed adjustments affect generation time slightly but remain within typical real-time performance limits for most text lengths.

Language Override

Use the optional language field (ISO code) to force a specific language. This is critical for non-English Latin-script text to prevent incorrect language detection. For example, specify 'fr' for French or 'de' for German.

If you do not set this field, the API guesses the language from the input script. Unsupported languages like Vietnamese or Thai are not supported.

Rate Limits and Throttling

Sound wave illustration for: Rate Limits and Throttling

VoiceScope enforces a strict rate limit of 60 requests per minute per API key. This ceiling applies to all synthesis endpoints and ensures stable performance for freelance developers managing concurrent audio generation tasks in their mobile applications.

New keys start with a lower limit of 10 requests per minute until the first top-up is processed.

60 Requests Per Minute

Once your account is funded, the standard limit is 60 requests per minute. This allows for efficient batching of text segments during app initialization or background processing without hitting throttling errors immediately.

  • Standard limit for active, funded accounts.
  • Applies per API key, not per user.

10 RPM for New Keys

Freshly issued keys begin with a 10 requests per minute limit. This constraint lifts automatically within minutes after your first USDT top-up is confirmed on the TRON network.

Queue Behavior

Requests are processed sequentially. If the queue is full or the limit is reached, new requests wait briefly rather than failing immediately. This ensures that no audio generation is lost during brief traffic bursts, though latency may increase under heavy load.

  • Requests are queued, not dropped, when limits are temporarily exceeded.
  • Latency increases if the queue backs up.
Rate Limits and Throttling

Error Handling and Status Codes

Sound wave illustration for: Error Handling and Status Codes

The API returns specific HTTP status codes to indicate request outcomes. Understanding these errors helps you debug integration issues quickly, especially when handling mobile app network conditions or invalid payloads during synthesis jobs.

400 Bad Request

Returned when the request body is malformed. Common causes include providing an invalid voice name or using unsupported parameters.

401 Unauthorized

Returned when the Bearer token is missing, expired, or invalid. Ensure your Authorization header matches the key format Bearer tts-.... If your key was rotated, the old one stops immediately.

429 Too Many Requests

Returned when you exceed the rate limit of 60 requests per minute. New keys start with a 10 RPM limit until the first top-up. Requests may also queue during high load, causing delays before the error triggers.

Example: cURL Command

Sound wave illustration for: Example: cURL Command

The API accepts standard JSON bodies. You send text, select a voice, and receive an audio file. This section demonstrates three common scenarios using cURL.

Each command uses the base URL https://api.playk444.com/v1. Replace YOUR_API_KEY with your actual token from /get-api-key/.

Basic French Request

Generate a short MP3 file using the Nova voice for French text.

The API guesses the language from the script, but you can explicitly set it.

  • curl -X POST https://api.playk444.com/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • `-d '{"model": "tts-1", "input": "Bonjour le monde", "voice": "nova", "response_format": "mp3"}'`

HD Model Request

Use the HD model for higher quality audio. The price remains the same per character.

This is useful for high-fidelity mobile app narration.

  • curl -X POST https://api.playk444.com/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • `-d '{"model": "tts-1-hd", "input": "High quality audio generation test", "voice": "atlas", "response_format": "wav"}'`

Speed Adjustment

Adjust the playback speed between 0.25 and 4.0. This helps match voice timing to UI animations.

Faster speeds may reduce naturalness; slower speeds may increase latency.

  • curl -X POST https://api.playk444.com/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • `-d '{"model": "tts-1", "input": "Speak slowly for clarity", "voice": "sage", "speed": 0.75, "response_format": "mp3"}'`

SDK Integration (OpenAI Compatible)

Sound wave illustration for: SDK Integration (OpenAI Compatible)

VoiceScope’s API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing SDK clients by simply pointing them to our base URL. This compatibility means you can integrate TTS into your iOS or Android apps by reusing existing SDK clients.

Base URL Configuration

Update your SDK’s base URL to https://api.playk444.com/v1. Ensure your Authorization header uses the Bearer tts-... key format. The official OpenAI SDKs work directly with this configuration, treating our endpoint as a drop-in replacement for standard speech synthesis calls.

Python SDK Example

Install the openai package. Initialize the client with your VoiceScope API key and the custom base URL. Call client.audio.speech.create() with your desired model, input text, and voice preset. The SDK handles the request and returns the audio binary stream or file object for immediate playback in your mobile interface.

Node.js SDK Example

Import the OpenAI client and configure it with your VoiceScope key and base URL. Invoke the audio speech method with parameters like model: "tts-1", voice: "nova", and your input text. The response provides the audio data, which you can pipe directly to your app’s audio player or save as a file for offline caching.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The underlying voice models are trained on data from LibriTTS-R, which aggregates public-domain audiobook readings from LibriVox.

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. LibriVox public-domain audiobooks
  3. Tether (USDT)
  4. OpenAI API reference: create speech
  5. TRON developer hub: TRC-20
  6. curl documentation
  7. Creative Commons Attribution 4.0
  8. IETF RFC 7845: Ogg Opus
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. MDN: Web Speech API
  11. openai-node on GitHub
  12. FFmpeg documentation

More on this site