How to Integrate Our TTS API with the OpenAI SDK?

By VoxCraft editorial team · Updated 2026-11-18

This guide explains how to integrate the VoxCraft text-to-speech API using the standard OpenAI SDK. By overriding the base_url to https://api.play55kk.com/v1, you can leverage a familiar interface for speech synthesis without learning a new library. This approach simplifies authentication and request handling for indie developers who already use OpenAI tools, ensuring seamless compatibility with our standard endpoint shape.

You will find concrete Python and JavaScript examples, request body structures, and error handling strategies. The guide covers practical details like managing audio responses, handling rate limits, and debugging common configuration issues, ensuring you can deploy reliable speech generation services with clear pricing and no enterprise overhead.

How to Integrate Our TTS API with the OpenAI SDK?

Frequently asked questions

Do I need to change the model name in the SDK?

No. Use "tts-1" or "tts-1-hd" exactly as you would with OpenAI. Both models use the same engine and pricing. The endpoint structure matches the OpenAI speech endpoint, so no model name adjustments are required when switching your base URL to https://api.play55kk.com/v1.

Is the response format the same as OpenAI?

Yes. The request body structure matches the OpenAI speech endpoint, allowing you to use official OpenAI SDKs by updating the base_url to https://api.play55kk.com/v1. The API returns audio files in mp3, wav, opus, flac, or pcm formats. Authentication uses a Bearer token, and the model parameter accepts "tts-1" or "tts-1-hd".

Can I use the same SDK for text generation?

No. This API is exclusively for text-to-speech synthesis. It does not offer text generation, translation, or speech-to-text capabilities. While you can use the OpenAI SDK, you must configure it to point to our base URL and use only the /v1/audio/speech endpoint. Other endpoints like /v1/voices are distinct to our service.

How do I handle audio playback in the browser?

The API returns the complete audio file in the response, so no special streaming handling is required. Receive the data and pass it directly to an HTML5 audio element. Since the service supports standard formats like MP3, WAV, and Opus, you can easily create a Blob URL from the response for immediate playback in your browser application.

Does the SDK handle retries automatically?

The OpenAI SDK retries on rate limits (429) and server errors (5xx), but not all failures. You should implement custom retry logic for robustness. Failed requests are free, so retrying on error does not incur additional charges if the synthesis fails. Use the SDK’s built-in retries for transient issues, but add your own logic for specific TTS constraints.

What if the API is down?

We do not offer an SLA or uptime guarantee. If the API is unavailable, your requests will fail. Failed requests are free, meaning you are not charged for characters processed during outages. You can verify service status by attempting a request or monitoring your dashboard for error notifications.

Can I use this with Node.js?

Yes. You can use the official OpenAI SDK for Node.js. Set the base_url to https://api.play55kk.com/v1 and provide your Bearer token. The SDK handles the JSON body structure correctly for the /v1/audio/speech endpoint, allowing seamless integration into your Node.js applications.

Is the SDK open source?

We do not provide an official SDK. Instead, use the open-source OpenAI SDKs or plain HTTP requests. Our API follows the same request shape as OpenAI, so you can use their SDKs by changing the base_url to https://api.play55kk.com/v1 and updating the authentication header with your API key.

How do I set the speed parameter?

Include the "speed" field in your JSON request body. Values must range from 0.25 to 4.0. The default speed is 1.0. This parameter adjusts the generation speed of the audio output, allowing you to speed up or slow down the speech synthesis.

Can I generate multiple voices in one request?

No. Each request supports only one voice preset. To generate audio with different voices, you must send separate requests for each voice. You can split longer texts into parts, but each part is synthesized with a single voice per request.

Does the SDK support streaming?

No. The API does not support streaming or WebSocket for partial audio. It returns the complete audio file in the response body. You must wait for the full synthesis to complete before receiving the data. For long texts, this may take time as requests are processed sequentially, but the entire file is delivered at once upon success.

How do I debug a failed request?

