Integrating Our TTS API into Voice Assistants

By BotVoice editorial team · Updated 2026-11-18

This guide walks product teams through integrating our text-to-speech API into voice assistants and chatbots. You will learn how to generate audio files programmatically using standard HTTP requests, ensuring reliable voice UX without managing complex infrastructure. The process is designed to be straightforward, using familiar tools like the OpenAI SDK with a simple base URL change.

We cover every step from signing up and securing your API key to handling errors and scaling your bot. You will see concrete examples of request bodies, voice selection, and performance optimization. This resource is for engineers who need clear, practical instructions to speed up development and maintain control over their voice integration costs and quality.

Integrating Our TTS API into Voice Assistants

Frequently asked questions

How do I install the OpenAI SDK for this API?

Install the official OpenAI SDK for your programming language. Configure the client by setting the base URL to https://api.playfk9.com/v1. Authenticate using your Bearer token from the /get-api-key/ dashboard. The request body shape matches the standard speech endpoint, allowing immediate integration without custom client libraries or additional dependencies.

What is the best voice for a customer service bot?

Milo's voice is described as friendly and conversational, making it ideal for customer service interactions. Atlas offers a neutral, news-style tone suitable for clear information delivery. Select based on your brand personality, as all eight voices support all 23 languages and can be swapped dynamically via the voice parameter in your API calls.

How do I handle rate limits in a chatbot?

The API allows 60 requests per minute per key, or 10 per minute before the first top-up. Implement client-side queuing to process requests sequentially if needed. Since requests are processed one after another, under load a request may wait in a queue. Monitor your usage dashboard to stay within limits.

Can I use this API for a mobile app?

Yes, you can use the standard HTTP endpoint from a mobile app. However, there is no official mobile SDK or browser extension. You must manage authentication securely and handle the API key exposure risks inherent in client-side applications. Use the standard OpenAI SDK or plain HTTP requests to send text and receive audio files.

How do I split long texts into chunks?

Split input text into parts of up to 4096 characters per request. Generate audio for each chunk individually. Then, join the resulting audio files on the client side to create a continuous playback experience. This ensures each request stays within the character limit while delivering the full message to the user.

What is the difference between tts-1 and tts-1-hd?

Both models use the same engine and price. The only difference is the model identifier string sent in the request body. Selecting either 'tts-1' or 'tts-1-hd' results in identical audio generation quality and cost. Use the identifier that fits your existing code structure or preference without affecting performance or billing.

How do I specify the language in the request?

Include the optional 'language' field in the JSON body with an ISO code. If omitted, the system guesses the language from the script, defaulting Latin text to English. For non-English Latin-script text, explicitly set the language parameter to ensure accurate synthesis and avoid misinterpretation by the voice engine.

Can I change the speed of the audio after generation?

No, the speed is determined during generation via the 'speed' parameter (0.25–4.0). Once the audio file is returned, its playback speed is fixed. To change the speed, you must resend the request with a different speed value. There is no post-processing feature to adjust playback rate on existing files.

How do I track my API usage?

View your usage, balance, and characters left directly on the /get-api-key/ dashboard. The system keeps request metadata including time, characters, and status for billing purposes. Failed requests are free and returned in full. Monitor the dashboard regularly to manage your balance and ensure sufficient credit for ongoing integrations.

What should I do if the audio fails to play?

First, verify the audio file format matches your player capabilities (mp3, wav, opus, flac, pcm). Check that the response status was successful. If the synthesis failed, the charge is returned in full. Ensure your client correctly handles the binary audio data returned in the response body without corruption.

Do I need to handle audio file decoding?

No, the API returns standard audio files in formats like mp3, wav, opus, flac, or pcm. Your application simply needs to handle the binary response data. Standard media players can decode these formats natively. No custom decoding libraries are required unless you need specific processing beyond basic playback.

How do I test the API before going live?

