README.md

---
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

```json
{
  "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)

```json
{
  "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:
```json
{
  "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:**
```bash
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)

```bash
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:
```bash
# 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)

```python
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`](test.py)**.  
It generates **five long Twi sentences** and saves them as `output_twi_1.wav` … `output_twi_5.wav`.  
Just run:

```bash
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

```bash
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.
```