Speech to Text

The Speech to Text (STT) service transcribes audio files into text. The unified POST /tasks/audio/transcriptions endpoint is powered by Sunbird’s faster-whisper ASR model (Sunbird/faster-whisper-51-african-languages, a Whisper large-v3 fine-tune) covering 51 African languages.

Breaking change (v2.1). This endpoint previously accepted platform, adapter, whisper, recognise_speakers, org, and gcs_blob_name. Those parameters have been removed and are now rejected with 422. Send only audio, language, and (optionally) timestamps.

Audio Requirements

Formats: MP3, WAV, M4A, OGG, and more.
Duration Limit: For files larger than 100MB, only the first 10 minutes are transcribed.
File Size: Direct uploads are supported. Use the signed-URL workflow to stage large files in Google Cloud Storage.

Transcribing a File

audio and language are both required. The model reuses Whisper’s language-token slots for African languages, which makes automatic language detection unreliable — always pass a language explicitly.

Parameters

Parameter	Type	Required	Description
`audio`	file	Yes	The audio file to transcribe (multipart/form-data).
`language`	string	Yes	ISO 639-3 code — one of the 51 supported languages.
`timestamps`	boolean	No	Return per-segment start/end times in `segments`. Defaults to `false`.

import os
import requests
from dotenv import load_dotenv

load_dotenv()

url = "https://api.sunbird.ai/tasks/audio/transcriptions"
access_token = os.getenv("AUTH_TOKEN")

headers = {
    "accept": "application/json",
    "Authorization": f"Bearer {access_token}",
}

files = {
    "audio": ("recording.wav", open("/path/to/audio_file.wav", "rb"), "audio/wav"),
}
data = {
    "language": "lug",   # required: ISO 639-3 code
}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()
print(f"Transcription: {result['audio_transcription']}")

const formData = new FormData();
formData.append('audio', fileInput.files[0]);
formData.append('language', 'lug');

const response = await fetch('https://api.sunbird.ai/tasks/audio/transcriptions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_TOKEN>'
  },
  body: formData
});
console.log(await response.json());

curl -X POST "https://api.sunbird.ai/tasks/audio/transcriptions" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "audio=@/path/to/audio_file.wav" \
     -F "language=lug"

Response

{
  "audio_transcription": "Ekibiina ekiddukanya ...",
  "language": "lug",
  "audio_url": "gs://.../audio.wav",
  "audio_transcription_id": 123,
  "duration_seconds": 12.4,
  "segments": null,
  "usage": { "type": "duration", "seconds": 12.4 },
  "diarization_output": {},
  "formatted_diarization_output": "",
  "was_audio_trimmed": false,
  "original_duration_minutes": null
}

Timestamped Segments

Set timestamps=true to also receive per-segment start/end times in segments. It is false by default, in which case segments comes back as null.

data = {
    "language": "ach",
    "timestamps": True,
}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()

print(result["audio_transcription"])
for segment in result["segments"]:
    print(f"[{segment['start']:7.2f} -> {segment['end']:7.2f}] {segment['text']}")

{
  "audio_transcription": "Gyebaleko ssebo",
  "language": "ach",
  "duration_seconds": 2.25,
  "segments": [
    {"start": 0.0, "end": 1.0, "text": "Gyebaleko"},
    {"start": 1.0, "end": 2.25, "text": "ssebo"}
  ]
}

Supported Languages (51)

Pass the ISO 639-3 code as language. All ten languages served by the previous version of this endpoint are still supported.

Code	Language	Code	Language	Code	Language
`ach`	Acholi	`kab`	Kabyle	`nyn`	Runyankole
`afr`	Afrikaans	`kau`	Kanuri	`orm`	Oromo
`aka`	Akan	`kik`	Kikuyu	`pcm`	Nigerian Pidgin
`amh`	Amharic	`kin`	Kinyarwanda	`ruc`	Ruruuli
`bam`	Bambara	`kln`	Kalenjin	`rwm`	Kwamba
`bem`	Bemba	`koo`	Rukonjo	`sna`	Shona
`ber`	Berber	`kpo`	Ikposo	`som`	Somali
`cgg`	Rukiga	`led`	Lendu	`sot`	Sotho
`dag`	Dagbani	`lgg`	Lugbara	`swa`	Swahili
`dga`	Dagaare	`lin`	Lingala	`teo`	Ateso
`eng`	English	`lth`	Thur	`tsn`	Tswana
`ewe`	Ewe	`lug`	Luganda	`ttj`	Rutooro
`fra`	French	`luo`	Luo	`wol`	Wolof
`ful`	Fulani	`luy`	Luhya	`xho`	Xhosa
`hau`	Hausa	`mlg`	Malagasy	`xog`	Lusoga
`ibo`	Igbo	`myx`	Lumasaba	`yor`	Yoruba
		`nbl`	Ndebele	`zul`	Zulu
		`nya`	Chichewa

Per-language accuracy scales with the amount of training data available for each language. See the model card for per-language WER/CER figures.

File Uploads (Signed URLs)

Generate secure signed URLs for direct client uploads to Google Cloud Storage. URLs are valid for 30 minutes and include path-traversal protection.

import os
import requests
from dotenv import load_dotenv

load_dotenv()

# Step 1: Generate an upload URL
url = "https://api.sunbird.ai/tasks/generate-upload-url"
access_token = os.getenv("AUTH_TOKEN")

headers = {
    "accept": "application/json",
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

data = {"file_name": "recording.wav", "content_type": "audio/wav"}

response = requests.post(url, headers=headers, json=data)
result = response.json()

upload_url = result["upload_url"]
file_id = result["file_id"]
print(f"Upload URL: {upload_url}")
print(f"File ID: {file_id}")
print(f"Expires at: {result['expires_at']}")

# Step 2: Upload the file directly to GCS
with open("/path/to/your/recording.wav", "rb") as f:
    upload_response = requests.put(
        upload_url, data=f, headers={"Content-Type": "audio/wav"}
    )

if upload_response.status_code == 200:
    print("File uploaded successfully!")

Getting Started

Guides

Support

Audio Requirements

Transcribing a File

Parameters

Response

Timestamped Segments

Supported Languages (51)

File Uploads (Signed URLs)

​Audio Requirements

​Transcribing a File

​Parameters

​Response

​Timestamped Segments

​Supported Languages (51)

​File Uploads (Signed URLs)

Audio Requirements

Transcribing a File

Parameters

Response

Timestamped Segments

Supported Languages (51)

File Uploads (Signed URLs)