Use the free trial credit of $0.50 (about 50,000 characters) valid for 7 days after signing in with Google; accounts created with email and password start without trial credit. Make test requests using the curl example provided on the /get-api-key/ page. Verify the audio output and response format. Monitor the dashboard to ensure credits are deducted correctly for successful generations.

Can I use multiple voices in one conversation?

Yes, you can switch voices between separate API requests. Each request accepts a 'voice' parameter allowing you to select from eight presets. Generate each line of dialogue with the desired voice and concatenate the audio files. This allows dynamic voice changes within a single conversation flow without waiting for a single long generation.

How do I reset my API key?

Issue a new key from the /get-api-key/ dashboard at any time. When you generate a new key, the old one stops working immediately. Update your application configuration with the new Bearer token. This ensures secure access management without downtime, as the transition is instantaneous and requires no manual revocation steps.

Step 1: Get Your API Key

Sound wave illustration for: Step 1: Get Your API Key

Start by creating an account on playfk9.com/get-api-key/. You can sign in using your Google account for immediate access, which includes a $0.50 trial credit valid for seven days. Alternatively, use an email and password setup, though this method does not include trial credit.

Sign Up with Google

Click the sign-up button on the dashboard. Select Google as your authentication provider. This method grants instant access to your new account and activates your free trial credit automatically.

Generate Key in Dashboard

Once logged in, navigate to the dashboard to view your API key. The interface displays your current balance, character usage, and a ready-to-use cURL example. You can issue a new key at any time, which immediately invalidates the previous one.

Copy Key Securely

Copy the key starting with 'tts-'. Store it in your environment variables or secret manager. Ensure it is not exposed in public repositories, as it authenticates all your synthesis requests.

  • Prefix: starts with 'tts-'
  • Format: Bearer token in header
  • Security: Use environment variables

Step 2: Install SDK

Sound wave illustration for: Step 2: Install SDK

The API follows the OpenAI request shape, allowing you to use the official OpenAI SDKs by simply adjusting the base URL. This eliminates the need to build custom HTTP clients or manage raw JSON serialization for your voice assistant’s text-to-speech module, though you may use plain HTTP if preferred.

Start by installing the library in your project environment. You will then update the configuration to point to our API endpoint, ensuring your bot sends synthesis requests to the correct infrastructure without modifying the core request structure.

OpenAI SDK Installation

Install the standard OpenAI SDK using your preferred package manager. This library handles the underlying HTTP connections and JSON formatting, reducing boilerplate code in your voice assistant’s backend.

  • pip install openai
  • npm install openai

Configure Base URL

Update the SDK configuration to direct requests to our API. Set the base URL to https://api.playfk9.com/v1 so that all subsequent speech synthesis calls route correctly.

Set Authentication Header

Provide your generated API key in the Authorization header as a Bearer token. Ensure this key is stored securely in your environment variables to prevent unauthorized usage of your character credits.

  • Authorization: Bearer tts-your-api-key-here

Step 3: First Request

Sound wave illustration for: Step 3: First Request

Sending your first synthesis request connects your chatbot’s text output to audible responses. You will construct a JSON payload containing the text, voice selection, and audio format, then send it to the API endpoint. This step validates your integration and returns the generated audio file.

The API processes standard TTS parameters, allowing you to immediately hear how your bot’s voice sounds. Ensure your text is under 4,096 characters to fit within a single request, keeping the payload concise for reliable delivery.

Construct JSON Body

Build a JSON object with the required fields. Include the input string with your bot’s response text, the voice preset (e.g., 'nova' for upbeat tones), and the response_format such as 'mp3'. Set the model to 'tts-1' or 'tts-1-hd' depending on your quality needs. Omit the language field if the text script clearly indicates the language; otherwise, specify the ISO code.

  • model: 'tts-1' or 'tts-1-hd'
  • input: Your bot's text response
  • voice: e.g., 'nova', 'aria'
  • response_format: 'mp3', 'wav', 'opus'

Send POST Request

