Integrate Our Text-to-Speech API with OpenAI SDKs

By AssistVoice editorial team · Updated 2026-11-18

This documentation guides startups building assistive devices and elderly care apps through integrating AssistVoice’s text-to-speech API. You will learn how to generate clear, natural speech using standard OpenAI SDKs by simply changing the base URL. The guide covers authentication, available voices, and response formats, ensuring you can deliver accessible audio for your users without complex infrastructure.

We provide transparent, per-character pricing with no hidden fees or monthly subscriptions. This page details the specific request parameters, rate limits, and error handling procedures you need for reliable production use. By the end, you will have a working cURL example and a clear understanding of how to manage your API key and balance efficiently.

Integrate Our Text-to-Speech API with OpenAI SDKs

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playsv77.com/v1. You send POST requests to https://api.playsv77.com/v1/audio/speech to generate audio. This endpoint accepts JSON bodies containing your text, voice selection, and format preferences. All other endpoints, such as retrieving voices or models, are accessed relative to this base URL.

How do I authenticate my requests?

Include your API key in the Authorization header as Bearer tts-... . Each account has one active key at a time. You can issue a new key at any time via the dashboard; the old key stops working immediately. Ensure your key is valid before sending requests to avoid authentication errors.

What models are available?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and price. Choose tts-1 for standard generation or tts-1-hd for higher quality. The model parameter is required in your request body. Both models support all available voices and languages, offering consistent performance across your use cases.

Can I use the OpenAI SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.playsv77.com/v1. Use your AssistVoice API key for authentication. The request shape matches the OpenAI speech endpoint exactly. This allows you to integrate AssistVoice into existing OpenAI-based workflows without significant code changes or custom client implementations.

What are the rate limits?

The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. If you exceed this, requests may be queued or rejected. Ensure your application handles rate limit errors gracefully. For high-volume use, consider batching requests or implementing exponential backoff strategies.

How do I handle errors?

Failed requests are free, and the charge is returned in full. Monitor response status codes to detect failures. If synthesis fails, no characters are deducted from your balance. Implement retry logic for transient errors. Check your key validity and rate limit status if errors persist. Review the response body for specific error details.

What audio formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. Specify the desired format using the response_format parameter in your request. Each format serves different use cases, from web playback to high-fidelity storage. The API returns the audio file directly in the response, allowing immediate playback or storage.

How do I specify a voice?

Use the voice parameter with one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrators to deep documentary styles. Select the voice that best fits your content. You can switch voices dynamically between requests to vary the output.

What is the character limit per request?

Each request supports up to 4096 characters of input text. For longer texts, split them into parts of this size and join the resulting audio files. Spaces and punctuation count toward the character limit. This limit ensures efficient processing and consistent generation times for standard-length inputs.

How do I set the language?

Use the optional language parameter with an ISO code. If omitted, the language is guessed from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly set the language to ensure correct pronunciation. Supported languages include Arabic, Chinese, English, French, German, and others listed in the API docs.

Can I change the speed of the speech?

Yes, adjust the speed using the speed parameter, ranging from 0.25 to 4.0. The default speed is 1.0. Faster speeds reduce generation time, while slower speeds may improve clarity for accessibility use cases. This feature allows fine-tuning the output to match your specific application requirements.

What happens if I exceed the rate limit?

Requests are processed sequentially, so under load, a request may wait in a queue. If you exceed the limit, subsequent requests may be delayed or rejected. Implement retry logic with exponential backoff. Monitor your usage via the dashboard to stay within limits.

How do I get a list of available voices?

Send a GET request to /v1/voices. This endpoint returns details about all available voices, languages, formats, and pricing. Use this information to select the best voice for your content. The response includes metadata about each voice, helping you make informed decisions about your TTS implementation.

Is the API compatible with OpenAI SDKs?

Yes, the API is compatible with OpenAI SDKs. Change the base_url to https://api.playsv77.com/v1 and use your AssistVoice key. The request shape matches the OpenAI speech endpoint. This compatibility allows seamless integration into existing OpenAI-based applications without requiring custom client code or significant refactoring of your existing logic.

First request

curl

curl https://api.playsv77.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playsv77.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.playsv77.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication

Sound wave illustration for: Authentication

Access the AssistVoice API using a Bearer token in the Authorization header. This single key authenticates all requests to the speech endpoint and ensures secure, tracked usage of your account's character balance.

Bearer Token

Bearer Token

Include your key as Authorization: Bearer tts-... in every request. The token verifies your identity and deducts characters from your active balance at the rate of $0.01 per 1,000 characters (or $10 per 1 million characters).

  • Format: Authorization: Bearer tts-your_key_here
  • Sent in the HTTP header for all API calls

