Getting Started with VocalCare API Integration

By VocalCare editorial team · Updated 2026-11-18

This guide helps product teams build accessible reading experiences for elderly users and assistive devices. You will learn how to send text and receive natural audio files via our reliable TTS API. The documentation covers authentication, endpoints, and parameters needed to integrate VocalCare into your workflow.

We provide a straightforward integration path using standard HTTP requests or the official OpenAI SDK. You can manage your API key, select from eight voice presets, and handle rate limits effectively. Follow these steps to convert text into audio, ensuring your content is easier to consume for users with visual impairments or reading difficulties.

Getting Started with VocalCare API Integration

Frequently asked questions

How do I get an API key?

Sign up on /get-api-key/ using Google or email. Google sign-ins receive a $0.50 trial credit valid for 7 days. Email accounts start without credit. Each account has one active key; issuing a new one immediately invalidates the old one.

What is the base URL?

The API base URL is https://api.playak77.com/v1. Use this for all requests, including the speech endpoint at /audio/speech. This base URL allows compatibility with standard HTTP clients and SDKs that support custom base URL configuration.

Which SDKs are compatible?

The request shape matches the OpenAI speech endpoint. Official OpenAI SDKs work by changing the base URL to https://api.playak77.com/v1. You can also use any standard HTTP client to send JSON requests to the endpoint.

How do I send a request?

Send a POST request to https://api.playak77.com/v1/audio/speech with a JSON body. Include the model, input text, voice, response format, and optional speed or language. The API returns the generated audio file directly in the response.

What are the rate limits?

Limits are 60 requests per minute per key. New accounts without top-ups are limited to 10 requests per minute. Requests are processed sequentially, so high load may cause queuing delays. Longer texts are split into 4096-character chunks.

How do I handle errors?

Failed requests are free, and the charge is returned in full if synthesis fails. Monitor response status codes to detect errors. Ensure your input text is under 4096 characters. Check your balance and key validity if requests fail unexpectedly.

What audio formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. Specify the desired format using the response_format field in your request body. All generated files include an inaudible watermark marking them as synthetic speech for identification purposes.

How do I choose a voice?

Choose from eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrators to deep documentaries. All voices support all 23 listed languages, regardless of the voice's original style.

Can I use OpenAI SDK?

Yes, the official OpenAI SDKs work by setting the base URL to https://api.playak77.com/v1. The request structure matches the OpenAI speech endpoint exactly. This allows you to use familiar code patterns without needing a custom SDK.

How do I authenticate?

Include your API key in the Authorization header as a Bearer token: Authorization: Bearer tts-... . Each account has one active key. Issuing a new key immediately invalidates the previous one, so update your headers accordingly.

What is the request body?

The JSON body includes model (tts-1 or tts-1-hd), input (text up to 4096 chars), voice, and response_format. Optional fields are speed (0.25–4.0) and language (ISO code). Spaces and punctuation count toward the character limit.

How do I check voices?

Send a GET request to /v1/voices to retrieve available voices, languages, formats, and pricing. This endpoint provides the complete list of eight presets and their supported attributes. Use this data to select the best voice for your content.

What happens if I exceed limits?

Requests may wait in a queue if you exceed the 60 requests per minute limit. Processing is sequential, so delays occur under load. Failed requests do not incur charges. Ensure your application handles potential latency gracefully during high usage.

How do I retry a request?

Retry failed requests as they are free. For successful requests, the audio is returned immediately. If you exceed rate limits, wait for the queue to clear or retry after the minute resets. Split long texts into smaller chunks.

First request

curl

curl https://api.playak77.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.playak77.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.playak77.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

VocalCare secures your API access through a simple key system. You can generate your unique key on the /get-api-key/ page using either a Google account or an email and password. This key acts as your credential for all subsequent requests to the API.

Each account is limited to one active key at a time. You can issue a new key at any time, which immediately invalidates the previous one, ensuring your access remains secure and up-to-date without needing complex rotation procedures.

Get Your API Key

Get Your API Key

Visit the /get-api-key/ page to create your account. Choose between signing in with Google for a $0.50 trial credit or using an email and password for a standard account. Once registered, your unique API key is displayed alongside your balance, trial status, and usage statistics.

  • Sign up via Google or email/password
  • Immediate access to your unique key
  • View balance and character limits instantly

