Frequently asked questions
What is the best way to handle audio playback?
Receive the audio file from the POST response and pass it to your device’s native audio player. The API returns standard formats like mp3, wav, opus, flac, or pcm. Since the service provides complete files rather than streams, you must wait for the full response before initiating playback on the iOS device.
How do I manage API keys securely?
Store your single active Bearer token in your iOS keychain. The API uses one key per account; issuing a new key immediately invalidates the old one. You can rotate keys anytime via the dashboard to ensure security without downtime, provided you update the Authorization header in your HTTP requests.
Can I cache generated audio files?
Yes. The API returns the audio file in the response but does not store it. You can save the generated audio locally or on your server for reuse. This is efficient for IVR systems where menu prompts remain static, reducing repeated API calls and costs for identical text inputs.
What is the latency for short texts?
Short phrases take a few seconds to generate. Requests are processed sequentially, so under load, a request may wait in a queue. Expect roughly real-time speed on long texts, but short inputs incur a fixed processing delay. Plan your UI accordingly to avoid blocking the user interface during synthesis.
How do I handle long texts?
Split input text into parts of up to 4096 characters per request. Send each part to the POST endpoint and join the resulting audio files. This ensures compliance with the character limit while allowing you to generate audio for longer scripts, such as detailed IVR menus or extended call center scripts.
Is the API suitable for real-time use?
It is not a streaming API. You receive the complete audio file after synthesis. While generation is roughly real-time for long texts, short phrases take a few seconds. There is no WebSocket support for partial audio. For IVR, pre-generate audio files or handle the few-second delay appropriately in your call flow.
Do I need a backend server?
Not strictly, but recommended. You can call the API directly from iOS using the OpenAI SDK or plain HTTP. However, a backend helps manage rate limits, hide your API key, and handle text splitting for inputs over 4096 characters. It also simplifies managing USDT top-ups.
How do I detect the language?
Set the optional language parameter to an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly set the language to ensure correct voice synthesis. Supported languages include English, Spanish, German, French, and others listed in the docs.
Can I mix voices in one response?
No. Each request accepts one voice preset from the eight available options. To mix voices, you must send separate requests for each voice segment and join the resulting audio files. This requires client-side or server-side logic to concatenate the mp3, wav, or other supported format outputs into a single file.
What is the character limit per request?
The input field accepts up to 4096 characters per request. Spaces and punctuation count toward this limit. For texts exceeding this length, you must split the text into chunks of 4096 characters or fewer, generate audio for each chunk, and join the files. Failed requests are free.
How do I handle rate limits?
The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so queueing may occur. Implement exponential backoff in your iOS app or backend if you exceed the limit. Monitor your usage via the dashboard to stay within the 60 requests per minute threshold.
Is streaming supported?
No. The API does not support streaming or WebSocket connections. You receive the complete audio file in the response body. There is no real-time partial audio delivery. You must wait for the full synthesis to complete before playing the audio. This fits well with IVR systems that pre-load audio prompts.
Can I use custom pronunciation?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. Pronunciation is determined by the voice preset and input text. If specific words need alternative pronunciation, you may need to spell them out phonetically in the input text or use a different voice preset that handles them better.
How do I monitor usage costs?
Check the dashboard at /get-api-key/ to view your balance, characters left, and usage. The cost is $10 per 1 million characters. Failed requests are free. You can monitor real-time usage and character counts directly on the account page to manage your USDT balance and avoid unexpected charges.
Preparation Phase
To begin integrating LinguaLink into your iOS call center application, secure an account via /get-api-key/ using Google or email. This establishes your billing profile and allows access to the API dashboard where usage metrics are tracked.
Account Creation
Register on the site's /get-api-key/ page. Accounts are site-specific, so ensure you are on bme688.info. Use Google sign-in for immediate trial credit activation, or email/password for standard access.
- Sign up via /get-api-key/.
- Use Google for $0.50 trial credit.
- Email/password accounts start with zero balance.
Key Generation
Generate a Bearer token (tts-...) from your dashboard. This single key authenticates all requests to https://api.bme688.info/v1. You may issue a new key at any time, instantly invalidating the previous one.
- One active key per account.
- New keys instantly invalidate old ones.
- Use Authorization: Bearer tts-...
Trial Credit Usage
Google sign-in grants $0.50 credit (~50,000 characters) valid for 7 days. This allows testing the POST /v1/audio/speech endpoint. Email-based accounts do not receive trial credit.
- $0.50 credit for Google sign-ins.
- Valid for 7 days.
- Email accounts start with zero balance.
API Configuration
Configure the API base URL to https://api.bme688.info/v1 in your iOS SDK settings. This ensures all speech synthesis requests route correctly to the LinguaLink infrastructure.
Include the Authorization: Bearer tts-... header in every request. Use your unique API key issued during account creation to authenticate requests for call center audio generation.
Base URL Setup
Set the base URL to https://api.bme688.info/v1. This endpoint handles all POST requests for audio synthesis and GET requests for voice metadata and models.
- Base URL: https://api.bme688.info/v1
- Endpoint: POST /v1/audio/speech
Authentication Header
Pass your API key via the Authorization: Bearer header. Each account has one active key; issuing a new key invalidates the old one immediately.
- Format:
Authorization: Bearer tts-... - One active key per account
Model Selection
Select either tts-1 or tts-1-hd. Both models use the same engine and price structure, allowing flexible quality selection without cost variation.
- Models: tts-1, tts-1-hd
- Same price for both models
Request Construction
Constructing the request body for the LinguaLink TTS API requires precise JSON formatting. Each synthesis call must include the model, input text, voice selection, and response format. The structure mirrors standard TTS endpoints, ensuring compatibility with existing HTTP libraries on iOS devices.
JSON Body Structure
The request body is a JSON object sent via POST. It must contain the model ("tts-1" or "tts-1-hd"), input text (max 4096 characters), voice, and response_format. Optional fields include speed (0.25–4.0) and language.
- Content-Type: application/json
- Method: POST
- Max input length: 4096 characters
Voice Parameter
Select one of eight preset voices. Female options include aria, nova, luna, and sage. Male options are felix, milo, atlas, and orion. Each voice is optimized for specific tones, from warm narration to neutral news delivery.
Language Code
Provide an ISO language code for non-English texts. While the API guesses language from script, explicit codes prevent errors for Latin-script languages like German or Dutch. Supported languages include English, Spanish, French, German, and 19 others.
- ISO 639-1 codes
- Defaults to English if unspecified
- Supported: 23 languages
Audio Handling
Audio handling determines how synthesized speech is delivered to your iOS user interface. The API returns standard audio files that must be decoded and played by your application, requiring careful management of file formats and timing to ensure a seamless IVR or call center experience.
MP3 vs WAV
Choose MP3 for efficient network transmission and lower bandwidth usage, which is critical for mobile data conservation. Select WAV if your iOS audio pipeline requires uncompressed PCM data for immediate playback without decoding overhead, accepting the larger file sizes.
File Size Optimization
Optimize storage by caching generated audio files locally when appropriate, though note that generated audio is not stored server-side. For long IVR menus, split texts into chunks under 4096 characters to manage memory usage effectively during synthesis.
Playback Delay
Expect a generation speed of roughly 25 characters per second for long texts, with short phrases taking a few seconds. Requests are processed sequentially, so under load, a request may wait in a queue, introducing latency before the audio file is ready for playback.
Error Management
Handling failures gracefully is critical for call center reliability. Your iOS application must distinguish between transient network issues and permanent API errors to ensure seamless IVR interactions.
Rate Limit Errors
The API enforces a limit of 60 requests per minute per key. If you exceed this threshold, the API returns a 429 status code. For new accounts, the limit is stricter at 10 requests per minute until the first top-up is processed.
- Monitor the
X-RateLimit-Remainingheader in responses. - Implement exponential backoff when a 429 error occurs.
- Consider caching frequent prompts to reduce request volume.
Invalid Input
Errors often stem from exceeding the 4096-character limit per request or providing an unsupported voice or format. Ensure your payload conforms to the required JSON schema. Invalid characters or unsupported languages may also trigger rejection.
- Validate text length before sending the request.
- Verify voice IDs against the
/v1/voicesendpoint. - Check that the response format is one of mp3, wav, opus, flac, or pcm.
Network Timeouts
Longer texts may take several seconds to generate. Set your iOS network client timeout to at least 30 seconds to accommodate processing delays, especially during high-load periods. If the connection drops mid-request, the API may still process the text. However, you will not receive the audio file. Implement idempotency checks or request a fresh synthesis if the status is unknown.
Optimization Strategies
Optimizing text-to-speech synthesis for iOS applications requires careful management of request volume and network latency. By implementing efficient caching and precise text segmentation, developers can reduce API calls and minimize playback delays for interactive voice response systems.
Text Chunking
Since each request accepts a maximum of 4,096 characters, longer prompts must be split and concatenated. This prevents truncation and ensures consistent audio quality across extended dialogues for IVR menus.
Caching Responses
Store generated audio files locally or on a CDN for static prompts like greetings or menu options. This eliminates redundant API calls, lowers costs, and reduces latency for frequently played phrases.
Batch Processing
Group independent text segments to process them sequentially within the 60 requests-per-minute limit. This strategy maintains steady throughput without hitting rate limits, ensuring smooth audio playback during high-traffic periods.
Testing Phase
Testing ensures your IVR bots deliver clear audio without disrupting user experience. Verify voice quality and latency limits before routing live call traffic. This phase confirms that your implementation handles both standard and edge-case inputs correctly. We recommend a structured approach: validate syntax locally, test latency in a staging environment, and simulate peak usage with load tests. This prevents costly misroutes during production deployment.
Local Validation
Validate JSON structure and character limits locally. Ensure the API key authenticates correctly against https://api.bme688.info/v1. Use the provided curl example to confirm immediate audio generation for short phrases.
- Verify 4096 character limit enforcement
- Check
response_formatcompatibility - Confirm 200 OK status codes
Staging Environment
Test voice selection (aria, nova, etc.) and language codes in a controlled setting. Verify that the trial credit ($0.50) processes correctly and that metadata logging captures request times accurately.
- Test ISO language codes
- Verify voice presets
- Check metadata logging
Load Testing
Simulate peak IVR traffic to observe queue behavior. Ensure the system respects the 60 requests per minute limit without dropping calls. Monitor that audio generation remains stable under concurrent requests.
- Simulate 60 RPM traffic
- Monitor queue wait times
- Verify concurrent request stability