Check the HTTP status code and response body for error details. Failed requests are free, so no charge is applied. Ensure your input text is under 4096 characters and your voice ID is valid. Use the /v1/voices endpoint to verify available options.

Can I use the SDK with serverless functions?

Yes. The API is stateless and works well with serverless environments. Use the OpenAI SDK or plain HTTP to send requests. Be mindful of the 60 requests per minute rate limit per key. Serverless functions can easily manage the JSON body structure.

What is the maximum payload size?

The input text is limited to 4096 characters per request. Spaces and punctuation count toward this limit. For longer texts, split the text into parts of up to 4096 characters and join the resulting audio files manually in your application logic.

Why Use the OpenAI SDK

Sound wave illustration for: Why Use the OpenAI SDK

Our TTS API mirrors the standard OpenAI speech structure, allowing teams to reuse existing code patterns without learning a proprietary protocol. This compatibility ensures that developers can integrate speech synthesis directly into their current workflows with minimal friction.

Familiar interface for many developers

Since our endpoint follows the same request shape as the OpenAI speech endpoint, you can leverage existing knowledge. This reduces the learning curve for teams already familiar with the SDK's method signatures and response structures.

Well-documented and widely used

The OpenAI SDK is extensively documented and widely adopted. By using it to call our API, you benefit from a mature ecosystem with clear examples and community support, ensuring stability for your integration.

Simplifies authentication handling

The SDK handles authentication cleanly via environment variables. You simply set your API key, and the library manages the Authorization: Bearer header automatically, keeping your credentials secure and your code clean.

Configuration Steps

Sound wave illustration for: Configuration Steps

To integrate the VoxCraft API, you leverage the official OpenAI SDK, which provides a familiar interface for many developers. This approach simplifies authentication handling and utilizes well-documented, widely used libraries, allowing you to apply standard patterns to our endpoint without learning a new client structure.

By overriding the base URL, you direct the same SDK calls to our infrastructure. This method ensures compatibility with existing codebases while accessing our specific voices and formats. The process requires minimal configuration changes, making it ideal for indie developers who need reliable synthesis without enterprise overhead.

Install the official OpenAI package

The official OpenAI SDK for Python or JavaScript is the correct client library to use. Although branded for OpenAI, it works seamlessly with our API because we mirror their request shape. You simply install the package via your standard package manager, such as pip or npm, to get started.

Set the API key in environment variables

Retrieve your API key from your account dashboard at /get-api-key/. Store this key, prefixed with 'tts-', in an environment variable named OPENAI_API_KEY. This ensures your credentials remain secure and are easily accessible to the SDK during runtime without hardcoding them into your source files.

Override the base_url to our endpoint

Configure the SDK to point to our API base URL: https://api.play55kk.com/v1. This overrides the default OpenAI endpoint, ensuring that all speech synthesis requests are routed to our infrastructure. The SDK handles the rest, using your key for authentication against our rate limits and billing system.

Configuration Steps

Code Implementation Details

Sound wave illustration for: Code Implementation Details

The OpenAI SDK simplifies integration by allowing you to point the base URL to our API endpoint. This enables you to use the same familiar interface for speech synthesis while leveraging our specific voice models and pricing structure.

Below are practical examples for Python and JavaScript, demonstrating how to configure the client, send a request, and handle the returned audio data efficiently.

Python code example for speech generation

Install the official OpenAI package and set your API key. Override the base_url to https://api.play55kk.com/v1 to route requests through our infrastructure. Use the audio.speech.create() method, passing your model, voice, and input text.

JavaScript code example for speech generation

Initialize the OpenAI client with your key and the custom base_url. Call the speech endpoint with parameters like model, voice, and input. The response provides the audio stream directly for immediate processing or saving.

Handling the audio response object

The API returns audio in the format you specified (mp3, wav, opus, flac, or pcm). Save the binary response directly to a file or pipe it to a browser player. Note that while the SDK offers streaming methods, our API delivers the full file per request, so handle the response as a complete unit.

Request Body Structure

Sound wave illustration for: Request Body Structure