Bearer Token Format

Bearer Token Format

Include your key in the HTTP header as a Bearer token. The format is strictly 'Authorization: Bearer tts-...' followed by your specific alphanumeric key string. Ensure there are no extra spaces or characters in the token value to avoid authentication errors.

Key Management

You hold one active key per account. If you suspect a leak or need a fresh start, generate a new key on your dashboard. The old key stops working immediately upon the new key's creation, providing instant security without downtime for your assistive device integration.

  • One active key per account
  • Instant invalidation of old keys
  • Regenerate anytime via dashboard

Endpoints

Sound wave illustration for: Endpoints

The API exposes three primary endpoints to manage your text-to-speech workflow. The Speech endpoint processes your input, while Voices and Models endpoints provide metadata for configuration.

Speech Endpoint

POST to /v1/audio/speech to generate audio. Send JSON with model, input text, voice, and format. Receive an audio file directly.

  • Endpoint: POST https://api.playak77.com/v1/audio/speech
  • Returns: Audio file (mp3, wav, opus, flac, pcm)

Voices Endpoint

GET /v1/voices returns available presets, supported languages, formats, and price. Use this to select from the 8 voice options before sending speech requests.

  • Endpoint: GET https://api.playak77.com/v1/voices
  • Returns: List of voices, languages, and formats

Models Endpoint

GET /v1/models lists available models like tts-1 and tts-1-hd. Both use the same engine and pricing structure.

  • Endpoint: GET https://api.playak77.com/v1/models
  • Returns: Available model identifiers

Request Parameters

Sound wave illustration for: Request Parameters

Configure the core parameters to generate speech that fits your assistive reading workflow. You define the audio format, content length, and speaker voice to ensure clear, accessible output for elderly users or those with visual impairments.

Each parameter directly influences how the text is synthesized, ensuring the resulting audio is natural and easy to understand for your target audience.

Model Selection

Choose between tts-1 for standard quality or tts-1-hd for higher fidelity. Both use the same engine and pricing, allowing you to upgrade audio clarity for complex medical instructions or educational content without changing your integration logic.

  • tts-1: Standard quality
  • tts-1-hd: Higher fidelity

Input Text

Pass your content as the input field, supporting up to 4096 characters per request. Spaces and punctuation count toward this limit, so plan your splits carefully for longer articles or manuals.

For texts exceeding this limit, split the content into chunks and join the resulting audio files to maintain continuous playback for users.

  • Max 4096 characters per request
  • Spaces and punctuation count

Voice Selection

Select from 8 presets to match the tone of your assistive device. Use sage for calm, instructional guidance or nova for upbeat, engaging content. Every voice supports all 23 languages, allowing flexible localization.

Set the language parameter explicitly for non-English Latin text to prevent incorrect guessing, as Latin text defaults to English.

  • 8 voice presets available
  • Supports 23 languages
  • Explicit language setting recommended

Response Format

Sound wave illustration for: Response Format

The API returns the synthesized audio directly in the response body, allowing your application to save the file immediately. You can choose from mp3, wav, opus, flac, or pcm formats via the response_format parameter, ensuring compatibility with your specific assistive device or web player requirements.

Audio Files

Generated audio files are delivered as binary data. The length of the audio roughly matches the input text duration, typically requiring about 25 characters of text per second of generation time for long texts. These files are not stored on our servers after delivery, preserving privacy for your elderly users’ reading sessions.

  • Formats: mp3, wav, opus, flac, pcm
  • No server-side storage of generated audio
  • Inaudible watermark marks synthetic speech

Headers

Response headers provide metadata about the request, including the character count processed and the model used. This data helps you track usage against your balance and debug any discrepancies in character billing.

Status Codes

A 200 OK status indicates successful synthesis, returning the audio file. If the request fails (e.g., invalid text or key), you will receive an error JSON body. Crucially, failed requests are free, and any pre-charged amount is returned in full to your balance.

Rate Limits

Sound wave illustration for: Rate Limits

VocalCare enforces strict rate limits to ensure stable synthesis for assistive device workflows. New accounts start with a 10 requests-per-minute limit. This cap applies until your first top-up is processed, allowing you to test the API without immediate throttling.

60 Requests/Minute

