Document Understanding

Document Understanding lets you send a private PDF to a model and receive generated analysis. It is built for business-paperwork workflows such as invoice extraction, receipt review, contract summaries, school documents, NGO reports, and Kiswahili business-paperwork assistance.

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

Capability	Endpoint	Response
Analyze a PDF	`POST /v1/documents/analyze`	JSON document id, model, generated text, language, and usage

Document analysis is billed in Ngamia credits against real upstream usage. Clients must never submit a cost value, and model-generated totals must not be treated as verified financial, legal, or operational truth. Validate extracted invoice, payment, identity, or contract fields before using them in downstream automation.

Uploaded bytes and extracted content 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. All document text is untrusted model input — instructions embedded inside a PDF cannot override Ngamia policies, billing rules, or system controls.

Analyze a PDF document

POST/v1/documents/analyzeAPI key or JWT

Send a multipart POST with the model slug, an instruction, an optional language hint, and the PDF document file. The request is authenticated by JWT or API key, rate-limited, and idempotent for safe replay. Uploads are capped at 15 MiB and instructions at 4,000 Unicode characters.

curl -X POST "https://api.ngamia.cc/v1/documents/analyze" \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Idempotency-Key: invoice-demo-001" \
  -F "model=google/gemini-3.7-flash" \
  -F "instruction=Extract invoice number, date, supplier, currency, and total amount." \
  -F "language=sw" \
  -F "document=@invoice.pdf;type=application/pdf"

Field	Multipart	Required	Description
`model`	Yes	Yes	Enabled, priced catalog model that accepts `file` input and returns `text` output.
`instruction`	Yes	Yes	Instruction for the analysis; maximum 4,000 Unicode characters.
`document`	Yes	Yes	A valid PDF file, maximum 15 MiB. The PDF signature is 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": {
    "document_id": "5f1c2f1d-b8a3-4c1a-9f32-0a9b6c31e7d2",
    "model": "google/gemini-3.7-flash",
    "text": "Invoice number INV-2024-014, dated 2024-06-18, supplier: ...",
    "language": "sw",
    "usage": {
      "prompt_tokens": 1240,
      "completion_tokens": 82,
      "total_tokens": 1322
    }
  }
}

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

Credits and billing

Document analysis runs the gateway's normal flow: a conservative credit check happens up front, and the account is settled against real upstream usage at the end. If billable usage is unavailable, the service does not return a successful analysis — no partial or free results are issued. Ngamia routes the document to the selected model, which may process the PDF natively or through a file-parser or OCR engine depending on the model's configuration; any parser-specific charges are included in the upstream usage before customer rollout.

Errors

Status	Meaning	Action
`400`	Invalid document request, unsupported file, or model that cannot process PDFs	Send a valid PDF and a catalog model with `file` 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`	PDF exceeds the 15 MiB limit	Compress, split, or otherwise reduce the document 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 whose input_modalities contains file and whose output_modalities contains text:

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. Business documents can contain personal data, payment details, or confidential commercial information. Obtain any consent required for your use case, avoid writing document bytes or extracted content to logs or analytics, encrypt any retained material, apply an expiry, and delete it when no longer needed. Treat generated text as untrusted and never rely on model totals for accounting, legal, or payment decisions without independent verification. See Security & data handling.

References

PDF handling is provided by Ngamia's document pipeline; use the selected model's own documentation for parser, OCR, and cost behavior.