How to Integrate TTS into a Meditation App?

By FitVoice editorial team · Updated 2026-11-18

This guide explains how to integrate FitVoice’s text-to-speech API into meditation and fitness applications. We cover the complete workflow from signing up for a free trial to deploying calm synthetic voices like Luna or Sage. You will learn to convert scripts into audio files using standard HTTP requests, ensuring reliable playback for guided sessions.

The steps are practical and specific to product teams building audio features. We detail how to manage character limits, optimize costs via USDT top-ups, and handle voice selection without complex integrations. This page provides concrete examples and numbers to help you implement the API efficiently, from initial testing to supporting users via email.

How to Integrate TTS into a Meditation App?

Frequently asked questions

How do I choose the right voice?

Select from eight presets based on tone. Luna offers soft storytelling for guided sessions, while Sage provides calm, instructional clarity. Aria delivers a warm, clear narrator style. Each voice supports all 23 languages, allowing you to match the audio to your specific meditation or fitness script without needing separate voice models.

What is the best format for apps?

MP3 is a common choice for apps due to its balance of quality and file size. You can also choose WAV, Opus, FLAC, or PCM via the response_format parameter. Select the format that best fits your app’s storage constraints and playback requirements, keeping in mind that generated files are not stored by the API.

Can I change voices per user?

Yes. The API accepts a voice parameter in each request, allowing you to switch voices dynamically. You can assign specific voices to different user profiles or meditation types. Since each request is independent, you can change the voice setting for every individual audio generation without any global configuration changes.

How do I handle long scripts?

Split your script into parts of up to 4096 characters per request. Generate audio for each part individually, then join the resulting audio files on your end. This ensures reliable synthesis and avoids hitting the character limit. Failed requests are free, so you can retry parts if necessary without incurring extra costs.

Is the API suitable for real-time?

It is not designed for real-time streaming or WebSocket partial audio. Requests are processed sequentially, so under load, a request may wait in a queue. Typical speed is roughly real-time on long texts, but short phrases may take a few seconds. Pre-generate audio files for the best user experience in meditation apps.

What if the API goes down?

We do not provide an SLA or uptime guarantee. If the API is unavailable, requests may fail or queue. Failed requests are free, so you are not charged for errors. You should implement retry logic in your integration and consider pre-generating common meditation scripts to ensure availability even during temporary service disruptions.

Do I need a backend?

A backend is not strictly required but is recommended. You can call the API directly from your app using the OpenAI SDK by changing the base_url. However, using a backend helps manage your API key securely and allows you to handle character splitting and audio file joining efficiently before delivering content to the user.

Can I use the API on iOS?

Yes. You can use the OpenAI SDKs or plain HTTP requests from your iOS app. Simply change the base_url to https://api.bg4550.net/v1 and use your API key. The API returns standard audio files that iOS players can handle natively, making integration straightforward for your meditation or fitness application.

Can I use the API on Android?

Yes. The API works with any HTTP client or the OpenAI SDK on Android. Update the base_url to https://api.bg4550.net/v1 and authenticate with your Bearer token. Android apps can receive the generated audio files in formats like MP3 or WAV and play them using standard media players within your app.

How do I handle errors?

Check the HTTP status code and response body for error details. Failed synthesis requests are free, so you are not charged for errors. Implement retry logic for transient issues. Since requests are processed sequentially, high load may cause delays. Ensure your app handles timeouts gracefully and informs users if audio generation takes longer than expected.

What is the character limit?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer scripts, split the text into chunks of 4096 characters or less, generate audio for each chunk, and join the resulting files. This ensures reliable processing and avoids truncation of your meditation or fitness scripts.

Does it support multiple languages?

Yes, it supports 23 languages including English, Spanish, German, French, and Japanese. Any voice can speak any of these languages. If the language parameter is not set, the API guesses the language, defaulting to English for Latin script. For non-English Latin text, explicitly set the language code to ensure accurate pronunciation.

Is there a demo available?

You can test the API immediately by signing up with Google to receive a $0.50 free trial credit, valid for 7 days. This provides about 50,000 characters to generate audio. Use the provided curl example on the /get-api-key/ page to make your first request and hear the synthetic speech quality firsthand.