Send the JSON payload via a POST request to https://api.playfk9.com/v1/audio/speech. Include your API key in the Authorization header as Bearer tts-.... The API processes requests sequentially, so ensure your integration handles the response promptly. If the synthesis fails, no charge is applied.

  • Endpoint: POST https://api.playfk9.com/v1/audio/speech
  • Header: Authorization: Bearer tts-...
  • Rate limit: 60 requests/minute

Parse Audio Response

The API returns the audio file directly in the response body. For 'mp3' or 'wav' formats, save the binary data to a temporary file or stream it directly to your voice assistant’s audio player. Check the HTTP status code to confirm success (200) or identify errors like rate limits (429).

Once parsed, pass the audio data to your bot’s audio engine. Ensure your playback library supports the chosen format, typically MP3 for efficient bandwidth usage in chatbot environments.

  • Response is binary audio data
  • Status 200 indicates success
  • Stream directly to audio player

Step 4: Choose Your Voice

Sound wave illustration for: Step 4: Choose Your Voice

Selecting the right voice ensures your bot sounds natural and aligns with its purpose. Our eight presets cover distinct tones, from warm narrators to energetic promos. Each voice handles all 23 supported languages, allowing consistent performance across global markets without needing separate voice profiles for different regions.

Start by listing the emotional context of your bot’s responses. Use the voice parameter in your JSON body to assign a specific preset. Test each option with typical phrases your bot will deliver, ensuring the tone matches the user experience you’ve designed.

Select Tone and Style

Define the personality of your assistant before choosing a voice. Use sage for clear, instructional content or felix for upbeat, promotional interactions. The atlas preset works well for neutral, news-style updates, while orion suits deeper, documentary-style explanations. Match the voice to the context to reduce cognitive load for users.

Ensure the selected voice feels consistent across all interactions. If your bot switches between casual and formal modes, consider if a single voice can handle both tones or if context-specific voice switching is necessary. Consistency builds trust and recognition.

  • Use aria for clear instructions.
  • Choose felix for energetic promos.
  • Select atlas for neutral updates.
  • Pick orion for deep narration.

Test Different Voices

Run your key phrases through the API using different voice presets. Pay attention to pacing and clarity, especially with longer texts. The nova voice offers a bright, upbeat quality suitable for engaging content, while luna provides a soft, storytelling tone ideal for immersive experiences.

Compare the audio output across various languages if your bot serves multiple regions. Since any voice can speak any of the 23 supported languages, you can maintain a consistent character voice even when switching languages by setting the language field explicitly.

  • Test nova for upbeat content.
  • Try luna for storytelling.
  • Verify clarity with sage (calm, instructional).
  • Check multi-language consistency.

Match Brand Identity

Align your voice choice with your brand’s visual and verbal identity. A tech support bot might benefit from the calm, instructional tone of sage, while a gaming assistant could use the energetic felix. Consistency in voice reinforces brand recognition and user trust.

Document your voice selection in your design system. Include the chosen voice preset in your API configuration templates. This ensures that all team members and future integrations use the same voice, maintaining a uniform user experience across all touchpoints.

  • Align voice with brand tone.
  • Document choice in design system.
  • Ensure team consistency.
  • Update API configs uniformly.

Step 5: Handle Errors

Sound wave illustration for: Step 5: Handle Errors

Errors are inevitable in voice assistant integrations. Handling them gracefully ensures your bot remains responsive and doesn't fail silently. This section covers how to interpret API responses and manage interruptions.

We provide clear status codes and predictable rate limits. By implementing robust error handling, you maintain a consistent user experience even when the API is under load or when requests fail.

Check HTTP Status Codes

The API returns standard HTTP status codes to indicate success or failure. A 200 OK means the audio file is ready. Use 400 Bad Request for invalid parameters, 401 Unauthorized for missing or invalid keys, and 500 Internal Server Error for transient issues.

Always log the full response body. It contains specific error codes that help pinpoint issues like invalid voice IDs or exceeded character limits.

  • 400: Invalid request parameters.
  • 401: Invalid or missing API key.
  • 429: Too many requests.
  • 500: Server error, try again later.

