Text to Speech API

The Text to Speech API accepts text and a voice_id, then returns MP3 or WAV audio. The Base URL is https://api.kitschlabs.com, and public requests are authenticated with the xi-api-key header.

API overview

Item	Value
Base URL	https://api.kitschlabs.com
Authentication	xi-api-key: <API_KEY>
Default output	mp3_44100_128 (audio/mpeg)
Additional output	wav_24000 (audio/wav)

The language_code schema accepts en, ko, ja, and zh. Available languages and voices can vary by account, so select from the GET /v1/voices response.

Which endpoint should I use?

Method	Endpoint	Purpose
GET	/v1/voices	List available voices
POST	/v1/text-to-speech/{voice_id}	Generate a complete audio file

How do I authenticate?

Send xi-api-key to every public endpoint. Replace <API_KEY> with your issued key, and do not write the real key to source code or logs.

xi-api-key: <API_KEY>

How do I list voices?

curl "https://api.kitschlabs.com/v1/voices" \
  --header "xi-api-key: <API_KEY>"

Use the voice_id from the /v1/voices response for speech synthesis. Store the voice_id instead of a display name so a name change does not break your integration.

How do I generate speech?

Send JSON to POST /v1/text-to-speech/{voice_id} and save the response body to a file.

cURL

curl --request POST \
  "https://api.kitschlabs.com/v1/text-to-speech/<VOICE_ID>?output_format=mp3_44100_128" \
  --header "xi-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "text": "Have a great day today.",
    "language_code": "en"
  }' \
  --output speech.mp3

Python

import os

import requests

response = requests.post(
    "https://api.kitschlabs.com/v1/text-to-speech/<VOICE_ID>",
    params={"output_format": "mp3_44100_128"},
    headers={
        "xi-api-key": os.environ["KITSCH_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "text": "Have a great day today.",
        "language_code": "en",
    },
    timeout=120,
)
response.raise_for_status()

with open("speech.mp3", "wb") as audio_file:
    audio_file.write(response.content)

JavaScript

import { writeFile } from "node:fs/promises";

const response = await fetch(
  "https://api.kitschlabs.com/v1/text-to-speech/<VOICE_ID>?output_format=mp3_44100_128",
  {
    method: "POST",
    headers: {
      "xi-api-key": process.env.KITSCH_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Have a great day today.",
      language_code: "en",
    }),
  },
);

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));

Which fields do I send?

Field	Type	Required	Description
text	string	Yes	Text to synthesize. An empty string is not allowed
language_code	string	No	One of en, ko, ja, or zh
instruct	string	No	Natural-language instructions for the speaking style
speed	number	No	Speaking speed from 0.25 to 4
voice_settings.emotion_code	string	No	Select an available emotion

Which text tags are supported?

You can include [laughter], [sigh], [en], [wa], and [hnn] tags in text. Other square-bracket tags are rejected as request errors.

{
  "text": "Really? [laughter] I did not expect that either."
}

How should I handle errors?

Error responses generally include detail.status, detail.message, and detail.request_id.

{
  "detail": {
    "status": "rate_limited",
    "message": "Rate limit exceeded. Please retry later.",
    "request_id": "<REQUEST_ID>"
  }
}

Status	Meaning	Recommended action
400·422	Invalid request value	Correct the body, tag, or range
401	API key is missing or invalid	Check the key and xi-api-key header
402	Not enough available credits	Check the Billing status
404	Voice was not found or is not accessible	Check the voice_id and account access
429	Account request limit exceeded	Follow Retry-After and apply backoff
5xx	Temporary server error	Record the request ID and retry a limited number of times

Log the x-kitsch-request-id header from successful and error responses for support requests and incident tracking.