How do I contact support?

Support is available by email only. There is no phone number, live chat, or SLA. You can find the support email address on the /contact/ page. We do not offer real-time assistance, so please include your API key and details of your issue in your email for a faster response.

Step 1: Create an Account

Sound wave illustration for: Step 1: Create an Account

Accessing the FitVoice API requires creating an account on the /get-api-key/ page. You can sign in using Google or create an account with an email and password. This step establishes your unique identity within the system and prepares your environment for the first API calls.

Once registered, you will receive immediate access to your dashboard. This area serves as the central hub for managing your credentials, monitoring your character usage, and initiating top-ups. Keeping your key secure is essential for authenticating your requests.

Sign up with Google

Navigate to the /get-api-key/ page and select the Google sign-in option. This method provides a quick route to account creation and automatically grants you a free trial credit of $0.50, valid for 7 days. This trial allows you to test the API without immediate payment setup.

  • Supports email + password registration as an alternative
  • Google sign-up includes a $0.50 trial credit
  • Instant access to the dashboard upon verification

Get free trial credit

The trial credit provides approximately 50,000 characters of synthesis. This is sufficient for testing core features like voice selection and basic script generation. Note that accounts created with email and password start without this trial credit, requiring a manual top-up to begin usage.

  • Credit amount: $0.50
  • Approximate character count: 50,000
  • Validity period: 7 days

Find your API key

Your API key is displayed on the dashboard after registration. It appears in the format tts-... and is required for the Authorization: Bearer header. You can issue a new key at any time; the old key stops working immediately upon generation, ensuring security if you suspect exposure.

  • Key format: Bearer token starting with 'tts-'
  • One active key per account
  • New keys invalidate the old one instantly

Step 2: Choose a Voice

Sound wave illustration for: Step 2: Choose a Voice

Selecting the right voice establishes the emotional tone for your meditation or fitness app. FitVoice offers eight presets, each crafted from licensed recordings to provide distinct auditory experiences. Choosing correctly ensures your audio aligns with user expectations for calm or instructional content.

Select voices that match your content. Match the voice’s character to the specific use case, whether it’s a guided breathing session or a fitness workout prompt. The API supports 23 languages, allowing any voice to speak any supported language when the language parameter is set correctly.

Luna for storytelling

Luna is described as soft and ideal for storytelling. Use this voice for guided meditations, sleep stories, or narrative-based wellness content. Its gentle tone helps users relax and disengage from daily stress. Set the voice field to luna in your API requests.

Luna works well for longer, flowing scripts where a consistent, soothing presence is required. Since generated audio carries an inaudible watermark, users know it is synthetic, but the delivery remains natural and engaging.

  • Best for: Guided meditations, sleep stories, breathing exercises
  • Tone: Soft, storytelling
  • Language support: All 23 supported languages

Sage for instruction

Sage is calm and instructional, making it perfect for fitness cues, yoga poses, or structured routines. Its clear articulation ensures users understand each step without distraction. Use sage when precision and clarity are more important than emotional warmth.

This voice handles instructional text effectively, maintaining a steady pace. It is suitable for both short prompts and longer workout descriptions. Ensure the speed parameter is adjusted if the default pace feels too fast for your audience.

  • Best for: Yoga instructions, fitness cues, step-by-step guides
  • Tone: Calm, instructional
  • Language support: All 23 supported languages

Atlas for neutral tone

Atlas provides a neutral, news-like tone. Use it for factual content, progress updates, or when you want to avoid imposing a specific emotion. It is reliable for applications where the voice should remain unobtrusive and professional.

Atlas is suitable for users who prefer a straightforward delivery without stylistic flair. It works well for reminders, notifications, or general app audio where clarity and neutrality are prioritized over character-driven expression.

  • Best for: Notifications, progress updates, factual audio
  • Tone: Neutral, news-like
  • Language support: All 23 supported languages

Step 3: Prepare Your Script

Sound wave illustration for: Step 3: Prepare Your Script

