API Documentation for Text-to-Speech Integration

By VocalPipe editorial team · Updated 2026-11-18

This documentation guides mobile app developers through integrating VocalPipe’s text-to-speech API. We provide concrete steps for generating speech, managing voices, and handling audio formats like MP3 and Opus directly within your application’s workflow.

You will learn how to authenticate requests, interpret error codes, and manage rate limits efficiently. The guide covers practical examples for splitting long texts and selecting the right voice preset to enhance your app’s user experience without heavy infrastructure.

API Documentation for Text-to-Speech Integration

Frequently asked questions

What is the base URL for the API?

Use https://api.playl44.com/v1 as your base URL. This allows you to send requests to the speech endpoint at /v1/audio/speech. The structure mirrors standard TTS APIs, making integration straightforward for mobile developers who need a reliable, predictable endpoint for generating audio from text inputs.

How do I authenticate my requests?

Include your API key in the Authorization header as a Bearer token: Authorization: Bearer tts-... You receive one active key per account. If needed, you can issue a new key at any time, which immediately invalidates the previous one, ensuring secure access for your mobile app.

Can I use the Python OpenAI SDK?

Yes. Since the request shape matches the OpenAI speech endpoint, you can use the official OpenAI SDKs by changing the base_url to https://api.playl44.com/v1 and providing your VocalPipe key. This allows you to leverage familiar libraries without writing custom HTTP clients for your mobile backend or scripts.

Which models are available?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and have the same price. You can choose either model depending on your quality preferences, as the generation process and cost remain identical regardless of which model you select for your text-to-speech requests.

What is the maximum text length?

Each request supports up to 4096 characters of input text. If your content exceeds this limit, you should split the text into smaller parts, generate audio for each, and join the resulting files. This approach ensures compatibility with the API’s constraints while delivering your full narrative.

How do I specify the language?

Pass the ISO language code in the language field. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin text, explicitly set the language to ensure accurate synthesis, as any voice can speak any of the 23 supported languages.

What happens if I exceed the rate limit?

You are limited to 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load, your request may wait in a queue. Exceeding the limit returns a 429 error and does not incur extra charges, but may increase latency for your mobile users.

Do I need to handle streaming?

No, the API does not support streaming or WebSocket connections. You send a POST request and receive the complete audio file in the response. This synchronous model simplifies implementation for mobile apps, as you do not need to manage partial audio buffers or real-time data streams.

Is the audio format selectable?

Yes, you can choose from mp3, wav, opus, flac, or pcm via the response_format field. Selecting the appropriate format helps optimize file size and compatibility for your mobile platform, ensuring efficient storage and playback while maintaining the quality required for your application’s audio features.

How do I detect errors in mobile?

Check the HTTP status code and response body for error details. Failed requests are free, with charges returned in full. Implementing standard error handling for network issues or API errors ensures your app gracefully manages synthesis failures without impacting user experience or incurring unexpected costs.

Can I use the same key for iOS and Android?

Yes, your single API key works across all platforms. Since authentication relies on the Bearer token in the header, you can use the same key for both iOS and Android apps. This simplifies management, as you do not need separate keys for different device types.

Do you provide a webhook for completion?

No, the API is synchronous. You receive the audio file directly in the response body. There are no webhooks for completion notifications. This design eliminates the need for additional infrastructure to track job status, making it easier to integrate into standard mobile app request-response cycles.

How is the audio returned?

The generated audio is returned directly in the HTTP response body as the requested format. It is not stored on our servers. This immediate delivery allows your mobile app to play or save the audio file instantly, providing a seamless experience for your users without delay.

First request

curl

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

Start by creating an account at https://playl44.com/get-api-key/ using Google or your email. You will receive $0.50 of trial credit (valid for 7 days) if you sign in with Google; email accounts start with zero balance.

Once registered, access the dashboard to view your active API key, current balance, and usage statistics. This key authenticates all your requests to the API.

Generate key from dashboard

Generate key from dashboard

Your dashboard displays your unique API key immediately after signup. Copy this key to use in your mobile app's configuration. Each account holds one active key at a time.

  • Keys are visible in the dashboard under 'API Key'
  • Supports both Google Sign-In and email/password registration

Rotate keys if needed

Rotate keys if needed

You can generate a new key at any time from the dashboard. The previous key stops working immediately, ensuring no overlap in active credentials. This is useful if you suspect a key was exposed or need to reset access for a team.

First request with cURL

Sound wave illustration for: First request with cURL

Send your text to the speech endpoint and receive an audio file. This basic integration works with any HTTP client, making it easy to add voice to your mobile app without external dependencies.

The request combines the text, voice selection, and desired audio format into a single JSON payload. Authentication ensures only your account’s balance is charged for the synthesis.

POST to /v1/audio/speech