The request body requires explicit parameter mapping to ensure the API processes your text correctly. You must define the model, input text, voice selection, and output format within the JSON payload sent to the endpoint.

Proper configuration prevents errors and ensures the audio is generated in the desired format. Understanding these fields is critical for seamless integration with your application's workflow.

Mapping model to tts-1 or tts-1-hd

Both tts-1 and tts-1-hd use the same underlying engine and incur identical pricing. You may select either model based on your preference without affecting the cost per character or the core audio generation process.

This flexibility allows you to standardize your codebase while still having the option to switch models if specific experimental needs arise, though the technical output remains consistent between the two options.

  • Model options: tts-1 or tts-1-hd
  • Same engine and price for both models
  • No functional difference in pricing logic

Setting voice and input parameters

The input field accepts up to 4096 characters of text. Spaces and punctuation count toward this limit. You must select one of the eight available voices, such as aria for a warm narrator tone or atlas for neutral news delivery.

If the text language is not English, you should explicitly set the language parameter to the ISO code to ensure accurate synthesis, as the API guesses the language from the script by default for Latin text.

  • Max input length: 4096 characters
  • Voices: aria, nova, luna, sage, felix, milo, atlas, orion
  • Optional language parameter for non-English text

Specifying response format and speed

You can choose the response_format from mp3, wav, opus, flac, or pcm. Adjust the speed parameter between 0.25 and 4.0 to control the playback rate of the generated audio.

These parameters allow you to optimize file size and playback speed for your specific use case, whether you need high-fidelity FLAC for archival or compact MP3 for web delivery.

  • Formats: mp3, wav, opus, flac, pcm
  • Speed range: 0.25 to 4.0
  • Adjustable playback rate for optimization

Handling Audio Data

Sound wave illustration for: Handling Audio Data

The API returns the complete audio file directly in the response body, not as a continuous stream. The SDK handles this as a single, finite object, meaning you receive the entire asset once generation finishes. This simplifies integration since you do not need to manage partial chunks or WebSocket connections.

You can write this binary data directly to disk or load it into a browser’s Audio API. Since the data arrives as a complete file, traditional playback methods work without special streaming logic. This approach avoids intermediate storage and keeps memory usage predictable for standard text lengths.

Saving binary data to a file

Write the response content directly to a local file. In Python, use binary mode (wb) to save the bytes. In JavaScript, write the buffer to disk using Node.js file system modules. This ensures the audio is persisted for later use or archival.

  • Use binary write mode to preserve audio integrity.
  • No intermediate decoding is required before saving.
  • Works with all supported formats like MP3 and WAV.

Streaming audio to a browser player

Load the full response into a browser’s Audio object or HTML5 audio element. Since the entire file is returned, you can play it immediately after the request completes. This is not real-time streaming; the user waits for the full synthesis to finish before playback begins.

This method is suitable for short phrases or when immediate full-quality audio is preferred over progressive loading. Ensure the browser handles the response format correctly, such as converting PCM to a playable format if needed.

  • Load the binary response into an Audio object.
  • Play immediately after the request resolves.
  • No WebSocket or chunked encoding required.

Managing memory for large responses

For texts near the 4096-character limit, the response size is small enough to fit in memory easily. However, if processing many requests concurrently, monitor your application’s memory usage. The SDK returns the full file, so avoid keeping large audio objects in memory unnecessarily.

If generating long texts by splitting into segments, process and save each segment before freeing memory. This prevents memory leaks during batch operations. Use garbage collection or explicit disposal of audio objects after saving or playing.

  • Process segments individually to free memory.
  • Avoid storing large audio buffers in variables.
  • Monitor memory usage during batch requests.

Error Management in SDK

Sound wave illustration for: Error Management in SDK

Handling errors correctly ensures your TTS integration remains robust. The OpenAI SDK provides specific exception classes that distinguish between authentication failures, rate limits, and server errors, allowing you to implement targeted recovery logic rather than generic catch-all blocks.

Catching API exceptions