Deployment
Moving to production requires switching from your trial key to a dedicated production key. Ensure your iOS app securely stores the tts-... key, preferably using the Keychain, to prevent unauthorized usage from reverse-engineered binaries. With 60 requests per minute, configure your bot’s logic to handle rate limits gracefully without disrupting the user experience.
Monitor your API usage dashboard to track character consumption against your balance. Since billing is based on character count including spaces, accurate tracking prevents unexpected depletion. Set up alerts if usage spikes, ensuring your call center bot remains operational during high-volume periods.
Production Keys
Replace the trial key with your primary production key after the initial testing phase. Generate a new key via the /get-api-key/ page if the current one is compromised; the old key stops immediately.
Store the key securely in your iOS app’s Keychain. Avoid hardcoding it in plain text within the app bundle.
- Use the /get-api-key/ page to generate keys.
- Keys are invalidated immediately upon issuing a new one.
Monitoring Usage
Track character consumption directly from the dashboard. Each request’s character count is logged for billing purposes.
Set internal thresholds to pause audio generation if the balance drops below a critical level, preventing partial charges for incomplete calls.
- Characters include spaces and punctuation.
- Failed requests do not consume balance.
Cost Tracking
Billing occurs at $0.01 per 1,000 characters. Monitor your balance regularly to ensure sufficient funds for ongoing operations.
Top-ups via USDT (TRC-20) are credited automatically. Plan top-ups in advance to avoid service interruption during peak call center hours.
- Minimum top-up is $5.
- Balance does not expire.
Common Issues
Developers integrating LinguaLink into iOS call center bots often encounter predictable audio and latency issues. Understanding the underlying constraints of the TTS engine helps isolate whether the problem lies in the network, the request payload, or the playback implementation.
This section addresses three frequent operational hurdles: silent output, language misidentification, and generation delays. Each cause is mapped to a specific configuration or environmental factor.
Silent Audio
Silent audio usually results from an empty input field or a silent text payload. Verify that the text string contains visible characters and is not null. Ensure the response_format matches the iOS player’s capabilities, though MP3 is universally supported.
- Check
inputfield for null or empty strings. - Verify
response_formatcompatibility with AVPlayer. - Ensure text is not purely whitespace.
Wrong Language
If the language parameter is omitted, the engine guesses from the script. Latin script defaults to English, which causes errors for other languages. Explicitly set the language code (e.g., es, fr) for non-English text to prevent mispronunciation.
- Set
languageexplicitly for non-English Latin text. - Use ISO codes for precise language targeting.
- Avoid relying on script detection for mixed scripts.
Slow Generation
Generation speed depends on text length and server load. Short phrases take a few seconds; longer texts process at roughly real-time speed. Requests are queued sequentially, so high concurrent load increases latency. Split long texts into 4096-character chunks to maintain responsiveness.
- Expect a few seconds for short phrases.
- Load-dependent queuing may increase latency.
- Split text into 4096-character chunks for better control.
Best Practices
Implementing robust error handling and resource management ensures reliable audio playback in your iOS call center application. Properly managing network requests and file resources prevents memory leaks and maintains a smooth user experience during high-volume IVR interactions.
Secure key storage protects your billing identity and prevents unauthorized usage of your text-to-speech credits. Following these practices minimizes operational overhead and ensures consistent service delivery for your end users.
Error Retry Logic
Implement exponential backoff for rate limit (429) and network errors. Since requests are processed sequentially, brief delays prevent queue saturation. Retry failed requests once to handle transient network issues, but discard after two attempts to avoid infinite loops during sustained load.
- Use exponential backoff for 429 and 5xx errors
- Retry failed requests once before discarding
- Discard requests after two failed attempts
Resource Cleanup
Ensure all URLSession tasks and audio players are properly deallocated when views disappear. Release temporary audio files immediately after playback to prevent storage bloat on the device. Clearing these resources maintains app performance during long IVR sessions.
- Deallocate URLSession tasks and audio players
- Remove temporary audio files post-playback
- Clear resources on view disappearance
Secure Key Storage
Store your API key in the iOS Keychain, not in UserDefaults or code. This prevents extraction by casual reverse engineering. Since each account has only one active key, compromise allows immediate key rotation via the dashboard.
- Use iOS Keychain for key storage
- Avoid
UserDefaultsor hardcoded strings - Rotate keys immediately upon suspected compromise
Support Channels
LinguaLink provides a single, direct channel for all technical inquiries regarding iOS integration. There is no phone support or live chat available. Developers must submit questions via email to receive assistance with implementation details, billing discrepancies, or API behavior.
Email Support
All support requests are handled exclusively through email. This ensures a documented trail for every issue, which is critical for debugging call center audio flows. Responses are provided based on the volume of incoming tickets; there is no guaranteed SLA for response time.
Documentation Updates
The documentation is updated whenever the API structure or rate limits change. Since we do not maintain versioned legacy docs, always refer to the current /docs/ page for the latest iOS integration patterns. We do not issue formal release notes for minor updates.
Community Forums
We do not maintain official community forums for this independent storefront. Developers are encouraged to review the provided curl examples and SDK usage guides for common iOS implementation patterns. For specific technical issues, email support is the primary channel.
Future Updates
We do not have an official proprietary SDK for iOS or other platforms. Developers must use the standard OpenAI SDK or plain HTTP requests, adjusting the base URL to our API endpoint. This approach ensures compatibility with any modern iOS networking library without requiring additional dependencies.
SDK Updates
Since we provide a REST API compatible with the OpenAI speech endpoint, updates to our interface will be backward-compatible. You will not need to update a specific SDK version but should ensure your HTTP client libraries are current.
- Use standard OpenAI SDK or HTTP client.
- No proprietary iOS SDK required.
- Base URL configuration remains the primary integration point.
New Voices
We may introduce new voice presets based on licensed recordings from LibriVox. Any new voices will be added to the GET /v1/voices endpoint, allowing your app to fetch the latest available options dynamically without code changes.
- Voices are added to the existing 8 presets.
- New voices support all 23 languages.
- Fetch updated voice list via API.
Format Changes
We support MP3, WAV, OPUS, FLAC, and PCM. We may add new formats if they become industry standards for call center quality or bandwidth efficiency. The response_format parameter in your request will accept these new formats seamlessly.
- Current formats: mp3, wav, opus, flac, pcm.
- New formats added via API endpoint.
- No breaking changes to existing requests.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. For projects needing only basic IVR menus without custom cloning, this preset range is sufficient and reliable.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriVox public-domain audiobooks
- MDN: Web Speech API
- curl documentation
- ISO 639 language codes
- Tether (USDT)
- LibriTTS-R corpus (OpenSLR 141)
- TRON developer hub: TRC-20
- Creative Commons Attribution 4.0
- openai-python on GitHub
- W3C WAI: making audio and video accessible
- OpenAI API reference: create speech