Direct your HTTP client to the speech endpoint. This POST request triggers the synthesis engine, which processes your input text and returns the generated audio file in the response body.

  • Endpoint: https://api.playl44.com/v1/audio/speech

JSON body structure

Include the model, input, voice, and response_format fields. The input text must not exceed 4096 characters. You can also optionally specify speed and language to customize the output.

  • model: "tts-1" or "tts-1-hd"
  • input: your text string
  • voice: e.g., "aria", "nova"
  • response_format: "mp3", "wav", etc.

Authorization header

Include your API key in the header. This key identifies your account and deducts credits from your balance upon successful synthesis. Generate or rotate this key via your dashboard.

  • Header: Authorization: Bearer tts-<your-key>

Using OpenAI SDKs

Sound wave illustration for: Using OpenAI SDKs

VocalPipe mirrors the OpenAI Speech endpoint shape, allowing mobile teams to reuse existing OpenAI SDKs with minimal changes. You simply point the library at our API base URL instead of OpenAI’s servers.

This approach lets you keep your current code structure while benefiting from our pricing and voice options. It is a drop-in replacement for standard text-to-speech integrations.

Change base_url to api.playl44.com

Update your SDK configuration to use https://api.playl44.com/v1 as the base URL. This directs all requests to our infrastructure while maintaining the standard OpenAI request shape.

  • Base URL: https://api.playl44.com/v1
  • Keep your API key in the Authorization header

Use official OpenAI libraries

Any official OpenAI SDK (Python, Node.js, etc.) works out of the box. No custom wrapper or proprietary client is required for integration.

  • Python: openai package
  • JavaScript: openai npm package

Standard SDK methods

Call the standard audio.speech.create method with your model, input text, and voice selection. The SDK handles serialization and authentication automatically.

  • Method: audio.speech.create
  • Params: model, input, voice, response_format

Available voices

Sound wave illustration for: Available voices

VocalPipe offers eight distinct voice presets, all capable of speaking any of the 23 supported languages. You can mix and match voices regardless of the language, allowing for flexible localization without needing separate voice models for each market.

Each voice is derived from licensed recordings, ensuring high-quality synthetic speech. All generated audio files include an inaudible watermark to identify them as AI-generated content, which is useful for compliance and transparency in your mobile app.

List of 8 voice IDs

The API supports eight specific voice models, categorized by gender and tone. You can choose from four female voices and four male voices to suit your app’s personality.

All voices support the full range of 23 languages, including Arabic, Chinese, English, German, Japanese, Spanish, and others listed in our documentation. If you do not specify a language, the system guesses it based on the text script.

  • Female: aria (warm, clear narrator), nova (bright, upbeat), luna (soft, storytelling), sage (calm, instructional)

Gender and style tags

Each voice has a distinct character. Aria provides a warm, clear narration style suitable for audiobooks. Nova offers a bright, upbeat tone ideal for quick notifications or marketing snippets.

Luna is soft and storytelling-focused, while Sage delivers a calm, instructional tone perfect for educational apps. Felix is energetic and promo-oriented, Milo is friendly and conversational, Atlas is neutral for news, and Orion is deep for documentary styles.

Selecting the right voice

Choose a voice that matches your app’s user experience. For a news app, Atlas provides a neutral, professional tone. For a children’s app, Luna’s soft style might be more engaging.

Remember that any voice can speak any supported language. If you are generating text in a non-English Latin script, explicitly set the language field to ensure correct pronunciation, as the default guess is English.

Response formats

Sound wave illustration for: Response formats

The API returns audio in five formats: mp3, wav, opus, flac, or pcm. Each balances quality, file size, and compatibility differently, letting you optimize for your app’s specific constraints. Choose the format that best fits your target devices and network conditions.

Selecting the right format ensures efficient data usage and smooth playback. While all formats are supported, some are better suited for mobile environments where bandwidth and storage matter. Understanding these differences helps you deliver a better user experience without unnecessary complexity.

MP3, WAV, Opus, FLAC, PCM

MP3 offers broad compatibility with small file sizes, making it ideal for most mobile apps. WAV provides uncompressed quality but results in larger files. Opus is efficient for low-bandwidth scenarios, FLAC preserves lossless quality, and PCM delivers raw audio data.

PCM is useful when you need exact sample data, while FLAC suits high-fidelity needs. Opus is efficient for low-bandwidth scenarios, and WAV is suitable for local playback where file size is less critical. MP3 remains the safest default for general use.

  • mp3: Best for general mobile use
  • wav: Uncompressed, high quality
  • opus: Efficient for streaming
  • flac: Lossless compression
  • pcm: Raw audio data

Choosing format for mobile

For mobile apps, MP3 is often a good choice due to its balance of quality and size. Opus is another strong option for efficient data usage, especially on slower networks. WAV and FLAC are better for local playback where bandwidth is not a concern.

