API Documentation for Text-to-Speech Integration

By MediVoice editorial team · Updated 2026-11-19

This documentation outlines the API integration process for SaneReads, a text-to-speech service designed for large healthcare teams creating patient guides and clinical content at scale. You will find precise technical details for sending text to our endpoint and receiving audio files, along with examples using cURL and the official OpenAI SDK.

We cover the available models, voice presets, and response formats suitable for medical audio generation. The guide also explains rate limits, error handling, and how to manage long texts by splitting them into manageable chunks. Use this reference to integrate our reliable TTS API into your existing workflows without manual recording overhead.

API Documentation for Text-to-Speech Integration

Frequently asked questions

What is the API endpoint?

Send a POST request to https://api.titan33.info/v1/audio/speech with a JSON body. The request shape matches the OpenAI speech endpoint, allowing you to use standard HTTP clients or the OpenAI SDK by adjusting the base URL.

Do I need to install a specific SDK?

No proprietary SDK is required. You can use the official OpenAI SDKs by changing the base_url to https://api.titan33.info/v1 and providing your site’s key. Standard HTTP libraries work equally well for sending requests and receiving audio files.

How do I handle long medical texts?

Split your text into parts of up to 4096 characters and send each part as a separate request. Then, join the resulting audio files to create a continuous audio track. This ensures compliance with character limits while preserving the full content.

What is the maximum character limit?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer medical guides, you must split the text into multiple requests and concatenate the returned audio files to maintain continuity.

Can I change the speed of the voice?

Yes, you can adjust the speed using the speed field in the request body. The acceptable range is 0.25 to 4.0, allowing you to slow down complex medical explanations or speed up routine patient instructions to fit your specific workflow needs.

How do I specify the language?

Include the optional language field with an ISO code. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin text, explicitly set the language to ensure accurate synthesis for your patient guides.

Is the API synchronous or asynchronous?

The API is synchronous. You send a request and receive the audio file directly in the response. However, requests are processed sequentially, so under heavy load, your request may wait in a queue before synthesis begins.

What happens if the service is busy?

Requests are processed one after another. If the service is under load, your request may wait in a queue. Typical speed is roughly real-time, but short phrases may take a few seconds to generate.

Can I use the same key for multiple projects?

Yes, each account has one active key that can be used across multiple projects. You can issue a new key at any time, which immediately invalidates the old one, allowing you to rotate credentials easily across different teams or apps.

How do I authenticate requests?

Include the Authorization: Bearer tts-... header in your requests. Use the API key provided in your account dashboard. Ensure you are using the correct key associated with your account to avoid authentication errors when generating audio files.

What is the response format?

The response contains the generated audio file directly. You can specify the format using the response_format field, choosing from mp3, wav, opus, flac, or pcm. The audio is returned immediately upon successful synthesis of the input text.

Are there any headers required?

You must include the Authorization: Bearer <your-key> header. Additionally, ensure your Content-Type is set to application/json when sending the request body. These headers are essential for authenticating your request and ensuring the server processes your JSON payload correctly.

How do I test the API before paying?

Sign in with Google to receive a free trial with $0.50 of credit, valid for 7 days. This allows you to generate about 50,000 characters of audio without immediate payment. Email/password accounts do not receive this trial credit initially.

What is the base URL for the API?

The base URL is https://api.titan33.info/v1. Use this for the speech endpoint and other API routes. You can configure the OpenAI SDK to use this base URL, enabling seamless integration with your existing medical software infrastructure.

First request

curl

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

Get your API key

Sound wave illustration for: Get your API key

Sign up on the dashboard at /get-api-key/ using Google or an email/password combination. The dashboard displays your active Bearer token, current balance, and a ready-to-use cURL example tailored for medical text generation.

Retrieve your Bearer token

Retrieve your Bearer token

Your key starts with tts- and authenticates all API requests. Pass it in the Authorization: Bearer header. One key per account ensures clear usage tracking for your team’s billing.

  • Keys are displayed directly on the dashboard after sign-in.
  • Use the provided cURL example to test connectivity immediately.

Rotate keys if needed

Rotate keys if needed

Issue a new key at any time from the dashboard. The previous key stops working instantly, ensuring no overlap or accidental usage with the old token.

  • Instant invalidation of the old key.
  • New key generated without downtime.

Make your first request

Sound wave illustration for: Make your first request

Once you have your API key, you can immediately start converting medical text into audio. The endpoint POST https://api.titan33.info/v1/audio/speech accepts your JSON payload and returns the synthesized audio file. This simple structure allows healthcare teams to integrate TTS into patient guide workflows without complex infrastructure.