Import OpenAIError and its subclasses like RateLimitError or AuthenticationError from the openai package. Wrap your speech generation calls in a try-except block to catch these specific exceptions. This allows you to log the exact error code and message returned by the API, making debugging straightforward.

Retrying on rate limits

Our API enforces a limit of 60 requests per minute per key. If you exceed this, the SDK raises a RateLimitError. Implement an exponential backoff strategy in your retry logic to wait before re-sending the request. For bursty workloads, consider pre-splitting long texts into 4096-character chunks to manage concurrency more effectively.

Logging errors for debugging

Log the request ID, error type, and timestamp for every failure. Since failed requests are free, ensure your logs distinguish between network errors and API rejections. Include the input text length and voice used to reproduce the issue. This data is critical for identifying patterns in production without storing the audio itself.

Testing the Integration

Sound wave illustration for: Testing the Integration

To validate your integration, start with a simple request using your API key. Send a short string of text to the endpoint to confirm the OpenAI SDK correctly overrides the base URL and handles authentication. This step ensures your environment variables are properly configured before processing larger payloads.

Running a test request with short text

Send a concise input string via the SDK to verify connectivity. Ensure the response returns a valid audio object without errors. This confirms the SDK correctly interprets the custom base URL and authenticates with your specific key.

  • Use a text string under 100 characters for quick verification.
  • Confirm the HTTP status code is 200.

Verifying audio format output

Check that the returned binary data matches your requested response_format. Whether you chose mp3, wav, or opus, the file header should be valid. Play the file locally to ensure audio quality and speed settings applied correctly.

  • Validate file headers match the specified format.
  • Play the audio to confirm clarity and speed.

Checking character count billing

Verify that your account balance reflects the correct charge. The cost is $0.01 per 1,000 characters, including spaces and punctuation. Confirm the characters processed match your input length to ensure accurate billing tracking.

  • Calculate cost: $0.01 per 1,000 characters.
  • Ensure spaces and punctuation are counted.
Testing the Integration

Common Integration Issues

Sound wave illustration for: Common Integration Issues

Integration failures usually stem from simple configuration mismatches. The most frequent error is pointing the SDK to the wrong base URL or providing an invalid authentication key.

Ensure your requests target the correct API endpoint and that your credentials match the specific format expected by our service.

Incorrect base URL configuration

The OpenAI SDK defaults to api.openai.com. You must override the base_url to https://api.play55kk.com/v1. A mismatched URL results in immediate connection errors or 404 responses.

  • Verify base_url is set to https://api.play55kk.com/v1
  • Ensure the /v1 prefix is included in the URL

Missing or invalid API key

Authentication requires a key starting with tts-. If the SDK sends a standard sk- or pk- key, authentication will fail. Ensure your environment variable contains the correct prefix.

  • Check that the key begins with tts-
  • Confirm the key is active and not revoked

Unsupported model names

Only tts-1 and tts-1-hd are valid. Using generic model names like tts-1-1106 or other OpenAI-specific identifiers will cause a 400 Bad Request error.

  • Use tts-1 for standard synthesis
  • Use tts-1-hd for high-definition audio

Performance Considerations

Sound wave illustration for: Performance Considerations

Performance hinges on managing the 60 requests-per-minute limit. Since requests are processed sequentially under load, concurrent spikes can cause queuing delays, extending generation time beyond the typical real-time speed of 25 characters per second.

Avoiding concurrent request spikes

Batch your requests to stay within the 60 RPM limit. Use a semaphore or queue in your application logic to prevent overwhelming the API during peak usage.

  • Limit concurrent threads to match your rate limit
  • Implement exponential backoff for queued requests

Batching small text segments

Split long texts into segments under 4,096 characters. Generate audio for each part and concatenate the files to ensure consistent playback without hitting input limits.

  • Max 4,096 characters per request
  • Concatenate MP3/WAV/OPUS outputs

Monitoring rate limit usage

Track your character consumption against the 60 RPM cap. Monitor your dashboard to adjust your request frequency before hitting the queue limit.

  • Check /v1/voices for current limits
  • Log request timestamps to detect spikes

