Bonga — Kiswahili Voice

Bonga is Ngamia's Kiswahili voice experience. A person speaks naturally, reviews the transcript, and hears Ngamia answer. The API orchestrates a synchronous loop: transcribe the voice note, generate a text reply, then optionally synthesize speech. Use the versioned endpoint POST /v1/bonga; POST /bonga and POST /v1/voice/responses remain compatible aliases. A polished consumer feature still needs the app interface, curated voices, latency/quality testing, and resilient mobile-network behavior; the endpoint alone is not a finished voice-agent product.

Use the direct routes when you want control over each stage; use the combined route when your product needs one request and one JSON result. Streaming and timestamp variants are separate public routes. Voice management, cloning, dictionaries, dubbing, and other audio processing are grouped in Audio Tools.

The Bonga aliases are POST /bonga and POST /v1/voice/responses; they accept the same request and return the same response as /v1/bonga.

For music generation, see Music Generation. Music is a separate audio-generation request; Bonga does not generate or attach music to a video.

What Bonga means to the user

Bonga is the product experience built around the combined route. A user taps the microphone, speaks Kiswahili, sees the recognized words, and gets both a written and spoken reply. Letting the user review the transcript before sending is a useful privacy and accuracy control. They should be able to stop playback, replay it, switch voice, and fall back to text when the connection is poor.

The current combined route is synchronous: one JSON request carries base64 input audio and the response carries base64 output audio. That is appropriate for short voice notes and an MVP. For a live, interruptible conversation, the app would need streaming audio and partial transcripts; for longer conversations, it should use an asynchronous session/job design. Those are follow-on engineering tasks, not behavior this route promises today.

Language coverage

Bonga is not an all-languages end-to-end endpoint. Input transcription follows the selected transcription model; language is a recognition hint and defaults to sw. The current response_language field accepts sw or en. Spoken output depends on the selected speech model and approved voice, and may not cover every input language. Check the live catalog and test the exact language, dialect, and voice you plan to offer.

Bonga, step by step

1. Capture: the app records a short voice note and uploads it securely. Ask for microphone permission only when the user starts recording.
2. Transcribe: The selected transcription model returns the Kiswahili transcript. Let the user correct names, amounts, and misunderstood words before consequential actions.
3. Answer: Ngamia sends the transcript to a selected text model with an instruction for clear Tanzanian Kiswahili. Text models remain separate from speech models.
4. Speak: The selected speech model generates audio with an approved voice. Save or stream the returned audio and show the text answer even if audio fails.
5. Account: debit the user for the stages that ran and record model, generation IDs, latency, usage, and charges for support and margin reporting. Show the estimated debit before a long or expensive operation.

Do not use speech recognition as authorization for payments or account changes. Confirm such actions in text or through a separate authenticated control. Avoid keeping raw recordings by default; set a clear retention policy before adding saved voice history.

Voice Studio and learning workflows

Voice Studio should offer templates for ads, store announcements, public-service notices, and narration. A business can write its script, choose a voice, preview a short sample, see the character-based estimate, and download the complete audio. Optional music should be a separate opt-in charge with its own duration estimate so a user can remove or regenerate it without rerunning speech.

Read and learn can use the same pipeline: summarize or simplify notes with the text model, then synthesize the output. For long lessons, split at paragraph boundaries, preserve section order, and join the audio in a background job. Keep the original notes, generated summary, and audio as separate downloadable artifacts only when the user chooses to save them.

Creator tools: what “video plus music” means

A soundtrack-generation capability may accept video and return music audio without mixing it into the original video. Ngamia would need to combine the soundtrack with the source, render and store the finished media, and provide a download link. Video dubbing similarly needs job status, translated transcript review, speaker/voice handling, rendering, and storage. Multi-speaker dialogue and dubbing are not currently available through Ngamia's public gateway.

The routes below describe the current public API behavior. Additional creator workflows remain future product work.

For customer-owned voice cloning, listing, and deletion, see Audio Tools. A clone can be used only by the Ngamia account that created it.

1. Speech-to-text

Ngamia accepts either JSON with raw base64 audio or OpenAI-compatible multipart/form-data. The optional model must be a public value returned by GET /v1/models whose output_modalities contains transcription. Omit it to use the configured default.

JSON with base64 audio

input_audio.data is the raw base64 string. It is not a data: URI. The audio format must match the bytes you send.

import base64
import os
import requests
 
with open("voice-note.mp3", "rb") as audio_file:
    audio_base64 = base64.b64encode(audio_file.read()).decode("ascii")
 
response = requests.post(
    "https://api.ngamia.cc/v1/audio/transcriptions",
    headers={
        "Authorization": "Bearer " + os.environ["NGAMIA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "input_audio": {
            "data": audio_base64,
            "format": "mp3",
        },
    },
    timeout=90,
)
response.raise_for_status()
print(response.json()["text"])

Multipart upload

curl https://api.ngamia.cc/v1/audio/transcriptions \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -F "language=sw" \
  -F "file=@voice-note.mp3"

The gateway caps audio input at 25 MiB. Compressed formats such as MP3 are usually a better fit for mobile voice notes. Split unusually long recordings into smaller requests and apply your own duration policy before forwarding user content.

A successful response is JSON:

