Text-to-Speech API Documentation for Developers

By Curisum editorial team · Updated 2026-11-18

This guide helps indie developers integrate Curisum Audio’s text-to-speech API into their digital news platforms. You will find clear examples for generating audio from article text, managing your API key, and handling responses efficiently. The documentation covers every endpoint you need to turn written content into natural-sounding speech for your audience.

We provide specific details on request structures, available voices, and rate limits so you can build reliable audio pipelines. Whether you are converting short updates or long articles, this reference ensures you understand the parameters, formats, and constraints. Use this page to get your integration running quickly and correctly.

Text-to-Speech API Documentation for Developers

Frequently asked questions

What is the API endpoint URL?

The endpoint for generating audio is POST https://api.kurisumala.com/v1/audio/speech. You send a JSON body containing the text, model, voice, and other parameters to this URL to receive the synthesized audio file as a response.

How do I get an API key?

Sign up on the /get-api-key/ page using Google or an email and password. Once registered, your account dashboard displays your active API key, which you use for authentication in the Authorization header of your requests.

Can I use the OpenAI SDK?

Yes, the official OpenAI SDKs work perfectly. You simply change the base_url to https://api.kurisumala.com/v1 and use your Curisum Audio API key. The request shape is identical to the OpenAI speech endpoint, ensuring seamless integration.

What is the base URL change?

Change your SDK or HTTP client base URL to https://api.kurisumala.com/v1. This allows you to use the same request structure as the OpenAI speech endpoint, making it easy to switch libraries or integrate into existing projects.

How do I handle long texts?

Split your text into parts of up to 4096 characters. Send each part as a separate request to the API. Then, join the resulting audio files on your end to create a continuous audio track for the full article.

What are the rate limits?

You are limited to 60 requests per minute per API key. Before your first top-up, this limit is lower at 10 requests per minute. Requests are processed sequentially, so high volume may result in queueing delays.

Which audio formats are supported?

The API supports mp3, wav, opus, flac, and pcm formats. Specify your preferred format in the response_format field of your request body. This allows you to choose the best balance between file size and audio quality for your needs.

How do I set the voice speed?

Use the speed parameter in your request body, accepting values between 0.25 and 4.0. This allows you to adjust the speaking rate of the selected voice, enabling faster narration for summaries or slower delivery for detailed explanations.

What happens if a request fails?

If synthesis fails, the charge is returned in full. You are not billed for failed requests, ensuring you only pay for successfully generated audio files. This applies regardless of whether the failure is due to server issues or input errors.

Do I need to install a specific SDK?

No, you do not need a proprietary SDK. You can use the official OpenAI SDK by adjusting the base URL, or simply use plain HTTP requests. This flexibility allows you to integrate with your existing technology stack easily.

Is the API compatible with Node.js?

Yes, the API is fully compatible with Node.js. Since it follows the OpenAI endpoint structure, you can use the standard OpenAI Node.js SDK or any HTTP library like axios to send requests and receive audio files.

How do I rotate my API key?

Generate a new key in your account dashboard. The new key works immediately, and the old one stops working at once. Update your applications to use the new key right away. This ensures secure access control without waiting for expiration periods. You can issue a new key any time your account is active.

What is the character limit per request?

Each request supports up to 4096 characters of input text. For longer articles, you must split the text into chunks of this size, generate audio for each chunk, and then concatenate the resulting audio files on your side.

Does the API support streaming?

No, the API does not support streaming, WebSocket, or real-time partial audio. You receive the complete audio file in the response once synthesis finishes. This synchronous approach simplifies integration, but you must wait for the full file generation before receiving the data.

First request

curl

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

Secure your API access with a Bearer token. Include Authorization: Bearer tts-... in every request header to authenticate your account against the Curisum Audio endpoints.

Our system supports simple key management. You can generate a new key at any time via the dashboard, ensuring you maintain control over your integration security.

Bearer token header

Include your unique key in the Authorization: Bearer tts-... header for every request. This standard format ensures compatibility with the official OpenAI SDKs and standard HTTP libraries.

API key management

Each account holds one active key. You can view and manage your key directly on the /get-api-key/ page alongside your balance and usage statistics.

  • Keys are account-specific to kurisumala.com
  • One active key per account

