Cloud TTS API: Quickstart Guide for Developers

By Kiriya Editorial Team · Updated 2026-11-19

This guide provides a practical reference for developers integrating Kiriya’s cloud text-to-speech API into digital agency projects. It covers authentication, endpoint structures, and parameter configurations needed to generate high-quality audio files programmatically.

Designed for technical teams building voice-enabled features for online stores, the documentation details request limits, supported languages, and code examples in cURL and Python. You will find specific instructions on handling rate limits, rotating API keys, and managing audio formats like MP3 and WAV.

Cloud TTS API: Quickstart Guide for Developers

Frequently asked questions

What is the API endpoint URL?

Send your POST request to https://api.kiriya.info/v1/audio/speech. This endpoint accepts JSON bodies containing your text and configuration parameters. It follows the standard shape of the OpenAI speech endpoint, ensuring compatibility with existing client libraries and workflows used by digital agencies integrating voice features.

How do I authenticate with the API?

Include your API key in the request header as Authorization: Bearer tts-.... Each account holds one active key at a time. You can issue a new key via the dashboard, which immediately invalidates the previous one, ensuring secure access control for your agency’s integrations.

What models are available?

Two models are available: "tts-1" and "tts-1-hd". Both use the same engine and pricing structure. You can list available models and details via the GET /v1/models endpoint. These models handle the synthesis process, delivering audio files based on your specified input text and voice parameters.

How do I set the voice?

Select one of eight preset voices from the voice field. Options include female voices like aria, nova, luna, and sage, or male voices like felix, milo, atlas, and orion. Retrieve the full list of available voices and their details using the GET /v1/voices endpoint.

Can I adjust the speed of the speech?

Yes, you can adjust the speech speed using the speed parameter. Acceptable values range from 0.25 to 4.0. This allows you to tailor the pacing of the generated audio to suit different content types, from slow instructional guides to fast-paced promotional announcements for online stores.

What formats are supported?

The API supports five audio formats: mp3, wav, opus, flac, and pcm. You specify the desired format using the response_format field in your request. This flexibility allows your agency to choose the optimal format based on the client’s frontend requirements and bandwidth constraints.

How do I handle errors?

If synthesis fails, the charge is returned in full, so you are not billed for unsuccessful requests. You should implement error handling in your integration to catch API responses and retry or alert the user as needed. Failed requests do not incur costs, protecting your budget.

Is there a rate limit?

The rate limit is 60 requests per minute per key. Before the first top-up, this limit is reduced to 10 requests per minute. If you exceed these limits, requests may be queued or rejected. Monitor your usage via the dashboard to ensure smooth integration for your clients.

Can I use the OpenAI SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.kiriya.info/v1. Use your Kiriya API key for authentication. This allows you to leverage familiar SDK methods while accessing our specific voices, formats, and pricing structure without rewriting your entire integration logic.

How do I specify the language?

Use the optional language field with an ISO code. If 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 to ensure accurate synthesis across the 23 supported languages.

What is the character limit per request?

Each request can contain up to 4096 characters of text in the input field. Spaces and punctuation count toward this limit. If your content exceeds this length, you must split the text into chunks, generate audio for each, and join the resulting files.

How long does generation take?

Generation takes roughly real time, averaging 25 characters of text per second of audio. Short phrases may take a few seconds. Requests are processed sequentially, so under load, a request may wait in a queue. Plan your integration’s latency expectations accordingly for a smooth user experience.

Do I need to split long texts?

Yes, if your text exceeds 4096 characters, you must split it into parts. Generate audio for each part separately and then join the audio files. This ensures that each request stays within the character limit and allows for precise control over the final audio output.

How do I get my API key?

Sign up on the /get-api-key/ page using Google or an email and password. The page displays your API key, balance, and usage details. Keys are issued per site account. You can also issue a new key at any time, which immediately invalidates the old one.

First request

curl

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

Authentication

Sound wave illustration for: Authentication