You can test the integration quickly using cURL or any HTTP client. The request requires a valid Bearer token in the authorization header, ensuring that only authorized accounts consume character credits from the balance.

Using cURL for quick tests

Use cURL to verify your key and voice selection before building the full application. This confirms that the API responds correctly to your specific medical text samples.

```bash curl -X POST https://api.titan33.info/v1/audio/speech \ -H "Authorization: Bearer tts-your-api-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello, this is your daily medication reminder.", "voice": "aria", "response_format": "mp3"}' ```

  • Replace tts-your-api-key with your actual key.
  • Ensure the API key has sufficient balance.
  • Check the response for the audio binary or error JSON.

JSON body structure

The request body is a standard JSON object. It includes the model identifier, the text to be spoken, the chosen voice, and the desired output format. Speed can be adjusted between 0.25 and 4.0 for faster patient education or slower, clearer delivery for elderly users.

All fields are sent in a single payload. The API processes the text up to 4096 characters per request, returning the audio file directly in the response.

  • model: "tts-1" or "tts-1-hd".
  • input: The text string (up to 4096 characters).
  • voice: One of the 8 available presets.
  • response_format: mp3, wav, opus, flac, or pcm.

Required and optional fields

The model, input, and voice fields are required for every synthesis request. The response_format defaults to MP3 if not specified. You may optionally provide a language ISO code to ensure correct pronunciation for non-English medical terms.

If the language field is omitted, the system guesses the language from the script. For Latin-script text, it defaults to English. For other languages, explicitly setting the language code ensures accurate synthesis for your patient guides.

  • model (required): "tts-1" or "tts-1-hd".
  • input (required): Your medical text.
  • voice (required): e.g., "aria", "nova", "sage".
  • language (optional): ISO code for precise control.

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

The SaneReads API mirrors the standard OpenAI speech endpoint structure, allowing your healthcare team to reuse existing integration patterns. By simply adjusting the base URL, you can switch from OpenAI’s service to our TTS endpoint without modifying your core application logic or voice selection code.

This approach minimizes development overhead for clinical content teams already familiar with OpenAI’s SDKs. You maintain full control over voice selection, speed, and output format while leveraging a reliable, scalable infrastructure designed for high-volume medical text generation.

Set the base_url endpoint

Point your SDK client to https://api.titan33.info/v1 instead of the default OpenAI URL. This single change directs all speech requests to our infrastructure while preserving the familiar request body structure you already know.

Ensure your SDK version supports custom base URLs. Most modern OpenAI Python or Node.js SDKs handle this configuration seamlessly, allowing you to keep your existing voice and model parameters intact.

  • Base URL: https://api.titan33.info/v1
  • Compatible with official OpenAI SDKs
  • No custom client library required

Use official SDK methods

Call the standard audio.speech.create method exactly as you would for OpenAI. Pass your desired model (tts-1 or tts-1-hd), voice preset, input text, and optional parameters like speed or language directly into this function.

The SDK handles JSON serialization and response parsing automatically. You receive the audio binary data, which you can then save as MP3, WAV, or other supported formats for your patient guides or clinical audio content.

Since the request shape is identical, you can swap the endpoint without changing your error handling or retry logic, ensuring a smooth transition for your development team.

  • Method: audio.speech.create()
  • Supports all standard parameters
  • Returns audio binary data

Pass your API key

Include your Bearer token in the SDK’s authentication header. Retrieve this token from your SaneReads dashboard at /get-api-key/ after signing in with Google or your email account.

The key must start with tts- and be sent as Authorization: Bearer tts-.... If you rotate your key, the old one stops immediately, so ensure your applications are updated promptly to avoid service interruptions.

Keep your key secure in your environment variables. Since each account has only one active key, losing it means generating a new one from the dashboard.

  • Token format: Bearer tts-...
  • Retrieve from /get-api-key/
  • One active key per account

Available models and voices

Sound wave illustration for: Available models and voices

Our API offers two models, tts-1 and tts-1-hd, which use the same underlying engine and pricing. This consistency ensures that switching between standard and high-definition audio does not affect your character count billing or integration logic, simplifying development for healthcare teams managing large volumes of clinical content.

tts-1 standard model

The tts-1 model provides efficient, clear speech suitable for most patient guides and instructional materials. It processes text at roughly real-time speed, making it ideal for generating bulk audio files without significant latency.

tts-1-hd model