Single Active Key

Single Active Key

Each account maintains one active API key. If you generate a new key, the previous one becomes invalid immediately. This simplifies security for assistive device deployments by ensuring only one credential is valid at any time.

Key Management

Manage your key directly on the /get-api-key/ dashboard. You can view your current balance, usage statistics, and issue a new key instantly without downtime, ensuring continuous operation for your elderly care applications.

  • View balance and usage on the dashboard
  • Issue new keys with immediate invalidation of old ones

Endpoints Overview

Sound wave illustration for: Endpoints Overview

The AssistVoice API provides three core endpoints to handle speech synthesis and configuration. The primary endpoint processes text inputs and returns audio files, while the secondary endpoints expose available voices and model details for seamless integration.

POST /v1/audio/speech

This endpoint accepts your text and returns an audio file. It follows the same request shape as the OpenAI speech endpoint, allowing you to use existing OpenAI SDKs by simply updating the base URL. You can specify the model, voice, language, and audio format in a single JSON payload.

  • Endpoint: POST https://api.playsv77.com/v1/audio/speech
  • Accepts JSON body with model, input, voice, and response_format
  • Returns audio file directly in the response

GET /v1/voices

Use this endpoint to retrieve a list of available voices, supported languages, and audio formats. It helps you verify which voices are active and determine the correct parameters for your synthesis requests before sending data.

  • Lists all 8 available voice presets
  • Shows supported languages and formats
  • Returns current pricing and availability status

GET /v1/models

This endpoint returns the available TTS models, currently "tts-1" and "tts-1-hd". Both models use the same engine and pricing, allowing you to switch between standard and high-quality audio without changing your pricing structure.

  • Returns available model identifiers
  • Confirms pricing parity between tts-1 and tts-1-hd
  • Provides model metadata for integration

Request Parameters

Sound wave illustration for: Request Parameters

Configure the synthesis parameters to match your assistive device or elderly care app requirements. The API accepts standard text input and allows precise control over voice, model, and output format to ensure optimal audio clarity and character accuracy.

Model Selection

Choose between tts-1 for standard processing or tts-1-hd for higher fidelity. Both models use the same engine and pricing structure, allowing you to switch without changing your integration logic.

Input Text

Submit plain text in the input field, limited to 4096 characters per request. Spaces and punctuation count toward the character limit. For longer content, split the text into chunks and join the resulting audio files.

Voice Selection

Select from eight distinct presets to suit your application's tone. Female voices include aria (warm, clear narrator), nova (bright, upbeat), luna (soft, storytelling), and sage (calm, instructional). Male options are felix (energetic, promo), milo (friendly, conversational), atlas (neutral, news), and orion (deep, documentary).

Response Formats

Sound wave illustration for: Response Formats

Select the output format that best suits your assistive device or elderly care application’s playback requirements. Each format balances file size, compatibility, and audio fidelity differently, allowing you to optimize for bandwidth or quality.

MP3

MP3 is the default and most widely supported format. It offers a good balance between file size and sound quality, making it ideal for mobile apps and web players where bandwidth conservation is important.

WAV

WAV provides uncompressed, high-quality audio. Use this format when you need pristine sound quality for playback on devices that do not support lossy compression or when you plan to further process the audio file.

FLAC, OPUS, PCM

FLAC offers lossless compression, reducing file size without quality loss. OPUS is efficient for low-bandwidth transmission. PCM provides raw, uncompressed audio data, useful for immediate hardware playback without decoding overhead.

  • FLAC: Lossless, smaller than WAV
  • OPUS: Efficient for low bandwidth
  • PCM: Raw, uncompressed data

Rate Limits

Sound wave illustration for: Rate Limits

Our API enforces strict rate limits to ensure stability during high-volume synthesis. Each API key is capped at 60 requests per minute, which is sufficient for most batch processing and real-time assistive device applications. Requests are processed sequentially, meaning complex generations may take slightly longer under load.

New accounts start with a lower limit of 10 requests per minute until the first top-up is confirmed. This prevents accidental bursts from draining your initial free trial balance before you verify your payment method.

60 Requests per Minute

Once you add funds, your limit increases to 60 requests per minute. This throughput is designed to handle typical startup workloads, such as generating audio for elderly care apps or assistive hardware, without requiring complex queue management on your end.

10 Requests per Minute (Initial)

Before your first top-up, you are limited to 10 requests per minute. This allows you to test the API’s quality and integration without risking excessive usage during your free trial period.

Queue Processing

Requests are processed one after another. If you send multiple requests rapidly, they will be queued and executed in order. Long texts may take time to synthesize, but the system ensures each request is completed before moving to the next, preventing data corruption.

  • Requests are sequential, not parallel.
  • Queue ensures no data loss.
  • No parallel burst allowed.
