API Documentation and Integration Guide for Text-to-Speech

By CursVoice editorial team · Updated 2026-11-18

This guide provides the technical specifications for integrating CursVoice’s text-to-speech API into your educational content workflows. It covers authentication, endpoint structures, and parameter configurations required to convert textbooks and course materials into audio files efficiently. You will find precise details on request limits, supported languages, and audio formats suitable for LMS platforms.

Designed for developers and instructional designers, this documentation enables seamless integration with existing systems. We cover OpenAI SDK compatibility, rate limits, and error handling to ensure reliable processing of long-form educational content. Use these specifications to automate audio generation for your online courses without manual recording.

API Documentation and Integration Guide for Text-to-Speech

Frequently asked questions

How do I authenticate with the API?

Include an Authorization: Bearer tts-... header with your unique API key in every request. Each account holds one active key; issuing a new key immediately invalidates the previous one. Ensure the key is sent with every synthesis call to verify your account.

What is the base URL for the API?

The base URL is https://api.playsma77.com/v1. Use https://api.playsma77.com/v1/audio/speech for the POST endpoint to generate audio. This structure mirrors the OpenAI API format, allowing standard HTTP clients and SDKs to connect by simply adjusting the base URL configuration in your integration settings.

Can I use the OpenAI SDK with this API?

Yes. The endpoint shape matches the OpenAI speech endpoint. Configure your OpenAI SDK client to use https://api.playsma77.com/v1 as the base URL. Pass your CursVoice API key as the API key. This allows you to use existing OpenAI SDK libraries without writing custom HTTP request logic from scratch.

What are the supported audio formats?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the desired format using the response_format field in your JSON request body. The API returns the audio file directly in the response, allowing you to choose the format that fits your LMS or delivery pipeline.

How many requests can I make per minute?

The rate limit is 60 requests per minute per API key. New accounts without a top-up are limited to 10 requests per minute. If you exceed the limit, requests may be queued or rejected. Ensure your integration handles rate limiting gracefully, especially when processing long texts split into multiple chunks.

What happens if I exceed the rate limit?

Requests are processed sequentially, so under load a request may wait in a queue. If the queue backs up or the limit is strictly enforced, you may receive a rate limit error. Monitor your request timing and implement exponential backoff in your client to handle temporary throttling effectively.

How do I specify the voice for synthesis?

Include the voice field in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narrator to deep documentary. You can also optionally specify the language to ensure correct pronunciation for non-English texts.

Is the API compatible with Python SDK?

Yes, it is compatible with the official OpenAI Python SDK. Set the base_url to https://api.playsma77.com/v1 and provide your CursVoice API key. This allows you to use standard Python libraries for TTS synthesis without building custom HTTP clients, leveraging existing code patterns and error handling mechanisms.

How do I handle errors in the response?

The API returns standard HTTP status codes for errors, such as 400 for bad requests or 429 for rate limits. Failed synthesis requests are free, and charges are returned in full. Check the response body for error details and implement logic to retry or adjust parameters based on the specific error code received.

What is the maximum input text length?

Each request supports up to 4096 characters of input text. For longer texts, split the content into chunks of this size and join the resulting audio files. Spaces and punctuation count toward the character limit. This ensures efficient processing while maintaining audio continuity across segments for long-form educational content.

Can I change the speed of the audio?

Yes, use the speed parameter to adjust playback speed between 0.25 and 4.0. The default speed is 1.0. Adjusting speed allows you to optimize audio length for different learning contexts. Faster speeds may reduce listening time, while slower speeds can improve clarity for complex educational material.

How do I list available voices?

Send a GET request to /v1/voices. This endpoint returns details on available voices, languages, and formats. You can use this endpoint to dynamically populate your UI with voice options or verify supported languages before initiating a synthesis request, ensuring correct voice and language configuration.

What models are available for synthesis?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing structure. Select the model that best fits your quality requirements. The API treats both models identically in terms of functionality, allowing you to switch between them without changing your request structure or integration logic.

Is there a limit on the response format size?

There is no explicit file size limit for the response format. The limit is defined by the input text length (4096 characters) and the audio duration generated. Larger texts produce longer audio files, which are returned directly in the response. Ensure your client can handle variable response sizes for long texts.

First request

curl

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

Authentication is handled via a single active API key per account, issued on the /get-api-key/ dashboard. This key authorizes all requests to the TTS engine and is the sole credential required for both the free trial and paid usage.

API Key Usage

API Key Usage