Advanced SDK Features

Sound wave illustration for: Advanced SDK Features

Using async/await keeps your application responsive while the API processes synthesis. Since requests are queued sequentially, non-blocking calls prevent your main thread from hanging during wait times. This is critical for maintaining throughput under load, ensuring your service remains available while individual audio files are generated.

Using async/await for non-blocking calls

Wrap your API calls in async functions to handle the asynchronous nature of the synthesis process. This allows your application to continue processing other tasks while waiting for the audio response. It is particularly useful when generating multiple short clips or handling high-volume requests where queue delays occur.

  • Ensure your runtime supports async/await syntax
  • Handle errors within the async context for cleaner stack traces

Configuring timeout settings

Set appropriate timeout values to avoid indefinite waits during peak usage. Given that processing is sequential, longer texts may take several seconds. A reasonable timeout prevents your application from timing out prematurely or hanging indefinitely if the queue is unusually long.

  • Set timeouts slightly above the expected generation time
  • Adjust timeouts based on text length and expected queue depth

Adding custom headers if needed

While the standard SDK handles authentication automatically, you can add custom headers for specific needs. This might include tracking IDs for debugging or custom metadata for your internal logging systems. Ensure these headers do not interfere with the required Authorization and content-type headers.

  • Add headers for request tracing or debugging
  • Ensure custom headers do not override essential API headers

Deployment Best Practices

Sound wave illustration for: Deployment Best Practices

Production deployments require strict key management to prevent unauthorized usage. Store your API key in secure environment variables rather than hardcoding it into source files. This ensures that credentials remain isolated from version control systems and can be rotated easily if needed.

Storing keys in secure environment variables

Use your platform’s secret management service to inject the Authorization: Bearer key at runtime. This prevents accidental exposure in logs or client-side bundles, ensuring that only your backend services can initiate speech synthesis requests.

  • Never commit keys to git repositories.
  • Rotate keys immediately if exposed.

Monitoring usage in production

Track character consumption and request latency to maintain cost efficiency. Since billing is based on character count, monitor usage spikes to ensure your balance covers high-volume periods. Regularly check your account dashboard for any anomalies in request status.

  • Set alerts for balance thresholds.
  • Log request durations for performance tuning.

Scaling based on character volume

Scale your infrastructure based on expected character volume rather than just request count. Remember that a single request can process up to 4096 characters, but longer texts require splitting. Ensure your queue system handles retries gracefully during peak loads to avoid timeouts.

  • Implement exponential backoff for retries.
  • Split long texts into 4096-char chunks.
Deployment Best Practices

Support and Troubleshooting

Sound wave illustration for: Support and Troubleshooting

When integration issues arise, our support channel is email-only; we do not offer phone lines or live chat. For quick reference, consult the /docs/ page for the latest endpoint specifications and request body structures. This ensures you are working with current implementation details without waiting for manual clarification.

Contact support via email for issues

Send detailed descriptions of your problem to [email protected]. Include your API key prefix, request timestamps, and error messages. We respond via email and do not maintain a ticketing system or live chat window. Expect a reply within standard business hours for complex SDK integration questions.

Check documentation for updates

The /docs/ page is updated whenever we modify the API schema or add new voice presets. Always verify your integration against the latest GET /v1/voices response to ensure your code handles all available formats correctly. This prevents errors when new languages or speed limits are introduced.

  • Review /docs/ for schema changes
  • Check /v1/voices for new presets
  • Update base_url if endpoints change

Verify account status and balance

Visit /get-api-key/ to view your current balance and character usage. If a request fails unexpectedly, confirm your account has sufficient funds. Failed requests are free, but insufficient balance will halt synthesis. Ensure your active key is correctly formatted in the Authorization header.

  • Check balance at /get-api-key/
  • Verify key format in headers
  • Confirm funds before bulk requests

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. indie developers can build rapid prototypes to validate startup ideas without needing large teams or significant funding.

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

More on this site