Authentication relies on a single active API key issued to your account. This key identifies your account and tracks usage against your balance. You can generate a new key at any time via the dashboard, which instantly invalidates the previous one, ensuring secure access control without downtime for active integrations.

The API expects standard HTTP authentication headers for every request. This ensures compatibility with existing tooling and allows you to manage credentials securely in environment variables or secret managers within your agency’s deployment pipeline.

API Key format

API Key format

Your API key begins with the prefix tts- followed by a unique alphanumeric string. It is a single active key per account, providing a simple and predictable authentication method for all API interactions.

  • Keys start with 'tts-'
  • One active key per account

Bearer token usage

Bearer token usage

Include your key in the Authorization header using the Bearer scheme. For example, use Authorization: Bearer tts-.... This standard format works with the official OpenAI SDKs by simply adjusting the base URL to https://api.kiriya.info/v1.

  • Use 'Authorization: Bearer tts-...'
  • Compatible with OpenAI SDKs

Key rotation

You can issue a new key at any time through the dashboard. The old key stops working immediately upon generation.

  • Instant invalidation of old keys
  • Generate new keys anytime

Endpoint Overview

Sound wave illustration for: Endpoint Overview

Kiriya Editorial’s Cloud TTS API provides three primary endpoints for integration. The core speech generation endpoint processes text input and returns audio files, while the voices and models endpoints allow you to discover available options programmatically.

Speech generation endpoint

Use POST https://api.kiriya.info/v1/audio/speech to generate audio. Send a JSON body with model, input, voice, response_format, and optional speed or language. The endpoint returns the audio file directly in the response.

Voices listing endpoint

The GET /v1/voices endpoint returns a list of all available voice presets, their associated languages, supported audio formats, and pricing details. This allows your application to dynamically present voice options to end-users.

Models endpoint

The GET /v1/models endpoint lists the available TTS models, specifically tts-1 and tts-1-hd. Both models use the same engine and pricing structure, offering flexibility based on your quality or cost preferences.

Request Parameters

Sound wave illustration for: Request Parameters

Configure the core parameters to generate speech that matches your digital store’s tone and technical requirements. The API accepts standard JSON bodies, allowing seamless integration with existing e-commerce workflows via the OpenAI SDK or plain HTTP requests.

Model selection

Choose between "tts-1" or "tts-1-hd"; both use the same engine and price. Both models use the same engine and pricing structure, ensuring consistent billing regardless of quality preference.

Input text limit

Each request supports up to 4,096 characters. For longer product descriptions or blog posts, split the text into chunks, generate each part, and join the resulting audio files. Spaces and punctuation count toward the limit.

Voice selection

Select from eight preset voices, including warm narrators like Aria or energetic promos like Felix. Every voice supports all 23 available languages, allowing you to maintain a consistent brand voice across multilingual storefronts without hiring new talent.

Response Formats

Sound wave illustration for: Response Formats

The API returns synthesized audio as a binary file directly in the HTTP response body. You can choose between lossy compression for efficient bandwidth usage or lossless formats for archival quality, depending on your client’s playback requirements.

Each format serves a specific use case in e-commerce workflows, from quick mobile previews to high-fidelity product descriptions.

MP3 output

MP3 is the default response format. It offers a good balance between file size and audio quality, making it ideal for web players and mobile applications where bandwidth conservation is important.

Use this format when delivering audio to standard web browsers or when storing generated clips for later playback in your store’s frontend.

  • Default format for most integrations
  • Suitable for web and mobile playback
  • Efficient storage and transfer

WAV output

WAV provides uncompressed, high-quality audio data. This format is preferred for professional editing workflows or when you need lossless fidelity for voiceovers in promotional videos.

Select WAV when your clients require the highest possible audio quality for broadcast or detailed editorial review.

  • Lossless uncompressed audio
  • Ideal for professional editing
  • Higher bandwidth usage

Opus and FLAC

Opus is a supported response format. FLAC provides lossless compression, reducing file size without sacrificing any audio data.

FLAC is a supported response format.

  • Opus: efficient low-bitrate streaming
  • FLAC: lossless compression
  • Archival quality with smaller size