Include your key in the HTTP Authorization header as a Bearer token. The key format is tts-... and is generated when you sign up via Google or email. Ensure the key is transmitted securely, as it provides direct access to your account balance and usage quota.

  • One active key per account
  • Sent via Authorization header
  • Format: Bearer tts-...

Bearer Token Format

Bearer Token Format

The token must be passed exactly as Authorization: Bearer tts-<your-key>. Any deviation in the header name or token prefix may result in authentication failures. The key remains valid until you manually issue a new one.

Key Management

You can generate a new key at any time from the dashboard. Upon issuance, the previous key becomes invalid immediately. This allows you to rotate credentials without downtime, ensuring secure access for your instructional design pipelines.

  • Regenerate key anytime
  • Old key stops instantly
  • No key expiration

Endpoints

Sound wave illustration for: Endpoints

CursVoice exposes a RESTful API for generating audio and retrieving metadata. The primary endpoint handles synthesis, while secondary endpoints provide voice lists and model details. All requests use standard HTTP methods and JSON payloads, compatible with the OpenAI SDK structure.

Speech Generation

Send text to receive an audio file. Use POST /v1/audio/speech with a JSON body containing the text, voice, and format. Text is limited to 4096 characters per request. For longer texts, split and join the resulting audio files.

  • Endpoint: POST /v1/audio/speech
  • Accepts: mp3, wav, opus, flac, pcm
  • Input limit: 4096 characters

Voice Listing

Retrieve available voices, languages, and formats using GET /v1/voices. This endpoint confirms the 8 preset voices and 23 supported languages. It helps developers verify available options before synthesis.

  • Endpoint: GET /v1/voices
  • Returns: Voice list, languages, formats
  • 8 presets available

Model Information

Fetch model details via GET /v1/models. The API supports two model variants: tts-1 and tts-1-hd. Both use the same engine and pricing, allowing consistent integration regardless of quality preference.

  • Endpoint: GET /v1/models
  • Models: tts-1, tts-1-hd
  • Same engine, same price

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts a simple JSON body to generate audio. You must specify the model, input text, and voice to ensure the synthesis matches your educational content requirements.

Requests are processed sequentially, so longer texts may queue. Ensure your input stays within character limits to avoid truncation or additional processing time.

Model Selection

Choose between 'tts-1' and 'tts-1-hd'. Both use the same engine and pricing, so select based on your preference for audio fidelity versus processing speed.

The model parameter does not affect voice characteristics; it only defines the synthesis engine quality.

  • tts-1: Standard quality
  • tts-1-hd: High definition audio

Input Text Limits

The maximum input length is 4096 characters per request. Spaces and punctuation count toward this limit.

For textbooks or course materials exceeding this length, split the text into parts, generate each audio file, and join them client-side.

  • Max 4096 characters per request
  • Includes spaces and punctuation

Voice Selection

Select from 8 presets (e.g., 'aria', 'nova', 'felix') that suit different instructional styles, from calm narration to energetic promos.

Set the optional 'language' parameter if using Latin-script text in non-English languages to ensure accurate pronunciation, as the API defaults to English.

  • 8 voice presets available
  • Optional 'language' ISO code supported

Response Formats

Sound wave illustration for: Response Formats

The API returns synthesized audio directly in the response body, allowing you to save the file locally or play it in your LMS player. Supported formats include mp3, wav, opus, flac, and pcm, ensuring compatibility with various educational platforms and devices.

Audio File Types

Choose the format that best fits your bandwidth and quality needs. MP3 is recommended for most web players due to its balance of size and quality, while WAV offers uncompressed lossless audio for high-fidelity archival. OPUS provides efficient compression, and FLAC offers lossless compression without quality loss. PCM returns raw uncompressed audio data.

  • mp3: Standard compressed audio, ideal for web playback
  • wav: Uncompressed, lossless audio for high-quality needs
  • opus: Efficient compression for streaming applications
  • flac: Lossless compressed audio
  • pcm: Raw uncompressed audio data

Error Codes

If synthesis fails, the request is free, and any charge is returned in full. Common errors include invalid API keys, exceeding rate limits (60 requests/minute), or input text exceeding 4096 characters. Each error response includes a clear code and message to help you debug quickly.

  • 401: Unauthorized – Invalid or expired API key
  • 429: Too Many Requests – Rate limit exceeded
  • 400: Bad Request – Invalid parameters or text too long
  • 500: Internal Server Error – Temporary synthesis failure

Success Response