Handle Rate Limits

Each API key is limited to 60 requests per minute. If you exceed this, the API returns a 429 status code. Before your first top-up, the limit is 10 requests per minute.

Rate limits are enforced per key, not per IP. Ensure your integration checks the Retry-After header in the 429 response to determine how long to wait before retrying.

  • 60 requests/minute after top-up.
  • 10 requests/minute before first top-up.
  • Limit is per API key.
  • Check Retry-After header.

Retry Logic

Implement exponential backoff for retries. Start with a short delay and increase it progressively for consecutive failures. This prevents overwhelming the API during high traffic periods.

Only retry idempotent requests, such as text-to-speech generation. Do not retry requests that have already been charged if the audio was successfully generated but not received due to a network issue.

  • Use exponential backoff.
  • Retry on 429 and 500 errors.
  • Do not retry charged requests unnecessarily.
  • Set a maximum retry limit.

Step 6: Optimize Performance

Sound wave illustration for: Step 6: Optimize Performance

Optimizing performance ensures your voice assistant responds quickly without consuming unnecessary bandwidth or generating excessive latency. By selecting the right audio format and managing character limits effectively, you can maintain a smooth user experience even during peak usage periods.

Use MP3 for Efficiency

MP3 is the default and most efficient format for most voice assistant use cases. It offers a good balance between file size and audio quality, reducing bandwidth costs while maintaining clear speech. Use MP3 unless your specific player requires WAV, FLAC, or OPUS.

Preload Audio Files

Preloading audio files before they are needed can reduce perceived latency for the user. Generate common phrases or responses in advance and store them locally or in a cache. This is particularly useful for static responses like greetings or confirmation messages.

Manage Character Limits

Each request supports up to 4096 characters. For longer texts, split the input into smaller parts and join the resulting audio files. This prevents request failures and ensures consistent audio quality. Remember that spaces and punctuation count toward the character limit.

Step 7: Test in Environment

Sound wave illustration for: Step 7: Test in Environment

Before connecting your voice assistant to live users, validate the integration in isolated environments. This ensures that audio generation latency and voice selection align with your bot’s interaction model without affecting real customers or incurring unexpected costs.

Use local testing to verify request shapes and response parsing. Move to staging to test with simulated user traffic, confirming that the TTS API handles expected load and that voice outputs integrate smoothly with your voice synthesis pipeline.

Local Testing

Run sample requests against the API base URL to confirm that the JSON body structure is correct and that the audio response parses successfully. Verify that the generated MP3 files play correctly in your local audio player or testing framework.

Check that character limits are respected and that the response time meets your bot’s latency expectations. Ensure that the voice output matches the intended tone and language settings before proceeding to more complex scenarios.

  • Verify JSON request structure
  • Confirm audio file playback
  • Check character limit handling
  • Validate response time metrics

Staging Deployment

Deploy your bot’s TTS integration to a staging environment that mirrors production settings. Send simulated user inputs and verify that the audio responses are generated and delivered correctly without impacting live users.

Test edge cases such as long texts that require splitting and joining audio files. Confirm that the rate limits are respected and that the API handles requests as expected under simulated load.

  • Simulate user traffic
  • Test long text splitting
  • Verify rate limit behavior
  • Check concurrent request handling

Production Monitoring

Once live, monitor key metrics such as request volume, character usage, and error rates. Set up alerts for unusual spikes in usage or failures to ensure that your bot remains responsive and cost-effective.

Review the API response logs regularly to identify any patterns in latency or errors. Adjust voice selection or request parameters as needed to optimize the user experience while staying within your budget and performance targets.

  • Track request volume
  • Monitor error rates
  • Set usage alerts
  • Review API logs

Step 8: Monitor Usage

Sound wave illustration for: Step 8: Monitor Usage

Monitoring usage ensures your voice assistant operates within budget constraints without unexpected interruptions. By tracking character consumption and balance, product teams can predict costs and maintain consistent service levels for end users. This proactive approach prevents downtime during high-traffic periods and helps optimize request patterns for efficiency.