{
  "text": "Habari, naomba unisaidie kuhusu malipo.",
  "language": "sw",
  "duration": 8.4,
  "usage": {
    "seconds": 8.4,
    "input_tokens": 42,
    "output_tokens": 12,
    "total_tokens": 54
  }
}

X-Generation-Id, when returned, is a generation identifier for support correlation. Keep it with your application request id, but do not expose credentials or raw audio in support logs.

2. Text-to-speech

Send text to a model whose output_modalities contains speech. The response is a raw audio stream, not JSON. The gateway supports mp3 and pcm. Choose a speech-capable model from the live catalog and use a valid voice ID configured for your Ngamia account. The voice field is an account voice identifier; language coverage and accent depend on the selected voice.

import os
import requests
 
response = requests.post(
    "https://api.ngamia.cc/v1/audio/speech",
    headers={
        "Authorization": "Bearer " + os.environ["NGAMIA_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "input": "Karibu Ngamia. Tunaweza kuzungumza kwa Kiswahili.",
        "voice": "<approved voice ID>",
        "response_format": "mp3",
        "speed": 1.0,
    },
    timeout=90,
)
response.raise_for_status()
with open("reply.mp3", "wb") as audio_file:
    audio_file.write(response.content)
print(response.headers.get("X-Generation-Id"))

The response includes an audio Content-Type and may include X-Generation-Id. Save PCM with a format appropriate to your playback pipeline; do not rename raw PCM bytes as MP3.

3. Bonga combined response

The Bonga route accepts a JSON body with base64 audio. It runs transcription, text response generation, and optional speech synthesis in sequence. The default input and response language is Kiswahili (sw). Set response_language to en only when your user experience intentionally requests an English response. POST /bonga and POST /v1/voice/responses remain aliases for existing clients.

{
  "audio_data": "<raw-base64-audio>",
  "audio_format": "mp3",
  "response_language": "sw",
  "voice": "<approved voice ID>",
  "response_format": "mp3",
  "include_audio": true
}

audio_data and audio_format are required. stt_model, text_model, tts_model, and voice are optional — omitted fields use the configured server defaults. Set include_audio to false when you only need the transcript and generated text; this avoids the speech stage and does not require a TTS model.

The response is JSON:

{
  "transcript": "Habari, naomba unisaidie kuhusu malipo.",
  "transcript_language": "sw",
  "text": "Hakika. Tafadhali niambie unahitaji msaada gani kuhusu malipo.",
  "audio_base64": "<generated-base64-audio>",
  "audio_content_type": "audio/mpeg",
  "speech_generation_id": "gen_..."
}

Example request:

curl https://api.ngamia.cc/v1/bonga \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_data": "<raw-base64-audio>",
    "audio_format": "mp3",
    "language": "sw",
    "response_language": "sw",
    "include_audio": false
  }'

Existing clients can send the same JSON body to either alias. Update BONGA_URL to select the route:

BONGA_URL=https://api.ngamia.cc/bonga
curl --fail-with-body "$BONGA_URL" \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_data":"<raw-base64-audio>","audio_format":"mp3","response_language":"sw","include_audio":false}'
 
BONGA_URL=https://api.ngamia.cc/v1/voice/responses
curl --fail-with-body "$BONGA_URL" \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_data":"<raw-base64-audio>","audio_format":"mp3","response_language":"sw","include_audio":false}'

The text stage is instructed to preserve Tanzanian names, numbers, dates, TZS amounts, and payment references. Treat transcription and model output as untrusted content: your application must still validate amounts, authorization, and any action that could create a key, move money, or change an account.

Discover compatible models

Do not hardcode the illustrative model values above. Fetch the live catalog and select records by capability:

curl https://api.ngamia.cc/v1/models \
  -H "Authorization: Bearer $NGAMIA_API_KEY"

The catalog is paid-only by default and can change as models or prices change. Refresh it when your service starts and when a request returns a model-not-found or unsupported-modality error.

Credits, retries, and operational behavior

Each direct voice stage reserves and settles credits through the normal Ngamia ledger. Transcription is settled from the upstream-reported usage.cost in USD converted to credits at the configured rate; speech is settled from the model's pricing, or a nominal credit when the provider reports no usage. The reservation is capped so an unmetered check never blocks a normal account, and the actual charge never exceeds the account balance.

Use a unique Idempotency-Key only where the endpoint and your deployment explicitly support safe replay. Do not blindly replay raw audio or speech requests, because replaying a side-effecting or billable operation can create an unexpected charge. On network failure, first determine whether your application received a successful response, then decide whether to retry according to your own request policy.

Voice responses are synchronous and base64-encoded on the combined route. For production mobile applications, enforce client-side duration and size limits, show progress and cancellation states, and avoid retaining recordings by default.

Errors

Non-success responses are JSON error objects even when the successful speech response is raw audio. Always check the HTTP status before writing a speech response to a file.

Security and privacy

Keep the API key on your server, not in a browser or mobile bundle. Voice notes can contain personal data, payment details, or confidential business information. Obtain any consent required for your use case, avoid sending recordings to logs or analytics, encrypt any retained media, apply an expiry, and delete it when no longer needed. See Security & data handling.

References

These routes use familiar request formats while remaining compatible with Ngamia's credit and reservation model.