Once you add funds via USDT on the TRON network (TRC-20), your limit increases to 60 requests per minute per API key. This steady throughput supports batch processing for elderly reading applications, though requests are processed sequentially and may queue under load.

10 Requests/Minute (Initial)

Before your first top-up, you are restricted to 10 requests per minute. This allows sufficient testing of voice presets and text lengths. Once you top up, the higher limit activates automatically within minutes after the transfer is credited.

Queue Processing

Requests are processed sequentially. If you exceed the limit, new requests enter a queue. Under heavy load, synthesis may take longer than the typical real-time speed of 25 characters per second. Please design your integration to handle these queues gracefully.

  • Requests are processed one after another.
  • Queueing occurs when limits are exceeded.
  • Long texts may experience longer wait times.
Rate Limits

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

To use the OpenAI SDK with VocalCare, configure the base URL to https://api.playak77.com/v1. This allows you to use the official SDKs by simply pointing them to our endpoint, ensuring seamless integration for product teams building accessible reading experiences.

Base URL Configuration

Set the base URL in your SDK client to https://api.playak77.com/v1. This single change redirects all requests to our TTS API, maintaining the same request shape as the OpenAI speech endpoint.

SDK Compatibility

The API is compatible with official OpenAI SDKs. You can use any language supported by these SDKs, passing your Bearer token via the standard Authorization header.

  • Works with any language supported by the official OpenAI SDKs

Example Code

Initialize the client with your key and the custom base URL. Then call the speech method with your model, voice, and input text to receive an audio file.

  • import OpenAI
  • client = OpenAI(base_url="https://api.playak77.com/v1", api_key="tts-...")
  • audio = client.audio.speech.create(model="tts-1", voice="aria", input="Hello, world!")

Error Handling

Sound wave illustration for: Error Handling

Errors are handled with standard HTTP status codes. The API returns clear messages for invalid inputs, such as text exceeding 4096 characters or unsupported voices. Failed synthesis requests are free, ensuring you are not charged for wasted effort. This reliability is critical for assistive devices where predictable audio output is essential for elderly users.

Understanding these errors helps product teams build robust reading experiences. By checking status codes, your application can gracefully handle issues without disrupting the user's flow, ensuring accessible content remains available even when technical hiccups occur.

Common Errors

The API uses standard HTTP status codes to indicate success or failure. Common issues include invalid JSON structures or missing required fields like input or voice. Ensure your text does not exceed 4096 characters per request to avoid truncation errors.

  • 400 Bad Request: Invalid JSON or missing fields
  • 401 Unauthorized: Invalid or expired API key
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Temporary synthesis failure

Failed Requests

If synthesis fails for any reason, the charge is returned in full. This ensures you only pay for successful audio generation. Failed requests do not consume your character balance, making it safe to retry failed attempts without financial penalty.

Retry Logic

Implement exponential backoff for transient errors. Since requests are processed sequentially, under load a request may wait in a queue. Retrying with a short delay helps avoid hitting rate limits during high-traffic periods.

Curl Example

Sound wave illustration for: Curl Example

This section demonstrates how to generate audio using the VocalCare API via a simple cURL command. It covers the essential components required for a successful request, ensuring your product team can quickly integrate text-to-speech into assistive devices for elderly users.

Basic Request

Send a POST request to the speech endpoint with your text and preferred settings. The following example uses the 'tts-1' model to convert a short phrase into an MP3 file.

Headers

Include your API key in the Authorization header. Use the Bearer token format, and set the Content-Type to application/json. Ensure your key starts with 'tts-' and is valid for the current account.

  • Authorization: Bearer tts-your-api-key-here
  • Content-Type: application/json

Response

The API returns the audio file directly in the response body. Use this data to select a voice for your content. If synthesis fails, the charge is returned in full, and you receive an error JSON object instead of audio.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Designing assistive devices for the elderly demands a deep empathy for their unique daily challenges and physical limitations.

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. W3C WAI: making audio and video accessible
  4. IETF RFC 7845: Ogg Opus
  5. LibriVox public-domain audiobooks
  6. curl documentation
  7. Node.js documentation
  8. Python documentation
  9. ISO 639 language codes
  10. MDN: Web Speech API
  11. Tether (USDT)
  12. OpenAI API reference: create speech

More on this site