Before sending text to the API, ensure your meditation script fits within the 4,096-character limit per request. Spaces and punctuation count toward this total, so review your full script length carefully to avoid truncation errors.

Check character limit

Each API call accepts a maximum of 4,096 characters. If your script exceeds this, you must split it into smaller parts before sending requests.

Split long texts

Divide longer meditation sessions into segments of up to 4,096 characters. Generate audio for each segment individually, then join the resulting audio files to play them sequentially in your app.

Set language code

Although the API guesses language from the script, explicitly set the language parameter for non-English Latin-script text to ensure accurate pronunciation. Supported languages include English, German, French, Spanish, and 19 others.

  • Set language ISO code for non-English Latin text
  • Default fallback is English for Latin scripts
  • Supports 23 languages including Arabic, Japanese, and Hindi

Step 4: Send Request

Sound wave illustration for: Step 4: Send Request

To generate audio, send a POST request to the speech endpoint with your script and voice selection. You can use the OpenAI SDK or a simple HTTP client like curl. The request body must be JSON, containing the model, input text, and voice parameters.

Use curl or SDK

Use the OpenAI SDK by changing the base URL, or send a direct POST request. Include the model (tts-1 or tts-1-hd), the text input, and the desired voice preset in the JSON body.

  • POST https://api.bg4550.net/v1/audio/speech
  • JSON body with model, input, voice, and response_format

Set base URL

Point your SDK or HTTP client to https://api.bg4550.net/v1. This ensures requests route correctly to the FitVoice API endpoint for audio synthesis.

Include API key

Add your unique key in the Authorization header as Bearer tts-.... Without this, the API rejects the request. You can find your key on the /get-api-key/ dashboard.

Step 5: Handle Response

Sound wave illustration for: Step 5: Handle Response

To use FitVoice in your meditation app, send a POST request to the speech endpoint with your script, chosen voice (e.g., Luna or Sage), and API key. The API returns the audio file directly in the response body, ready for immediate playback.

Receive audio file

The response contains the raw audio data in your requested format (mp3, wav, opus, flac, or pcm). No additional decoding is required before playback starts. Ensure your app handles binary data correctly to preserve audio integrity.

Play in app player

Integrate the received audio buffer into your existing media player. Since the output is a standard file format, it works with native iOS, Android, and web audio components. For meditation apps, ensure smooth transitions between generated clips if splitting long scripts.

Handle errors

If synthesis fails (e.g., invalid voice or rate limit), the API returns an error code but no audio data. Failed requests are free, so you can retry or notify the user without worrying about unnecessary charges. Always check the HTTP status code before processing the body.

Step 6: Optimize Costs

Sound wave illustration for: Step 6: Optimize Costs

Optimizing your API costs ensures your meditation app remains sustainable as you scale. By caching frequently used audio files, you avoid redundant generation fees for standard phrases like 'begin breathing exercise' or 'closing mantra'.

Monitoring your usage dashboard helps you track character consumption against your balance. This transparency allows product teams to adjust voice selection or script length before hitting limits.

Cache frequent texts

Store generated audio files locally or on a CDN for common instructions. Since the API charges per character, reusing existing files eliminates the cost of regenerating identical content.

This strategy is particularly effective for static meditation scripts that do not change frequently between updates.

  • Identify high-frequency phrases in your script
  • Store MP3 or WAV files in your app bundle or CDN
  • Update cache only when script text changes

Monitor usage

Check your balance and character count regularly via the dashboard. Failed requests are free, so ensure errors are handled correctly to avoid unnecessary charges.

Track your consumption rate to predict when you might need to top up, ensuring uninterrupted service for your users.

  • Review usage stats in the dashboard
  • Verify failed requests are not charged
  • Set internal alerts for low balance

Top up via USDT

Add funds using USDT on the TRON network (TRC-20). The minimum top-up is $5, and credits are applied automatically within minutes.

There are no monthly plans or subscriptions. Your balance does not expire, allowing you to pay only for what you use.

No credit cards or PayPal are required, keeping the process straightforward and global.

  • Send USDT (TRC-20) to your wallet address
  • Minimum top-up amount is $5
  • Credits appear within minutes

