TTS API Reference

The Shisa TTS HTTP API exposes two endpoints: one to generate speech and one to list available voices. Both authenticate with a standard bearer token. To receive streamed audio over a WebSocket, see WebSocket Streaming.

Authorization: Bearer YOUR_API_KEY

Endpoints

Generate speech

POST https://api.shisa.ai/tts

Converts text to speech audio. Returns binary audio data in the requested format.

List voices

GET https://api.shisa.ai/tts/voices

Returns an object with a voices array containing all currently active voices, their metadata, supported formats, sample rates, and streaming capability. See Voices for the catalogue.

Request parameters

Parameters for the POST /tts endpoint, sent as a JSON body:

Parameter	Type	Required	Description
voice_id	string	Required	UUID of the voice to use. Get available IDs from GET /tts/voices.
text	string	Required	The text to convert to speech. Default maximum: 5,000 Unicode characters.
format	string	Required	Output audio format. Must be supported by the selected voice. One of mp3, wav, ogg, pcm, flac.
stream	boolean	Optional	When true, returns audio as a chunked stream for real-time playback. The voice must have streaming: true, and the selected format must support streaming on that provider. Default false.
sample_rate	integer	Optional	Omit or use 0 for the 24,000 Hz default. Set a non-zero override only for voices with multiple advertised sample rates. Qwen-backed voices do not accept an override with ogg.
temperature	number	Optional	Provider-specific variation control, currently meaningful for Qwen-backed voices (Qwen default: 0.5). Omit for other voices.

Response

POST /tts — binary audio

On success, the API returns raw binary audio data with the appropriate Content-Type header (for example audio/mpeg for MP3). Save the response body directly to a file:

# The response is binary audio data — save directly to file
curl -s -X POST "https://api.shisa.ai/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id": "61ba1141-60aa-4bc3-a3b3-be1ec20700b3", "format": "mp3", "text": "テスト"}' \
  --output speech.mp3

GET /tts/voices — JSON

Returns an object containing an array of available voice objects:

{
  "voices": [
    {
      "id": "e3362c0a-7677-4cd8-b122-91fb093305c9",
      "description": "Young male Japanese voice...",
      "language": "Japanese & English",
      "gender": "Male",
      "formats": ["mp3", "ogg", "pcm"],
      "sample_rates": [8000, 16000, 22050, 24000, 32000, 44100, 48000],
      "streaming": true
    }
  ]
}

Voice object fields:

Field	Type	Description
id	string (uuid)	UUID to use as voice_id in requests.
description	string	Human-readable voice description.
language	string	Supported language(s).
gender	string	Voice gender (Male, Female, Neutral).
formats	array	Supported output audio formats.
sample_rates	array	Supported output sample rates in Hz.
streaming	boolean	Whether the voice's provider supports real-time streaming in at least one format. It does not mean every value in formats can stream.

Error handling

Errors are returned as JSON in the following format:

{
  "context": ["..."],
  "code": 104,
  "name": "ErrAuthenticationFailed",
  "error": "Authentication error: Invalid token"
}

Error codes

Status	Cause	Resolution
400	Missing or invalid parameters	Check voice_id, text, and format fields.
400	Unsupported format for voice	Use a format listed in the voice's formats array.
400	Provider/format combination cannot stream	Set stream to false, or choose a streaming-capable format.
400	Unsupported sample rate	Omit sample_rate, or choose a configurable rate supported by the voice.
400	Text exceeds the configured maximum	Shorten the text; the default maximum is 5,000 characters.
401	Invalid or missing API key	Check your Authorization: Bearer header.
403	Service access denied	The key cannot use the provider behind the selected voice.
404	TTS service/provider is not registered	Verify service availability or contact support.
429	Rate limit exceeded	Wait and retry with exponential backoff.
500	Internal server error	Retry the request or contact support.

warning

A 400 is also returned when the requested format is not in the selected voice's formats array. In addition, streaming: true does not guarantee that every supported format can stream; stream: true returns 400 for an unsupported provider/format pair.

Next steps

• Walk through your first request in the Quickstart.
• Browse available voices in the Voices catalogue.
• See how usage is billed in Pricing.