Rate Limits

Error Handling

Sound wave illustration for: Error Handling

Understanding error responses ensures your assistive device or elderly care app handles synthesis failures gracefully without crashing. AssistVoice returns standard HTTP codes to indicate the status of each request, allowing your integration to distinguish between temporary network issues and permanent configuration errors.

Common Error Codes

The API returns specific HTTP status codes to help you debug integration issues. A 400 Bad Request indicates invalid JSON, missing required fields, or text exceeding the 4096-character limit. A 401 Unauthorized error occurs if the Bearer token is missing or invalid, while a 429 Too Many Requests signal means you have exceeded the 60 requests per minute rate limit.

Retry Logic

For transient errors like 429 or 5xx server errors, implement exponential backoff in your client. Since requests are processed sequentially during high load, short pauses between retries prevent overwhelming the queue. Avoid immediate rapid retries, as this may worsen congestion and delay audio generation for your users.

  • Retry on 429 with increasing delays.
  • Retry on 500-503 errors.
  • Do not retry 400 or 401 errors without input correction.

Failed Request Refunds

If synthesis fails due to a server-side error, the charge is returned in full to your balance. Failed requests do not consume your character allowance. This ensures you only pay for successfully generated audio files, maintaining transparent per-character pricing even during occasional service hiccups.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Integrating AssistVoice with existing projects is straightforward because the API mirrors the structure of the OpenAI speech endpoint. You do not need a custom client library; simply point your existing OpenAI SDK to our base URL and provide your API key. This allows startups to swap providers with minimal code changes, leveraging familiar tools for assistive device and elderly care applications.

The single active key model ensures consistent access control, while the standardized request shape means your code remains portable. By updating just the base URL and headers, you gain access to clear, natural speech voices without adopting a new ecosystem or learning a proprietary SDK format.

Base URL Change

Update your SDK configuration to use https://api.playsv77.com/v1 as the base URL. This directs all requests to our infrastructure while maintaining the standard endpoint paths. Ensure your authorization header includes your tts-... bearer token.

This change enables immediate compatibility with the 8 voice presets and 23 supported languages. Your existing logic for handling text inputs and audio outputs remains valid, requiring only this single configuration adjustment to switch from any OpenAI-compatible provider.

SDK Compatibility

The official OpenAI SDKs work seamlessly with our API. Since we adhere to the same request shape, you can use any language supported by the OpenAI client libraries (Python, Node.js, etc.).

This compatibility extends to error handling and response parsing. Your application will receive audio files in the specified format (mp3, wav, opus, flac, or pcm) without needing custom deserialization logic for our specific JSON structure.

Code Example

```python import openai client = openai.OpenAI( base_url="https://api.playsv77.com/v1", api_key="tts-your-api-key-here" ) with client.audio.speech.create( model="tts-1", voice="aria", input="Hello, this is a test of the AssistVoice API for elderly care apps.", response_format="mp3" ) as response: response.stream_to_file("output.mp3") ``` This Python snippet demonstrates the minimal code required to generate speech. Replace the API key and adjust the voice or model as needed. The response returns the audio file directly, which you can save to disk.

Quick Start with cURL

Sound wave illustration for: Quick Start with cURL

Generate audio instantly with a single command. The AssistVoice API accepts plain text and returns synthesized speech files, making it easy to test voice quality before full integration.

This quick start demonstrates the core workflow: sending a request, receiving the audio file, and verifying the output format for your assistive device or app.

cURL Example

Use this command to generate speech. Replace <YOUR_API_KEY> with your key from the dashboard.

The command sends the request to the API base URL and saves the output to speech.mp3.

  • Ensure your key starts with tts-.
  • The endpoint is https://api.playsv77.com/v1/audio/speech.
  • Set Content-Type: application/json.

JSON Body Structure

The request body requires a model, input text, and voice selection. The input field supports up to 4096 characters.

You can optionally specify a language code or speed adjustment between 0.25 and 4.0.

  • model: "tts-1" or "tts-1-hd".
  • voice: e.g., "aria", "nova", "felix".
  • input: your text string.
  • response_format: "mp3" (default).

Audio Output

The response returns the audio file directly in the body. If the request fails, a JSON error object is returned with no charge.

Generated files contain an inaudible watermark to identify synthetic speech. You can choose MP3, WAV, FLAC, OPUS, or PCM formats.

  • MP3 is recommended for general use.
  • WAV provides uncompressed quality.
  • FLAC offers lossless compression.
  • PCM is raw audio data.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Input text is used exclusively for audio generation and never for model training.

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

More on this site