Step 7: Test Performance

Sound wave illustration for: Step 7: Test Performance

Testing ensures your meditation app delivers a calm, uninterrupted experience. By measuring generation speed and latency, you can set realistic expectations for users and optimize the audio player’s buffering behavior accordingly.

Accurate performance data helps you balance audio quality with responsiveness, ensuring that breathwork cues and guided sessions start promptly without awkward pauses.

Check generation speed

Longer texts generate at roughly real-time speed (about 25 characters per second of audio). Short phrases may take a few seconds to synthesize.

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

  • Expect ~25 characters per second for long texts
  • Short phrases take a few seconds
  • Sequential processing may cause queuing delays

Test latency

Measure the time from sending the API request to receiving the first bytes of audio. This helps you tune your app’s loading spinner or progress bar.

Network latency varies, but the API endpoint is stable. Monitor your specific region’s response times during peak usage hours.

  • Track end-to-end request time
  • Adjust UI loading indicators accordingly
  • Monitor regional performance variations

Verify audio quality

Listen to samples using Luna for storytelling or Sage for instruction to ensure the tone matches your app’s brand.

Check that the generated audio is clear and free of artifacts, especially when using higher speeds or different formats like Opus or FLAC.

  • Test Luna for storytelling
  • Test Sage for instruction
  • Verify clarity at various speeds
  • Check format-specific quality (Opus, FLAC)
Step 7: Test Performance

Step 8: Deploy to Users

Sound wave illustration for: Step 8: Deploy to Users

Once your meditation app is ready, point your API client to the production base URL. Ensure your authentication header uses the active key issued during setup. This configuration ensures all synthesis requests route correctly to the live service without affecting your development environment.

Keep an eye on your usage dashboard as you release to users. Monitoring helps you stay within the 60 requests per minute limit per key. If you approach the threshold, consider staggering requests or issuing a new key to reset the counter temporarily.

Go live with API

Update your application’s configuration to use the live endpoint. Verify that the base_url is set to https://api.bg4550.net/v1 and that your API key is securely stored in your backend environment variables. This ensures consistent audio generation for your users.

  • Set base_url to https://api.bg4550.net/v1
  • Store API key in backend environment variables
  • Verify authentication header format: Bearer tts-...

Monitor rate limits

The API allows 60 requests per minute per key. Exceeding this limit may result in temporary throttling. Use the usage dashboard to track your consumption and anticipate peak usage times during meditation sessions. If necessary, issue a new key to reset the limit immediately.

  • Limit: 60 requests per minute per key
  • New key issuance resets the limit
  • Track usage via the dashboard

Support via email

If users encounter issues during deployment, direct them to contact support via email. We do not offer live chat or phone support. Provide them with your account email for faster resolution. Ensure your team monitors this inbox regularly during the launch phase.

Step 9: Manage Voices

Sound wave illustration for: Step 9: Manage Voices

Manage your audio assets efficiently by understanding the available presets and how they fit your meditation app's tone. You can switch between voices based on specific session types or user preferences without changing your core integration.

Voice management is straightforward because the API provides a clear list of options. You can dynamically assign voices to different meditation tracks, ensuring a consistent or varied experience as needed.

List available voices

Retrieve the full list of voices via the /v1/voices endpoint. This returns metadata including voice name, gender, and supported languages, allowing you to build a selection menu in your app interface.

Each voice has a distinct character, from Luna’s soft storytelling to Atlas’s neutral news tone, giving you precise control over the auditory experience.

  • - Use GET /v1/voices to retrieve voice metadata
  • - Filter by gender or language support
  • - No custom cloning available; use presets only

Switch voices dynamically

Update the voice field in your API requests to change the speaker for subsequent audio generations. This allows you to offer multiple meditation guides within a single app without re-integrating.

Since voices are based on licensed recordings, the tone remains consistent even when switching between different narrators for various sessions.

Update presets

Presets are fixed; you cannot modify their inherent characteristics. However, you can adjust parameters like speed (0.25–4.0) to tailor the delivery style to your users' preferences.