Regular monitoring allows you to adjust voice synthesis strategies based on actual usage data. Understanding character limits and rate limits helps in designing robust fallback mechanisms, ensuring a seamless user experience even when the API is under load or when unexpected usage spikes occur.

Track Character Count

Every request consumes characters based on the input text length, including spaces and punctuation. The API charges $0.01 per 1,000 characters, so tracking this metric helps you estimate costs accurately. Note that longer texts must be split into parts of up to 4096 characters, and each part counts separately against your limit.

You can monitor character usage through your dashboard, which displays the total characters processed and the remaining balance. This data helps you optimize text length for voice assistants, ensuring you stay within budget while maintaining high-quality audio output for your users.

  • Characters include spaces and punctuation
  • Cost is $0.01 per 1,000 characters
  • Requests under 4096 characters count individually

Check Balance

Your account balance reflects available credits for synthesis. You can check this at any time via the dashboard or by reviewing your account details. The balance does not expire, and failed requests are refunded in full, ensuring you only pay for successful audio generation.

Top-ups are processed via USDT on the TRON network, with credits appearing automatically within minutes. Ensure your balance is sufficient before launching large-scale deployments, as a low balance may interrupt service if not topped up in time.

  • Balance does not expire
  • Failed requests are refunded
  • Top-ups via USTRC-20 are automatic

Review Logs

Request metadata, including time, characters, and status, is retained for billing purposes. Reviewing these logs helps you identify patterns in usage, such as peak times or frequent errors, allowing you to optimize your integration strategy. You can access these details directly from your account dashboard.

Logs also help you troubleshoot issues by showing which requests succeeded or failed. This data is crucial for debugging voice assistant responses and ensuring that your TTS integration remains reliable and cost-effective over time.

  • Metadata includes time, characters, status
  • Logs are available in the dashboard
  • Use logs for debugging and optimization

Step 9: Scale Your Bot

Sound wave illustration for: Step 9: Scale Your Bot

Scaling your voice assistant requires managing character throughput efficiently. With a limit of 60 requests per minute per key, high-volume bots must batch text into chunks under 4,096 characters and join the resulting audio files seamlessly to maintain conversation flow without exceeding rate limits.

Handle High Volume

Monitor your usage dashboard to stay within the 60 requests per minute threshold. If you exceed this, requests may queue, increasing latency. Distribute load across multiple keys if necessary, noting that each key has its own limit.

  • Track character consumption against your balance.
  • Split long scripts into 4,096-character segments.
  • Join audio files sequentially for long responses.

Optimize Request Shapes

Ensure your JSON bodies strictly follow the required structure. Include only necessary fields like model, input, voice, and response_format. Removing unused parameters reduces payload size and processing overhead, ensuring faster synthesis times.

  • Use tts-1 for standard needs.
  • Specify response_format as mp3.
  • Set speed between 0.25 and 4.0.

Use Parallel Requests

For multi-turn conversations, send parallel requests for different voice lines. This reduces total wait time compared to sequential generation. Since requests are processed one after another under load, parallelism helps mask queuing delays.

  • Send independent requests simultaneously.
  • Combine responses in client-side logic.
  • Avoid duplicate API calls for same text.

Step 10: Maintenance

Sound wave illustration for: Step 10: Maintenance

Regular maintenance ensures your voice assistant remains secure and cost-effective. By rotating keys and reviewing usage, you prevent unauthorized access and keep billing aligned with your bot’s actual needs.

BotVoice provides straightforward tools to manage these updates without downtime. Follow these steps to keep your integration running smoothly over time.

Rotate API Keys

Generate a new key from the dashboard whenever you suspect exposure or periodically for security. The old key stops immediately upon issuing the new one, ensuring zero overlap gaps.

This single-key model simplifies tracking. Store the new key securely in your environment variables before updating your bot’s configuration.

  • One active key per account
  • Old key invalidates instantly
  • No downtime during rotation

