README.md

metadata

title: Kasanoma Api
emoji: 🔥
colorFrom: gray
colorTo: green
sdk: docker
pinned: false

🔥 Kasanoma TTS API

A ready‑to‑use text‑to‑speech API powered by a custom Twi voice (Kofi).
Send text → get a .wav file back, hosted on Hugging Face.

Base URL: https://michsethowusu-kasanoma-api.hf.space

---

📡 Endpoints

Method	Path	Description
POST	/api/v1/synthesize	Synthesize speech from text
GET	/api/v1/synthesize/{filename}	Download a generated audio file
GET	/api/healthcheck	Public health check

---

✨ Synthesize speech

Send a POST request with a JSON body. The response includes the audio encoded as base64 – no second request is necessary.

Request Body

{
  "text": "Mema wo akwaaba!",
  "local": "twi_GH",
  "voice": "kofi-medium",
  "silence": 1,
  "speed": 1.0,
  "noise_w": 0.8,
  "effects": [],
  "lite_file": true
}

Field	Type	Required	Default	Description
text	string	yes	–	The text to speak
local	string	no	twi_GH	Language code (must match the .onnx filename)
voice	string	no	kofi-medium	Voice name (file = {local}-{voice}.onnx)
silence	number	no	1	Seconds of silence between sentences
speed	number	no	1.0	Speed factor
noise_w	number	no	0.8	Noise weight
effects	array	no	[]	Audio effects to apply (see below)
lite_file	boolean	no	true	Convert output to 16‑bit mono WAV (recommended)

Response (200 OK)

{
  "filename": "abc123.wav",
  "url": "/api/v1/synthesize/abc123.wav",
  "audio_base64": "UklGRi... (base64-encoded WAV)"
}

The audio_base64 field contains the raw audio data.
Simply decode it to get the WAV file – no additional download required.

---

🎚️ Audio Effects (optional)

You can chain multiple effects. Each effect object has name and params.

Effect	Parameters (defaults)
flanger	rate (0.15), min_delay (0.0025), max_delay (0.0035), feedback (0.9), t_offset (0), dry (0.5), wet (0.5)
pitch_shift	pitch_change (-100 to +100, default 0)
random_semitone_sawtooth_wave	min_freq (170), max_semitones (6), pitch_duration (0.4), wet (0.3)
normalize	(none)
speed_change	speed (positive = faster, negative = slower, e.g. 0.25 = 25% faster)

Example with a pitch shift and normalization:

{
  "text": "Ɛte sɛn?",
  "effects": [
    {"name": "pitch_shift", "params": {"pitch_change": 8}},
    {"name": "normalize", "params": {}}
  ]
}

---

🔐 Authentication

This Space is protected by HTTP Basic Auth.
You must include the following credentials in every request:

• Username: piper
• Password: kasanoma (this is the current API key)

Example with curl:

curl -u piper:kasanoma \
  -X POST "https://michsethowusu-kasanoma-api.hf.space/api/v1/synthesize" \
  -H "Content-Type: application/json" \
  -d '{"text": "Mema wo akwaaba", "local": "twi_GH", "voice": "kofi-medium"}'

If the API key changes in the future, update the password accordingly.

---

🧪 Usage Examples

curl (with auth)

curl -u piper:kasanoma \
  -X POST "https://michsethowusu-kasanoma-api.hf.space/api/v1/synthesize" \
  -H "Content-Type: application/json" \
  -d '{"text": "Me din de Kofi", "lite_file": true}'

The response contains audio_base64. Decode it to get the WAV file:

# Extract audio_base64 from JSON (using jq) and decode
curl -u piper:kasanoma ... | jq -r '.audio_base64' | base64 -d > output.wav

Python (using base64, with auth)

import requests
import base64

BASE = "https://michsethowusu-kasanoma-api.hf.space"
auth = ("piper", "kasanoma")

payload = {
    "text": "Mema wo akwaaba!",
    "local": "twi_GH",
    "voice": "kofi-medium",
    "lite_file": True
}

resp = requests.post(f"{BASE}/api/v1/synthesize", json=payload, auth=auth)
data = resp.json()

# Decode the base64 audio and save
audio_bytes = base64.b64decode(data["audio_base64"])
with open("output.wav", "wb") as f:
    f.write(audio_bytes)
print("Saved to output.wav")

📄 Ready‑made example script

The repository includes a fully working script: test.py.
It generates five long Twi sentences and saves them as output_twi_1.wav … output_twi_5.wav.
Just run:

python3 test.py

---

🗣️ Available Voices

Voice	File	local	voice
Kofi (Twi)	twi_GH-kofi-medium.onnx	twi_GH	kofi-medium

(More voices can be added by placing additional .onnx + .json files in the Space’s repository.)

---

🩺 Health Check

curl https://michsethowusu-kasanoma-api.hf.space/api/healthcheck
# → {"status":"ok"}

---

🛠️ Notes for developers

• All API routes (except /api/healthcheck) require HTTP Basic Auth.
• Audio is returned directly as base64 inside the JSON response – there is no need to perform a second download request.
• The test.py script in this repo is a complete example that uses the current API key and demonstrates the entire flow.