Embeddings — Ngamia Docs

POST/v1/embeddingsAPI key or JWT

Ngamia provides a non-streaming embeddings endpoint for semantic search, retrieval-augmented generation, classification, clustering, and similarity workflows. The response follows the OpenAI embeddings shape, while model availability and pricing come from Ngamia’s live catalog.

Use a model returned by GET /v1/models whose output_modalities contains embeddings. Do not hardcode a model or assume that a chat model can create vectors. Ngamia excludes free and zero-priced models from the normal catalog.

Request fields

Field	Required	Description
`model`	Yes	The public model value returned by `GET /v1/models`, such as `voyageai/voyage-4-lite`.
`input`	Yes	One string or an array of strings. Use an array for batches.
`encoding_format`	No	`float` for numeric vectors or `base64` when supported by the selected model.
`dimensions`	No	Requested vector length when supported by the selected model.

The model value is the catalog’s public model identifier. The upstream provider credential and routing details are not part of the public request.

Create one embedding

curl https://api.ngamia.cc/v1/embeddings \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyageai/voyage-4-lite",
    "input": "Mteja anauliza kuhusu malipo ya simu Tanzania.",
    "encoding_format": "float"
  }'

Create a batch

from openai import OpenAI
 
client = OpenAI(
    api_key="ngm_...",
    base_url="https://api.ngamia.cc/v1",
)
 
result = client.embeddings.create(
    model="voyageai/voyage-4-lite",
    input=[
        "Karibu Ngamia.",
        "Mteja anaomba msaada wa malipo.",
    ],
)
 
for item in result.data:
    print(item.index, len(item.embedding))

Response

{
  "object": "list",
  "model": "voyageai/voyage-4-lite",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0123, -0.0456, 0.0789],
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "total_tokens": 14
  }
}

The data array preserves the input order through each item’s index. Store the model and vector dimensions with your own index so that a later model change cannot silently mix incompatible vector spaces.

Model discovery and pricing

Fetch the catalog before creating a model picker or provisioning an index:

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

Filter the response in your application using these fields:

Field	How to use it
`model`	Send this public value in the request.
`input_modalities`	Confirm that the model accepts the input type you plan to embed.
`output_modalities`	Select models containing `embeddings`.
`supported_parameters`	Enable optional request fields only when the model advertises them.
`input_price_per_1k_credits`	Estimate token-based input cost.
`request_price_credits`	Include any per-request charge in your estimate.

Prices and availability can change. Read the live catalog at startup and refresh it after a model-not-found response. A successful embedding response includes provider-reported token usage when available, and Ngamia records the request in the account’s usage and credit ledger.

Retry and errors

Embeddings are non-streaming. Send an Idempotency-Key when your client may retry the same logical request after a network interruption. Reuse the same key only for the same request body; use a new key for a new input.

A 402 means the account does not have enough credits. A 404 usually means that the model is unknown or does not advertise embedding output. A 429 should be retried with exponential backoff and jitter. See Errors and response format and Rate limits.

Security and privacy

Keep the API key on your server. Do not send private documents directly from a browser with a long-lived key, and do not put raw document text or vectors in logs. Apply your own tenant authorization before embedding content and delete vectors when the source data’s retention period ends. See Security & data handling.

References

Ngamia's response shape is designed for compatibility with the OpenAI embeddings API. Discover embedding-capable models from the live catalog by selecting records whose output_modalities contains embeddings.