Key rotation process

Generate a new key whenever needed. The old key stops working immediately, ensuring seamless transition without downtime for your news platform integration.

  • Old key invalid instantly
  • New key active immediately

Speech Endpoint

Sound wave illustration for: Speech Endpoint

The speech endpoint handles text-to-audio conversion. Send a JSON payload to the API, and receive the generated audio file directly in the response. This synchronous HTTP call ensures you get the complete file before moving to the next step, though generation time depends on queue load.

Use this endpoint for standard synthesis tasks. It accepts your API key, the text to convert, and voice preferences. The system processes requests sequentially, so under heavy load, you may experience slight delays before the audio becomes available.

POST request structure

Send a POST request to https://api.kurisumala.com/v1/audio/speech. Include your Bearer token in the Authorization header. The body must be valid JSON containing the required parameters.

  • Endpoint: POST https://api.kurisumala.com/v1/audio/speech
  • Header: Authorization: Bearer tts-...
  • Content-Type: application/json

Required JSON fields

The request body requires specific fields to generate audio correctly. You must specify the model, the input text, and the desired voice. Other fields like format and speed are optional but recommended for control.

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

Response format

The API returns the audio file directly in the response body. The content type matches your requested format. If synthesis fails, you receive an error JSON instead, with no charge applied.

Speech Endpoint

Voices Endpoint

Sound wave illustration for: Voices Endpoint

Send a GET request to /v1/voices to retrieve available presets, supported languages, and format options. This endpoint provides the reference data needed to configure your synthesis requests accurately.

The response includes all eight voice presets and the 23 supported languages. You can use this data to map voice IDs to their descriptive styles, such as Aria’s warm, clear narrator tone or Felix’s energetic promo style.

List available voices ['The endpoint returns eight distinct voice presets. Each voice has a specific character, ranging from Luna’s soft storytelling to Atlas’s neutral news delivery. Use these IDs in your speech requests.', 'Voices are based on licensed recordings and carry an inaudible watermark marking them as synthetic speech. This ensures transparency for your news platform’s audio content.'] ['Female: aria, nova, luna, sage', 'Male: felix, milo, atlas, orion']

Language codes ['Any voice can speak any of the 23 supported languages, including Arabic, Chinese, English, and Swahili. If the language parameter is omitted, the system guesses the language from the script, defaulting to English for Latin text.', 'For non-English Latin-script text, explicitly set the language code to avoid misidentification. Unsupported languages like Vietnamese or Thai are not available.']

Format options ['The endpoint lists five supported audio formats: mp3, wav, opus, flac, and pcm. Choose the format that best fits your delivery pipeline, balancing quality and bandwidth.', 'Generated audio is returned directly in the response and not stored server-side. Request metadata is kept for billing purposes only.']

Models

Sound wave illustration for: Models

Both tts-1 and tts-1-hd models run on the same underlying synthesis engine. They offer identical voice behavior and audio quality profiles, allowing you to switch between them without altering the character of the generated speech.

tts-1 model details

The standard tts-1 model provides efficient, high-quality speech synthesis suitable for most news and content applications. It processes text through the shared engine to produce clear, natural-sounding audio files.

tts-1-hd model details

The tts-1-hd model utilizes the same core engine as tts-1. It is designed for use cases where you prefer the high-definition output profile, though the underlying synthesis logic remains consistent with the standard model.

Price difference

There is no price difference between the two models. Both are billed at $10 per 1 million characters. You can choose either model based on your preference without affecting your API costs.

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts text input up to 4,096 characters per request. Each character, including spaces and punctuation, counts toward your usage and billing. For longer articles, split the text into chunks of this size and join the resulting audio files.

Input text limits

Send your article content in the input field, ensuring it stays within the 4,096-character limit. Anything beyond this must be handled by your application logic, splitting the text and concatenating the outputs.

  • Maximum length: 4,096 characters per request
  • Spaces and punctuation count as characters
  • Split longer texts in your code before sending

Speed range 0.25-4.0

Adjust the playback speed using the speed parameter, which accepts values between 0.25 and 4.0. This allows you to fine-tune the pacing of news readings to suit your audience's preferences.

  • Minimum speed: 0.25
  • Maximum speed: 4.0
  • Adjust via the speed field in the JSON body

