Chat Completions — Ngamia Docs

POST/v1/chat/completionsAPI key or JWT

Ngamia deliberately mirrors OpenAI’s Chat Completions request, success response, and error shape. Existing OpenAI SDKs can usually connect by changing base_url to https://api.ngamia.cc/v1 and using an ngm_... API key.

Use an API key for production gateway traffic. It is long-lived, server-side, and receives rate limits by key id. A JWT can call this endpoint, but it expires and uses a less precise shared fallback rate-limit bucket.

The minimum request

Field	Required	What to send
`model`	Yes	A model id from `GET /v1/models`, such as `openai/gpt-4o-mini`.
`messages`	Yes	An ordered array of `{role, content}` messages.
`stream`	No	`false` by default. Set `true` for server-sent event streaming.
Other OpenAI fields	No	Fields such as `temperature`, `max_tokens`, `top_p`, and `tools` are passed through when the selected provider supports them.

{
  "model": "openai/gpt-4o-mini",
  "messages": [
    { "role": "user", "content": "Say hello in Swahili." }
  ],
  "stream": false
}

The model value is a bare catalog id (it may itself contain a /). The legacy provider/model_code prefixed form still resolves for backward compatibility, but the bare id is canonical. Fetch the current catalog instead of hardcoding a list; see Models.

Send a request

curl https://api.ngamia.cc/v1/chat/completions \\
-H "Authorization: Bearer $NGAMIA_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {"role": "user", "content": "Say hello in Swahili."}
  ]
}'

Successful response

A non-streaming response follows the OpenAI shape:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1752500000,
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Habari!" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 3,
    "total_tokens": 15
  }
}

The completion body does not include the price. Ngamia debits the account after the response completes and records actual provider token counts in Activity and Billing.

Streaming

Set stream to true to receive incremental server-sent events. Each event follows the OpenAI streaming chunk format. Buffer the delta content until the stream ends, then handle the final usage event if it is present.

See Streaming for the event shape and a consumer example.

Errors and retry behavior

This endpoint returns OpenAI-shaped errors instead of Ngamia’s standard envelope:

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "code": null
  }
}

HTTP	Error type or code	What it usually means	What your integration should do
400	`invalid_request_error`	The model id or request fields are invalid.	Read the message, correct the request, and do not retry unchanged.
402	`insufficient_quota`	The account does not have enough credits.	Ask the account owner to top up before retrying.
404	`invalid_request_error`	The model does not exist or is not enabled.	Refresh the model catalog and choose an enabled id.
429	`rate_limit_exceeded`	The API key or IP has sent too many requests.	Retry with exponential backoff and jitter.
502/503	`server_error`	The selected upstream provider failed or is temporarily unavailable.	Retry safely with backoff; consider another enabled model if it persists.

Safe retries

Add an Idempotency-Key header when a network failure leaves the outcome unknown:

Idempotency-Key: 3e2a7b4e-5c38-4d7b-bf12-1a3f46d9f1a8

Reuse the same key only when retrying the same logical request. See Idempotency for the supported endpoints and conflict behavior.

Provider health

GET/v1/gateway/healthNo authentication

Use this endpoint for a status page or operational check. It returns the standard Ngamia envelope rather than the OpenAI-compatible shape, and it is deliberately aggregate — it reports whether Ngamia's upstream providers are reachable and how many, never their names or individual latencies.

{
  "status": "success",
  "code": 200,
  "data": {
    "healthy": true,
    "upstreams_total": 2,
    "upstreams_healthy": 2
  },
  "request_id": "req_..."
}