README.md

metadata

title: NCAIR ASR API
emoji: 🎙️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false

NCAIR Nigerian ASR — API backend

An OpenAI-compatible speech-to-text service for the voice assistant. It loads the right NCAIR Whisper model based on the request's language field, so one endpoint covers Yorùbá, Igbo, Hausa, and Nigerian-accented English.

POST /v1/audio/transcriptions   multipart: file [, model] [, language]  ->  {"text": "..."}
GET  /health

language value	Model
yo / yoruba	NCAIR1/Yoruba-ASR
ig / igbo	NCAIR1/Igbo-ASR
ha / hausa	NCAIR1/Hausa-ASR
en / english / nigerian english	NCAIR1/NigerianAccentedEnglish

Models load lazily on first use and are cached, so startup is fast and only the languages you use get loaded. CPU is enough (Whisper Small).

---

Before you deploy

These models are gated and license-restricted:

1. Accept the terms for each model you'll use on Hugging Face (Yoruba-ASR, Igbo-ASR, Hausa-ASR, NigerianAccentedEnglish) with the account whose token you'll use.
2. Add an HF_TOKEN Secret so the gated weights can download.
3. License: research/innovation license — not for commercial or large-scale use (>1000 active users) without a separate Awarri agreement. Attribution: "developed by Awarri Technologies in partnership with the Federal Government of Nigeria." (Not legal advice.)

---

Deploy

1. Create a Docker → Blank Space, push app.py, requirements.txt, Dockerfile, README.md.
2. Add the HF_TOKEN Secret.
3. Wait for the build; the first call per language downloads that model.

Wire it into voice-ai-demo

On the voice-ai-demo Space, set per language (Yoruba shown):

Secret	Value
ASR_YORUBA_BASE_URL	https://<this-space>.hf.space/v1

The demo sends language=yo, so this service returns Yoruba. For Igbo/Hausa/English, add those languages to the demo's config.json and set ASR_<LANG>_BASE_URL to the same URL — the service routes by the language hint.

Local test

curl -X POST http://localhost:7860/v1/audio/transcriptions \
  -F "file=@sample.wav" -F "language=yo"

Project Structure

ncair-asr-api/
├── app.py              # FastAPI OpenAI-compatible ASR (multi-language)
├── requirements.txt    # transformers 5.x + serving deps
├── Dockerfile          # CPU image with ffmpeg
└── README.md           # this file