Consider your target audience’s devices and network conditions. If your app is used in areas with limited connectivity, prioritize formats like MP3 or Opus. For high-quality audio experiences, WAV or FLAC may be preferable.

  • MP3: General mobile use
  • Opus: Low-bandwidth efficiency
  • WAV/FLAC: Local playback quality

Audio file size differences

File sizes vary significantly by format. MP3 and Opus produce smaller files, reducing download times and storage usage. WAV and FLAC files are larger due to uncompressed or lossless compression. PCM files are the largest, as they contain raw data.

When processing long texts, smaller formats like MP3 or Opus can save significant bandwidth. For short phrases, the difference may be negligible, but it’s still worth considering for large-scale usage. Choose based on your app’s specific needs.

  • MP3/Opus: Smaller files
  • WAV/FLAC: Larger, high-quality files
  • PCM: Largest, raw data
Response formats

Rate limits

Sound wave illustration for: Rate limits

Understanding rate limits helps you maintain a smooth audio playback experience without unexpected interruptions. Our system processes requests sequentially, meaning your app may occasionally wait in a queue during high load.

Efficient limit management ensures your users hear clear speech without significant delays, keeping your app responsive even when generating longer text segments.

60 requests per minute

Each API key supports a standard limit of 60 requests per minute. This allows your mobile app to generate multiple short phrases or update text-to-speech content efficiently without hitting a bottleneck. If you exceed this limit, the API returns a 429 status code.

Since requests are processed one after another, under heavy load a single request may wait in a queue. This is normal and does not indicate a failure; the request will complete once the queue clears.

10 requests before top-up

New accounts or those without a recent top-up start with a reduced limit of 10 requests per minute. This ensures fair usage while you verify your integration. Once you add funds via USDT (TRC-20), your limit immediately increases to the full 60 requests per minute.

This lower initial cap helps prevent accidental spam from new integrations. You can monitor your current tier and usage directly in the dashboard alongside your balance and character count.

Handling 429 errors

When you receive a 429 Too Many Requests error, your app should pause and retry. Implement an exponential backoff strategy to avoid flooding the API again immediately. This is crucial for mobile apps where network conditions can vary.

Do not retry instantly. Wait a few seconds before attempting the request again. Since each request is processed sequentially, waiting ensures you respect the queue and avoid further throttling. This keeps your user experience smooth and predictable.

Error handling

Sound wave illustration for: Error handling

The API uses standard HTTP status codes to indicate request success or failure. Understanding these responses helps your app handle issues gracefully without crashing. Most errors are temporary and can be retried safely.

When synthesis fails, the charge is returned in full. Your app should parse the JSON response to determine the specific cause and decide whether to retry or prompt the user.

Common HTTP status codes

Use 200 for success. 400 indicates invalid input, such as text exceeding 4096 characters or an invalid voice ID. 401 means your API key is missing or incorrect. 429 signals rate limit exceeded, and 500 denotes a server-side error during synthesis.

  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 429: Rate Limit

JSON error responses

Errors return a JSON object with a code and message. This structure allows your mobile app to parse the error precisely. Check the message field for specific details like character limits or unsupported formats.

Retry strategies for mobile

Implement exponential backoff for 429 and 500 errors. Do not retry 400 errors as they will likely fail again. For 429 errors, wait until the rate limit resets (60 requests/minute). Always check the balance before retrying large batches.

Long text splitting

Sound wave illustration for: Long text splitting

The API enforces a strict 4096-character limit per request. This constraint applies to the raw text input, including spaces and punctuation. Requests exceeding this boundary will fail, so your mobile app must handle segmentation before sending data to the endpoint.

4096 character limit

Each synthesis request accepts a maximum of 4096 characters. This limit is fixed and does not change based on voice or format. Text beyond this threshold is rejected, so you must segment longer content in your app logic before making the API call.

Splitting text in app

Split your input text into chunks of up to 4096 characters. Ensure you do not break words arbitrarily; consider splitting at sentence boundaries or whitespace to maintain natural audio transitions. Send each chunk as a separate POST request to /v1/audio/speech.

Joining audio segments

Once you receive audio files for each chunk, combine them in your app. The API does not handle concatenation, so you must merge the resulting files client-side. For best results, use libraries that support seamless joining of your chosen format (e.g., MP3 or WAV).

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Our mobile apps must deliver seamless user experiences that keep product teams engaged and satisfied daily.

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-node on GitHub
  3. openai-python on GitHub
  4. curl documentation
  5. W3C WAI: making audio and video accessible
  6. LibriVox public-domain audiobooks
  7. ISO 639 language codes
  8. IETF RFC 7845: Ogg Opus
  9. Tether (USDT)
  10. TRON developer hub: TRC-20
  11. LibriTTS-R corpus (OpenSLR 141)
  12. Creative Commons Attribution 4.0

More on this site