NgamiaNgamiaDocs

Get started

Quickstart

Create an API key, send your first OpenAI-compatible request, and verify the cost in a few minutes.

This guide takes you from an empty project to a successful Ngamia response. You do not need a Ngamia-specific SDK: use the OpenAI SDK or send HTTP requests directly.

Before you start

You needValue
API base URLhttps://api.ngamia.cc/v1
API keyA server-side key beginning with ngm_...
Model idThe public model value returned by GET /v1/models, such as openai/gpt-4o-mini
CreditsEnough balance for the request; see Billing if you need to top up.

Never commit an API key to source control. Store it in a server-side environment variable such as NGAMIA_API_KEY.

1. Create and verify an account

Use the dashboard or the public authentication endpoints to register and verify your account. The verification response gives you a JWT for account management.

POST/v1/auth/register
{
  "full_name": "Ada Lovelace",
  "email": "ada@example.com",
  "password": "Sup3rSecret1",
  "confirm_password": "Sup3rSecret1"
}

Then verify the six-digit code sent to the email or phone number:

POST/v1/auth/otp/verify
{
  "identifier": "ada@example.com",
  "channel": "email",
  "purpose": "verify_email",
  "code": "123456"
}

The response contains an access_token and refresh_token. Use the access token for the next step. Access tokens expire after 15 minutes; use Refresh when it expires.

2. Create an API key

Create the key with the JWT from step 1:

POST/v1/api-keysJWT
{ "name": "production-server" }

The response contains the full ngm_... secret exactly once. Copy it into your secret manager or environment immediately. Later list requests return only the key prefix.

3. Discover an available model

Do not hardcode a model or its price. Ask the catalog for models enabled for your key:

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

Use the returned public model value in the next request. See Models for the response fields, modalities, and pricing columns.

4. Send your first request

The gateway uses the same request shape as OpenAI. Choose one example and keep the API key server-side.

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."}
  ]
}'

5. Confirm the response

A successful chat completion follows the OpenAI response shape:

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

Ngamia debits the balance after the response completes, using the provider’s actual token counts. The completion body does not include the price; use the activity and billing endpoints to inspect it.

6. Check balance and usage

curl https://api.ngamia.cc/v1/billing/balance \\
  -H "Authorization: Bearer $NGAMIA_API_KEY"
 
curl https://api.ngamia.cc/v1/activity \\
  -H "Authorization: Bearer $NGAMIA_ACCESS_TOKEN"

Use the API key for gateway calls and the JWT for account activity. The distinction is covered in Authentication.

If the request fails

  • A 401 usually means the bearer token is missing, expired, or from the wrong credential type.
  • A 402 means the account needs more credits.
  • A 404 often means the model id is not enabled; fetch /v1/models again.
  • A 429 means the request should be retried with backoff; see Rate limits.
  • A 5xx response may be temporary; log the request_id and retry safely with Idempotency.

Next steps