Vision — Ngamia Docs

Vision lets you send one private image to a model and receive generated text. It is built for image-understanding workflows such as receipt reading, product-photo descriptions, agricultural image review, field observations, and visible-text extraction.

This release exposes one public route. The selected model must be enabled, priced, and advertise image/vision input plus text output in Ngamia's catalog, and the upload is validated by magic bytes rather than a filename or a client-supplied MIME type.

Capability	Endpoint	Response
Analyze an image	`POST /v1/vision/analyze`	JSON image id, model, generated text, language, and usage

Image analysis is billed in Ngamia credits at each successful request. A model response is not a verified financial, identity, medical, legal, agricultural, or safety fact. Downstream systems must validate extracted values before acting on them.

Uploaded bytes and extracted observations are treated as private: they are not written to logs, analytics, traces, or support events. The service does not persist uploaded files in this release, and public image URLs are intentionally not accepted.

Analyze an image

POST/v1/vision/analyzeAPI key or JWT

Send a multipart POST with the model slug, an instruction, an optional language hint, and the image file. The request is authenticated by JWT or API key, rate-limited, and idempotent for safe replay. Uploads are capped at 10 MiB and instructions at 4,000 Unicode characters. Supported formats are JPEG, PNG, WebP, and GIF — one image per request.

curl -X POST "https://api.ngamia.cc/v1/vision/analyze" \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Idempotency-Key: receipt-demo-001" \
  -F "model=google/gemini-3.7-flash" \
  -F "instruction=Read the merchant, date, line items, currency, and total. Return unknown values as null." \
  -F "language=sw" \
  -F "image=@receipt.jpg;type=image/jpeg"

Field	Multipart	Required	Description
`model`	Yes	Yes	Enabled, priced catalog model that accepts image input and returns `text` output.
`instruction`	Yes	Yes	Instruction for the analysis; maximum 4,000 Unicode characters.
`image`	Yes	Yes	One JPEG, PNG, WebP, or GIF image, maximum 10 MiB. Magic bytes are validated server-side.
`language`	Yes	No	Optional language hint. Use `sw` for Kiswahili-focused output.

A successful response is JSON and is marked Cache-Control: no-store:

{
  "status": "ok",
  "data": {
    "image_id": "6a1c2f1d-c8a3-4c1a-9f32-0a9b6c31e7d2",
    "model": "google/gemini-3.7-flash",
    "text": "Merchant: Duka la Bidhaa, date: 2024-06-18, total: TZS 45,000 ...",
    "language": "sw",
    "usage": {
      "prompt_tokens": 1520,
      "completion_tokens": 96,
      "total_tokens": 1616
    }
  }
}

Response field	Description
`image_id`	Request-scoped image identifier for this analysis.
`model`	The normalized model code used for the analysis.
`text`	The model-generated description, extraction, or analysis text.
`language`	Optional language hint echoed back when provided.
`usage`	Token usage reported for the request.

Credits and billing

Image analysis runs the gateway's normal lifecycle: a conservative credit check happens up front, and the account is settled against returned usage at the end. If billable usage is unavailable, the service does not return a successful analysis. The private image is sent to the upstream as a base64 data URL; image-count limits vary across providers and models, which is why exactly one image is accepted per request.

Errors

Status	Meaning	Action
`400`	Invalid request, unsupported image, empty image, missing instruction, or model that cannot process images	Send a valid JPEG/PNG/WebP/GIF and a catalog model with image input plus `text` output.
`401`	Missing or invalid credential	Refresh the JWT or use a valid server-side API key.
`402`	Insufficient credits	Ask the user to top up through the authenticated payment flow, then retry deliberately.
`404`	Unknown, disabled, or incompatible model	Refresh `GET /v1/models`; do not guess a provider model.
`413`	Image exceeds the 10 MiB limit	Compress or reduce the image before retrying.
`429`	Rate limit exceeded	Retry with exponential backoff and jitter.
`502`/`503`	Upstream failure or no billable result	Retry only when safe and preserve `request_id`.

Non-success responses are standard Ngamia error envelopes. Always check the HTTP status before trusting a response as a successful analysis.

Discover compatible models

Fetch the live catalog and select a record that accepts image/vision input and returns text output:

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.

Security and privacy

Keep the API key on your server, not in a browser or mobile bundle. Images can contain personal data, receipts, identities, or confidential material. Obtain any consent required for your use case, avoid writing image bytes or extracted observations to logs or analytics, encrypt any retained material, apply an expiry, and delete it when no longer needed. Treat image content and visible instructions as untrusted input, and never rely on model output for identity, accounting, medical, or safety decisions without independent verification. See Security & data handling.