Text to Speech

Overview

The Text-to-Speech API turns text into speech in a single synchronous request. Unlike Video Jobs, which are queued and polled, this endpoint calls the TTS engine, stores the result, charges credits, and returns the audio in the same HTTP response.


POST /api/tts/generate/

Every request also creates a job in your history (see the X-Job-Id response header) and is billed per character of text.

Authentication

Send your key in the x-api-key header (browser sessions may use a JWT Authorization: Bearer <token> instead). See API Keys to create one.


x-api-key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate speech


POST /api/tts/generate/

Accepts application/json or multipart/form-data (use multipart to upload a reference clip for voice cloning). The simplest request:


curl -X POST https://api.oshara.ai/api/tts/generate/ \
  -H "x-api-key: $OSHARA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Oshara.","model":"kokoro-en","predefined_voice_id":"af_heart"}' \
  --output hello.wav

Request fields

Field	Type	Required	Description
`text`	string	✓	The text to synthesize.
`model`	string	recommended	Registry name of the voice model (see Models). If omitted, a default cloning model is used and a reference clip becomes required.
`predefined_voice_id`	string	for Kokoro	A named voice from the model’s catalog.
`reference_audio`	file	for cloning	An audio clip to clone (multipart only).
`reference_audio_url`	string	for cloning	A public URL to a clip to clone.
`language`	string	for multilingual models	Language code, e.g. `en`, `ne`.
`speed_factor`	number		Speed multiplier (e.g. `0.5` = slower). Honored by Kokoro and Sherpa.
`temperature`, `exaggeration`, `cfg_weight`, `seed`, `split_text`, `chunk_size`	mixed		Advanced controls; support varies by model.

Whether a voice source is required depends on the model — see Models.

Response

On success: 200 OK with the raw audio as the body.

Header	Value
`Content-Type`	`audio/wav` — 16-bit PCM, mono, 24 kHz
`X-Job-Id`	ID of the stored job
`X-Credits-Charged`	Credits deducted for this request

Write the body straight to a file with curl --output out.wav.

Billing

Requests are billed per character of text, at a per-model rate. The exact cost is checked before generation — if your balance can’t cover it, the request returns 402 and nothing is charged. The amount charged is returned in the X-Credits-Charged header.

Errors

Status	Meaning
`400`	Missing `text`, or a missing/invalid voice source for the chosen model.
`401`	Missing or invalid `x-api-key`.
`402`	Insufficient credits (nothing charged).
`502`	The TTS engine failed to generate audio.


{ "success": false, "message": "An error occurred",
  "errors": { "error": "..." } }

Models

List the models available to you, with providers and voice catalogs:


curl https://api.oshara.ai/api/ai-characters/tts-models/ \
  -H "x-api-key: $OSHARA_KEY"

Model	Provider	Language	Voice source	Cloning
`kokoro-en`	kokoro	English	`predefined_voice_id` (required)	—
`sherpa-onnx-en-ryan`	sherpa-onnx	English	none (fixed voice)	—
`sherpa-onnx-ne-sp6`	sherpa-onnx	Nepali	none (fixed voice)	—
`sherpa-onnx-ne-spk16`	sherpa-onnx	Nepali	none (fixed voice)	—
`chatterbox-finetuned-v1`	chatterbox	Multilingual	reference clip (optional)	✓
`xtts-ne-v2`	xtts	Multilingual	reference clip (optional)	✓

All examples below assume:


export OSHARA_KEY="sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Kokoro — preset English voices

Natural English voices selected by predefined_voice_id (required). No language needed — the voice ID encodes the accent.


curl -X POST https://api.oshara.ai/api/tts/generate/ \
  -H "x-api-key: $OSHARA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Hello from Oshara.","model":"kokoro-en","predefined_voice_id":"af_heart"}' \
  --output kokoro.wav

Voice catalog (predefined_voice_id):

American female: af_heart (default), af_bella, af_nicole, af_aoede, af_kore, af_sarah, af_sky
American male: am_adam, am_echo, am_eric, am_fenrir, am_liam, am_michael, am_onyx, am_orion, am_santa
British: bf_emma, bf_isabella (female); bm_george, bm_lewis (male)

Sherpa — fast fixed voices

Lowest latency, ideal for conversational use. Each model has one built-in voice, so just send text and model — no voice source required.


# English
curl -X POST https://api.oshara.ai/api/tts/generate/ \
  -H "x-api-key: $OSHARA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"This is a quick test.","model":"sherpa-onnx-en-ryan"}' \
  --output sherpa_en.wav
 
# Nepali (use sherpa-onnx-ne-spk16 for the alternate speaker)
curl -X POST https://api.oshara.ai/api/tts/generate/ \
  -H "x-api-key: $OSHARA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"नमस्ते, यो एक परीक्षण हो।","model":"sherpa-onnx-ne-sp6"}' \
  --output sherpa_ne.wav

Chatterbox & XTTS — multilingual + cloning

Multilingual models that can clone a supplied voice. Always pass language (e.g. en, ne) — they have no single fixed language. Without a reference clip they use a built-in default voice.


curl -X POST https://api.oshara.ai/api/tts/generate/ \
  -H "x-api-key: $OSHARA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"नमस्ते, यो एक परीक्षण हो।","model":"xtts-ne-v2","language":"ne"}' \
  --output xtts.wav

For multilingual models, omitting language falls back to English — set it explicitly ("ne" for Nepali) so the text is pronounced correctly.

Voice cloning

For chatterbox-finetuned-v1 and xtts-ne-v2, supply the voice to clone either by uploading a clip or referencing a public URL.


# Upload a clip (multipart)
curl -X POST https://api.oshara.ai/api/tts/generate/ \
  -H "x-api-key: $OSHARA_KEY" \
  -F "text=Hello, this is my cloned voice." \
  -F "model=xtts-ne-v2" -F "language=ne" \
  -F "reference_audio=@my_voice.wav" \
  --output cloned.wav
 
# …or reference a URL (JSON)
curl -X POST https://api.oshara.ai/api/tts/generate/ \
  -H "x-api-key: $OSHARA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"...","model":"chatterbox-finetuned-v1","language":"en","reference_audio_url":"https://example.com/voice.wav"}' \
  --output cloned.wav

Use a clean, single-speaker sample of at least a few seconds. Reference clips are automatically trimmed to the engine’s maximum (~40 seconds).