A successful request returns a 200 status code with the audio file in the specified format. The response includes the binary audio data. You can directly save this output to a file or pipe it into your audio player.

Rate Limits

Sound wave illustration for: Rate Limits

The API enforces a limit of 60 requests per minute per active key. Requests are processed sequentially, so under load a request may wait in a queue. Long texts are split into parts, counting as multiple requests.

Failure to adhere to these limits results in temporary access restrictions. Monitoring your usage via the dashboard helps prevent unexpected interruptions during bulk generation tasks.

Requests Per Minute

Each API key is limited to 60 requests per minute. This limit applies to the total number of synthesis attempts, regardless of text length.

Requests are processed one after another. Under heavy load, your request may wait in a queue before synthesis begins.

  • Limit: 60 requests/minute/key
  • Processing: Sequential
  • Queue: Possible under load

Pre-Trial Limits

Accounts created with email and password start without trial credit.

Google-sign-up accounts receive a $0.50 trial but are subject to the 10 requests/minute limit until the first top-up.

  • Standard limit: 60 req/min
  • Pre-top-up limit: 10 req/min

Limit Exceeded Errors

Exceeding the rate limit returns a 429 Too Many Requests error. The response includes a Retry-After header indicating when to retry (for 429 errors).

Retry logic should implement exponential backoff to handle queue delays effectively.

  • Error Code: 429
  • Header: Retry-After
  • Strategy: Exponential backoff
Rate Limits

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Configure the OpenAI Python SDK by overriding the base URL to point to the CursVoice API. This allows you to use the standard openai client with your API key, ensuring seamless integration into existing educational content workflows without requiring custom HTTP clients.

Base URL Configuration

Set the base_url parameter in your SDK client initialization to https://api.playsma77.com/v1. This directs all requests to the correct endpoint while maintaining standard request shapes.

  • Use the official OpenAI SDK for Python or Node.js.
  • Replace the default base URL with your specific domain endpoint.

SDK Compatibility

The API accepts the same request body structure as the OpenAI speech endpoint. You can use standard model identifiers tts-1 or tts-1-hd without modification. Authentication requires a Bearer token in the Authorization header.

Code Examples

Initialize the client with your key and custom base URL. Pass the text, voice, and format parameters directly to the audio.speech.create method. The SDK returns the audio file object for immediate playback or storage.

Ensure you handle the 60 requests per minute rate limit by implementing basic retry logic if necessary, especially when processing large course materials.

Curl Example

Sound wave illustration for: Curl Example

The following curl command demonstrates a standard synthesis request. It sends a short text payload to the speech endpoint, specifying the model, voice, and output format. This serves as a baseline for verifying connectivity before integrating into larger LMS workflows.

Basic Request

Execute the command below, replacing YOUR_API_KEY with your actual credential. The request targets the tts-1 model with the nova voice, outputting an MP3 file. This structure matches the OpenAI API shape, ensuring immediate compatibility.

Headers

The Authorization header must include the Bearer prefix followed by your unique key. The Content-Type is set to application/json to ensure the server correctly parses the input text and configuration parameters in the body.

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

Response Handling

On success, the response body contains the raw audio binary data. Save this directly to a file using shell redirection. If the request fails, the response will include a JSON error object detailing the issue, such as invalid parameters or insufficient balance.

Error Handling

Sound wave illustration for: Error Handling

Synthesis failures return a full credit refund, ensuring you only pay for successfully generated audio. The API distinguishes between client-side parameter errors and server-side processing issues.

Common Errors

Invalid voice IDs or unsupported languages trigger 400 errors. Input text exceeding 4096 characters per request also fails immediately.

  • 400: Bad Request (invalid parameters)
  • 401: Unauthorized (invalid or expired key)
  • 429: Too Many Requests (rate limit exceeded)

Retry Logic

Implement exponential backoff for 429 errors. Requests are processed sequentially; high load may increase latency, but failed requests are free.

Status Codes

200 OK returns the audio binary. 400–499 errors indicate request issues, while 500–599 errors may occur during peak processing times.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The request shape is identical to industry standards, meaning minimal code changes are needed to switch or integrate.

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 API reference: create speech
  3. IETF RFC 7845: Ogg Opus
  4. Creative Commons Attribution 4.0
  5. Python documentation
  6. TRON developer hub: TRC-20
  7. curl documentation
  8. LibriVox public-domain audiobooks
  9. MDN: Web Speech API
  10. LibriTTS-R corpus (OpenSLR 141)
  11. W3C WAI: making audio and video accessible
  12. FFmpeg documentation

More on this site