Update SDK Versions

While we use the standard OpenAI SDK, keep your library updated to benefit from bug fixes and stability improvements. There is no proprietary SDK to manage, only standard HTTP client updates.

Check for updates regularly, especially when new response formats or minor endpoint changes are announced.

Review Pricing Changes

Our pricing is stable at $0.01 per 1,000 characters, but verify your balance and usage logs monthly. Top-ups via USTRC-20 are processed automatically, so ensure your wallet remains funded.

Reviewing logs helps you spot unusual character consumption that might indicate a loop or error in your bot’s logic.

Step 11: Advanced Features

Sound wave illustration for: Step 11: Advanced Features

Fine-tune voice characteristics and output formats to match your bot’s specific requirements. The API allows precise control over audio generation parameters without needing complex infrastructure changes, ensuring consistent user experiences across different interaction contexts.

Speed Adjustment

Adjust playback speed between 0.25 and 4.0 to control how fast the voice assistant speaks. Faster speeds reduce latency for quick responses, while slower speeds improve clarity for complex instructions or accessibility needs.

  • 0.25–4.0 range supported
  • No SSML speed tags required

Language Specification

Explicitly set the ISO language code to ensure accurate pronunciation, especially for non-English Latin script texts. Without this, the system guesses the language, which may default to English for Latin characters.

  • 23 supported languages
  • Optional but recommended for accuracy

Format Selection

Choose from mp3, wav, opus, flac, or pcm formats based on your playback infrastructure. MP3 offers a good balance of quality and file size for most voice assistant applications.

  • mp3, wav, opus, flac, pcm
  • No streaming support available

Step 12: Troubleshooting

Sound wave illustration for: Step 12: Troubleshooting

If your bot encounters issues, start by checking the HTTP status codes returned by the API. Common errors include 400 Bad Request for invalid parameters or 429 Too Many Requests when hitting the 60 requests per minute limit. Ensure your input text does not exceed 4096 characters, as longer texts require manual splitting into chunks.

Audio playback issues often stem from incorrect format handling. If the response format is PCM or WAV, ensure your bot supports these uncompressed formats. For MP3 or Opus, verify codec compatibility. Remember that generated audio files are not stored server-side, so you must handle the returned binary data immediately.

Common API Errors

Check the response body for detailed error messages. A 401 error indicates an invalid or expired API key, while 400 errors usually mean missing required fields like 'model' or 'voice'. Ensure you are using the correct base URL: https://api.playfk9.com/v1.

Rate limits are strict: 60 requests per minute per key. If you hit this limit, implement exponential backoff in your retry logic. Failed requests are free, so do not worry about charges for 4xx/5xx errors.

  • 401: Invalid API key. Regenerate in dashboard.
  • 400: Missing fields (model, voice, input).
  • 429: Rate limit exceeded (60 req/min).
  • 500: Server error. Retry with backoff.

Audio Playback Issues

Ensure your bot supports the requested response format. If you request 'opus', verify the player supports Opus codec. PCM data is raw and may need conversion for playback.

Audio files are not stored after generation. If playback fails, the issue is likely with the bot's handling of the returned binary stream, not missing files on our servers.

  • Verify codec support for MP3, WAV, Opus, FLAC, PCM.
  • Handle binary data immediately; files are not stored.

Support Contact

For issues not covered here, contact support via email. We do not offer phone support or live chat. Include your API key (last 4 digits), request timestamp, and error response in your email for faster resolution.

image":

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Build conversational flows that feel human to delight users and drive engagement.

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. Python documentation
  3. LibriVox public-domain audiobooks
  4. LibriTTS-R corpus (OpenSLR 141)
  5. curl documentation
  6. OpenAI API reference: create speech
  7. W3C WAI: making audio and video accessible
  8. FFmpeg documentation
  9. Node.js documentation
  10. Creative Commons Attribution 4.0
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. TRON developer hub: TRC-20

More on this site