Use the /v1/models endpoint to verify available models.

Step 10: Handle Long Texts

Sound wave illustration for: Step 10: Handle Long Texts

Long meditation scripts often exceed the 4096-character limit per request. To ensure consistent audio quality, you must divide your script into smaller segments before sending them to the API.

This approach prevents truncation and allows your application to handle large guided sessions or lengthy ambient narratives without hitting API constraints.

Split into chunks

Break your text into parts of up to 4096 characters. Spaces and punctuation count toward this limit. Use a simple string split function in your backend to divide the script evenly.

Ensure each chunk is a complete sentence or thought to avoid awkward audio cuts. This maintains the calming flow essential for meditation apps.

  • Max 4096 characters per request
  • Count spaces and punctuation
  • Split at sentence boundaries

Join audio files

Receive individual audio files for each chunk. Concatenate these files in the correct order to reconstruct the full narration. Most audio libraries can merge these seamlessly.

The resulting file plays as a continuous stream, preserving the natural rhythm of the guided session without noticeable gaps between segments.

Manage queue

Requests are processed sequentially. Under load, synthesis may wait in a queue, adding slight latency. Monitor your rate limits (60 requests per minute) to avoid delays.

For optimal performance, space out requests if processing multiple long scripts simultaneously. This ensures each chunk is generated without bottlenecking the API.

Step 11: Validate Inputs

Sound wave illustration for: Step 11: Validate Inputs

Validating inputs prevents wasted API credits and ensures consistent audio quality. Since the API returns errors for invalid requests, checking parameters locally saves time and keeps your meditation app responsive. Proper validation is the first line of defense against silent failures or unexpected costs.

Ensure your application handles character limits and language constraints before sending data to the endpoint. This step protects your balance and maintains a smooth user experience during guided sessions.

Check language codes

The API supports 23 specific languages. If you send Latin-script text without a language code, it defaults to English. For non-English content, always set the language parameter to the correct ISO code to avoid mispronunciation.

This is critical for meditation apps with multilingual users. Incorrect language settings can result in awkward speech patterns that break the calming atmosphere.

  • Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

Validate text length

Each request accepts up to 4096 characters. Exceeding this limit causes the API to reject the request. Your app should truncate or split longer scripts before submission.

Counting includes spaces and punctuation. Accurate counting ensures you do not accidentally exceed your character limit for a single audio segment.

Handle special chars

The API handles standard Unicode text well. However, complex emoji or rare symbols might affect pronunciation or length calculations. Test edge cases in your script strings.

Ensure your client library correctly encodes JSON bodies to avoid transmission errors. Simple text with standard punctuation works reliably across all supported voices.

Step 12: Review Billing

Sound wave illustration for: Step 12: Review Billing

Tracking character consumption ensures your meditation app stays within budget. Since billing is based on input length, understanding exactly how many characters are processed helps you estimate costs before generating audio files.

Check character count

The API counts spaces and punctuation as characters. A 4096-character limit applies per request, so long scripts must be split. Your dashboard displays remaining characters and usage history for transparency.

  • Spaces and punctuation count toward the total.
  • Failed requests are free and do not consume credit.
  • Balance does not expire.

Verify charges

Pricing is fixed at $10 per 1 million characters. You can verify charges directly in your account dashboard. Each request shows the exact character count and cost incurred.

Top up as needed

Add funds using USDT on the TRON network (TRC-20). Transfers are credited automatically within minutes. There is no minimum spend or monthly subscription, so you only pay for what you use.

  • Minimum top-up is $5.
  • Support is via email only.
  • No VAT or invoices.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The voice handles factual statements with precision, avoiding emotional bias that might distract from performance metrics or health statistics.

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. W3C WAI: making audio and video accessible
  4. curl documentation
  5. TRON developer hub: TRC-20
  6. ISO 639 language codes
  7. FFmpeg documentation
  8. Python documentation
  9. Creative Commons Attribution 4.0
  10. openai-node on GitHub
  11. Node.js documentation
  12. LibriTTS-R corpus (OpenSLR 141)

More on this site