Use tts-1-hd when higher audio fidelity is required for complex medical terminology or detailed clinical explanations. It incurs the same rate of $0.01 per 1,000 characters as the standard model, so you can upgrade quality without unexpected cost increases.

8 voice presets for different tones

Select from eight distinct voices, each designed for specific communication styles. You can choose warm narrators like Aria or calm instructors like Sage for patient education, or use energetic voices like Felix for promotional health updates.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion
  • All voices support 23 languages, including English, Spanish, and German
  • Each audio file includes an inaudible watermark marking it as synthetic

Response formats

Sound wave illustration for: Response formats

The API returns audio files in formats specified by the response_format parameter. Choose based on your delivery needs: MP3 for broad web compatibility, WAV for lossless quality, or Opus, FLAC, and PCM for specialized workflows.

MP3 for web compatibility

MP3 is the default and most versatile choice. It balances file size and quality, making it ideal for embedding patient guides in web apps or mobile interfaces where bandwidth matters.

WAV for high fidelity

WAV provides uncompressed, lossless audio. Use this format when storing archival patient records or when downstream processing requires raw PCM data. It results in larger files but ensures maximum clarity.

Opus, FLAC, and PCM options

Opus offers high efficiency for low-bandwidth environments. FLAC provides lossless compression, reducing storage needs while preserving audio integrity. PCM returns raw, uncompressed audio data, useful for immediate playback in specific hardware or software pipelines.

Response formats

Rate limits and performance

Sound wave illustration for: Rate limits and performance

Your API key allows 60 requests per minute once established. This limit applies per key, so ensure your healthcare team shares the credential or issues separate keys for parallel patient guide generation.

60 requests per minute limit

After your initial period, the standard rate is 60 requests per minute. This supports batch processing of clinical content without overwhelming the service.

10 requests per minute initially

New accounts start with a lower limit of 10 requests per minute. This applies until you complete your first top-up, ensuring stable service during early testing.

Processing queue under load

Requests are processed sequentially. Under heavy load, synthesis may wait in a queue. Expect roughly real-time generation speed, averaging 25 characters per second.

Handling errors

Sound wave illustration for: Handling errors

API errors are returned with standard HTTP codes to help you diagnose issues quickly. Most failures, such as invalid keys or malformed JSON, return a 400 or 401 status, allowing immediate correction without consuming your character balance.

Failed synthesis requests are always free, so you can retry safely. If a temporary network hiccup occurs, the system does not charge you, ensuring your billing remains accurate even during transient instability.

Common HTTP status codes

Use 401 for authentication failures (check your Bearer token) and 400 for malformed requests. A 429 indicates you have exceeded the 60 requests per minute limit, while 500 errors are rare server-side issues that you can retry.

Retry logic recommendations

Implement exponential backoff for 429 and 500 errors. Since requests are processed sequentially, a brief pause between retries helps avoid queue congestion. Always check the response body for specific error messages to guide your next step.

Remember that failed requests do not deduct from your balance, so aggressive retries are safe as long as you stay within the per-minute rate limits.

Character limit exceeded errors

The API rejects any single request with more than 4096 characters, returning a 400 error. To handle long medical texts, split your content into chunks of up to 4096 characters, generate audio for each, and join the files programmatically.

This approach ensures reliable processing and keeps individual request times short, which is crucial for maintaining smooth workflows in large healthcare teams.

Audio generation details

Sound wave illustration for: Audio generation details

Audio generation typically runs at roughly real-time speed, processing about 25 characters per second for longer texts. Short phrases may take a few seconds to synthesize, and requests are processed sequentially, meaning under heavy load a request might wait in a queue before starting.

Real-time speed approximation

Generation speed scales with text length. While long documents produce audio at roughly real-time speed, brief inputs require a few seconds to synthesize.

Handling long texts with splitting

Each request supports up to 4,096 characters. For longer medical guides, split the input into chunks, generate each audio file, and join them sequentially.

Inaudible watermark inclusion

Every generated audio file includes an inaudible watermark, marking the content as synthetic speech. This applies to all formats and voices without affecting playback quality.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Their upbeat, rapid cadence can obscure important medical details, especially for those with hearing impairments.

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. curl documentation
  3. openai-node on GitHub
  4. LibriTTS-R corpus (OpenSLR 141)
  5. OpenAI API reference: create speech
  6. Tether (USDT)
  7. ISO 639 language codes
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. openai-python on GitHub
  10. W3C WAI: making audio and video accessible
  11. Creative Commons Attribution 4.0
  12. MDN: Web Speech API

More on this site