Ngamia lets you use many model providers through one OpenAI-compatible API. If your application already uses the OpenAI SDK, you usually only need to change the base_url, replace the API key, and choose a Ngamia model id.
For production integrations, use an API key that starts with ngm_.... Keep the key on your server, never in browser code or a mobile app bundle.
The platform at a glance
| Component | URL or value | What it is |
|---|---|---|
| Production API | https://api.ngamia.cc/v1 | OpenAI-compatible gateway for model requests. |
| Documentation | https://docs.ngamia.cc | Guides, endpoint details, examples, and troubleshooting. |
| Local development | http://localhost:8080/v1 | Base URL when running the API locally. |
| API key | ngm_... | Server-side credential for model and gateway requests. |
| Model id | A bare catalog id, e.g. openai/gpt-4o-mini | The value passed in the model field. |
What Ngamia gives you
| Capability | How it helps your integration |
|---|---|
| One OpenAI-compatible interface | Keep the request and response model you already know while changing providers behind the gateway. |
| One model catalog | Discover enabled paid models, modalities, supported parameters, and live pricing from GET /v1/models instead of hardcoding a list. |
| Chat and multimodal requests | Send OpenAI-compatible text or supported multimodal requests through one gateway. |
| Embeddings | Create complete vectors for semantic search and retrieval workflows through POST /v1/embeddings. |
| Ongea na Ngamia voice | Transcribe Kiswahili voice notes, generate localized text, and optionally return audio. |
| TZS credit billing | Top up and track usage in Tanzanian Shillings rather than maintaining separate provider billing accounts. |
| One API key | Use a single server-side credential across the enabled model catalog. |
| Usage visibility | Read token counts, audio duration, characters, cost, latency, and status from activity and billing endpoints. |
Why use Ngamia instead of one provider directly?
| Concern | Direct provider integration | Ngamia |
|---|---|---|
| Provider coverage | One provider per integration | Many enabled providers behind one gateway |
| Client code | Provider-specific setup | OpenAI-compatible SDK and request shape |
| Model selection | Maintain provider-specific ids | Discover the current catalog from the API |
| Billing | Provider currency and account | TZS credits and one balance |
| Switching providers | Update credentials and integration code | Change the model value when the model is enabled |
How an integration fits together
- Create and verify an account. Use Register, login & sessions to obtain a JWT for account management.
- Create an API key. Use the JWT to create a key on the API keys page. The secret is shown once.
- Choose a model. Fetch Models from
GET /v1/modelsand store the returned model id. - Send a request. Call Chat completions, Embeddings, or Voice & Ongea na Ngamia with the API key and selected catalog model.
- Monitor usage. Use Activity & analytics and Billing to inspect usage and balance.
Request and response model
Most account, billing, activity, and operational endpoints return Ngamia’s standard JSON envelope:
{
"status": "success",
"code": 200,
"data": {},
"request_id": "req_..."
}POST /v1/chat/completions is intentionally different: it mirrors OpenAI’s Chat Completions response and error shape so existing SDKs continue to work. The distinction is explained in Errors.
Next steps
- Follow the Quickstart to make your first request.
- Read Authentication to choose between JWT and API key credentials.
- Check Models before hardcoding a model id or price.
- Use Chat completions for the full request, response, error, and retry reference.