Optional language code

You can optionally specify the language parameter using an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script content, always set this field to ensure correct pronunciation.

  • Supported: 23 languages including English, Spanish, German, and Hindi
  • Not supported: Vietnamese, Thai, Ukrainian, and others
  • Set explicitly for non-English Latin text to avoid default English guessing
Request Parameters

Response Formats

Sound wave illustration for: Response Formats

The API returns the complete audio file directly in the response body. You can save this file immediately to your server or send it to your users for playback. The generated audio is not stored on our servers after delivery.

MP3 generation

MP3 is the default response format. It provides a good balance between file size and audio quality, making it ideal for most news articles and web players.

WAV and FLAC options

Choose WAV or FLAC if you need lossless audio quality for archival purposes or high-fidelity broadcasting. WAV is uncompressed and widely supported, while FLAC offers compression without quality loss.

Opus and PCM support

Opus is an efficient codec for modern web streaming, offering low latency and high quality at low bitrates. PCM provides raw, uncompressed audio data for specialized processing pipelines.

Rate Limits

Sound wave illustration for: Rate Limits

Curisum Audio enforces a rate limit of 60 requests per minute for standard accounts. This allows indie news platforms to process articles efficiently without overwhelming the synthesis engine. Each request consumes one unit of this quota, regardless of text length.

The limit applies to your API key. You can monitor your historical usage and character consumption on your dashboard after signing in. Note that the system does not expose real-time remaining request counts, so plan your batching strategy accordingly to avoid 429 errors.

60 requests per minute

Once your account is active, you may send up to 60 speech synthesis requests within any minute. This throughput is sufficient for most content pipelines, including regular news updates. Requests are processed sequentially, so higher volume may increase latency for individual files.

Initial 10 requests limit

New accounts, including those with free trial credits, start with a reduced limit of 10 requests per minute. This baseline applies until you perform your first top-up. After adding USDT to your balance, the limit increases to the standard 60 requests per minute automatically.

Queue behavior under load

Requests are processed one after another. If you send many requests simultaneously, they will wait in a queue. Short phrases may take a few seconds, while longer texts take longer. Under heavy load, you may experience delays as requests wait for their turn in the queue.

Rate Limits

Error Handling

Sound wave illustration for: Error Handling

When synthesis fails, Curisum Audio returns a full refund for the characters consumed, so you are never charged for errors. This applies whether the issue stems from network glitches or invalid input parameters. You can rely on the response body to identify the specific cause.

Common error codes

The API returns standard HTTP status codes to indicate the result of your request. A 401 Unauthorized response means your Bearer token is invalid or missing. A 429 Too Many Requests indicates you have exceeded the 60 requests per minute limit. Check your dashboard for current usage.

  • 401: Invalid or missing API key
  • 429: Rate limit exceeded (60 req/min)
  • 500: Internal server error during synthesis

Invalid voice ID

If you send a voice ID that does not exist, the request fails immediately. Use the GET /v1/voices endpoint to retrieve the exact string identifiers for all eight available presets. Ensure you copy the voice name exactly as listed, as IDs are case-sensitive.

  • Check GET /v1/voices for valid IDs
  • Voice IDs are case-sensitive
  • Example: 'aria', 'nova', 'atlas'

Character limit exceeded

Each request accepts a maximum of 4096 characters in the input field. If your text exceeds this limit, split it into smaller chunks and join the resulting audio files. Characters include spaces and punctuation, so plan your splitting logic accordingly to avoid errors.

  • Max 4096 characters per request
  • Split long texts into chunks
  • Join audio files in your app

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. news outlets often overlook the creative spirit of indie developers in their coverage.

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. Creative Commons Attribution 4.0
  3. LibriTTS-R corpus (OpenSLR 141)
  4. LibriVox public-domain audiobooks
  5. IETF RFC 7845: Ogg Opus
  6. W3C WAI: making audio and video accessible
  7. openai-python on GitHub
  8. ISO 639 language codes
  9. Node.js documentation
  10. MDN: Web Speech API
  11. Tether (USDT)
  12. TRON developer hub: TRC-20

More on this site