Speed Control

Sound wave illustration for: Speed Control

The API accepts a speed parameter ranging from 0.25 to 4.0, allowing precise control over voice pacing. This feature enables developers to optimize audio for specific use cases, such as slowing down narration for accessibility or accelerating promo content for quick engagement.

Adjustable speed range

Speed values outside the 0.25–4.0 range will result in an error. Adjusting speed does not alter the voice characteristics, only the rate of speech.

Real-time generation

Typical processing speed is roughly real-time, generating approximately 25 characters of text per second for long texts. Short phrases may take a few seconds to complete due to initialization overhead.

Queue handling

Requests are processed sequentially. Under high load, your request may wait in a queue before synthesis begins. This ensures consistent audio quality but may increase latency during peak usage.

Speed Control

Language Support

Sound wave illustration for: Language Support

Language detection is automatic for Latin-script text, defaulting to English. For other Latin-script languages or non-Latin scripts, explicitly setting the language parameter via ISO code ensures accurate synthesis.

ISO code usage

Pass a standard ISO 639-1 code (e.g., es, fr, de) to lock the language. This overrides auto-detection and ensures consistent output for mixed-script inputs.

  • Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
  • Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali.

Auto-detection

The API guesses the language from the script. Latin text defaults to English if no language is specified. Non-English Latin text requires explicit setting to avoid mispronunciation.

Specific language setting

Use the language field to force a specific voice output regardless of input script. All 8 voices support all 23 languages, allowing flexible voice selection per language requirement.

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate the outcome of each request. Understanding these codes helps your application handle failures gracefully without manual intervention.

When a request fails, the response body includes a JSON object with an error type and a human-readable message. This structure allows for easy parsing in any programming language.

Common error codes

Use standard HTTP codes to determine success or failure. A 200 OK status confirms the audio file is ready in the response body. Non-2xx codes indicate specific issues that require attention from your integration layer.

For instance, a 400 Bad Request signals invalid parameters, while a 500 Internal Server Error suggests a temporary issue on our end. Always check the response body for detailed error descriptions.

  • 200: Success, audio file included in response.
  • 400: Bad Request, check parameters and input format.
  • 401: Unauthorized, verify your Bearer token.
  • 500: Internal Server Error, try again later.

Rate limit errors

You are limited to 60 requests per minute per key. If you exceed this, the API returns a 429 Too Many Requests status. This limit applies to all requests.

Before your first top-up, the limit is stricter at 10 requests per minute. Monitor your response headers for X-RateLimit-Remaining and X-RateLimit-Reset to manage your queue effectively.

  • 429: Rate limit exceeded, wait before retrying.
  • Check headers for remaining requests and reset time.
  • Limit is 60 req/min after top-up, 10 req/min before.

Invalid input errors

Ensure your input text does not exceed 4096 characters. If it does, split the text into smaller chunks before sending. Also, verify that the voice parameter matches one of the eight available presets.

Invalid formats or unsupported language codes will also trigger an error. Always validate your input against the /v1/voices endpoint to ensure compatibility before generating audio.

  • 400: Input text exceeds 4096 characters.
  • 400: Invalid voice ID or unsupported format.
  • 400: Invalid ISO language code.

Code Examples

Sound wave illustration for: Code Examples

These examples demonstrate how to integrate Kiriya’s TTS API into your client’s e-commerce workflow. You can use standard HTTP libraries or the OpenAI SDK by pointing it to our base URL.

Curl example

Send a POST request to https://api.kiriya.info/v1/audio/speech with your Bearer token. The body includes the model, voice, and text input.

  • Replace YOUR_API_KEY with your actual key.
  • Ensure text is under 4096 characters.

OpenAI SDK example

Initialize the OpenAI client with base_url=https://api.kiriya.info/v1. Use client.audio.speech.create() to generate audio files directly.

Python example

Use the requests library to handle the POST response. Save the binary audio data to a file for playback in your store’s interface.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The following examples illustrate how to implement each approach using standard tools available to modern web developers.

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

More on this site