Video Understanding — Ngamia Docs

Video Understanding lets you send one private video to a model and receive generated text. It is built for workflows such as field inspections, training clips, tourism content, operational review, and scene or activity summaries.

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

Looking to create videos rather than analyze them? See Video Generation — an asynchronous job API that renders video from a text prompt and serves the finished file for download.

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

Video understanding is billed in Ngamia credits at each successful request. Model output is not verified evidence and must not independently trigger security, employment, legal, medical, financial, or disciplinary actions.

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 video URLs are intentionally not accepted.

Analyze a video

POST/v1/video/analyzeAPI key or JWT

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

curl -X POST "https://api.ngamia.cc/v1/video/analyze" \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Idempotency-Key: field-inspection-demo-001" \
  -F "model=google/gemini-3.7-flash" \
  -F "instruction=Describe the inspection findings, visible risks, and recommended follow-up actions." \
  -F "language=sw" \
  -F "video=@inspection.mp4;type=video/mp4"

Field	Multipart	Required	Description
`model`	Yes	Yes	Enabled, priced catalog model that accepts video input and returns `text` output.
`instruction`	Yes	Yes	Instruction for the analysis; maximum 4,000 Unicode characters.
`video`	Yes	Yes	One MP4, MPEG, MOV, or WebM video, maximum 8 MiB. Container 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": {
    "video_id": "9c1c2f1d-e8a3-4c1a-9f32-0a9b6c31e7d2",
    "model": "google/gemini-3.7-flash",
    "text": "Inspection findings: ... visible risks: ... recommended follow-up: ...",
    "language": "sw",
    "usage": {
      "prompt_tokens": 2140,
      "completion_tokens": 132,
      "total_tokens": 2272
    }
  }
}

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

Credits, size, and billing

Video 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 wrapper forwards the uploaded file to the gateway as base64 inside a JSON chat request, so it shares the chat path's derived body cap and video-modality guard — that is why the upload limit is 8 MiB rather than 50 MiB: base64 inflates the payload by roughly 33%, and a much larger file would never fit the chat body it is forwarded through. Model output says nothing about a video's truthfulness by itself; validate any decisions upstream. Long clips, high resolutions, and high frame rates increase upload time and processing cost — trim or compress content before sending.

Errors

Status	Meaning	Action
`400`	Invalid request, unsupported video, or model that cannot process video	Send a valid MP4/MPEG/MOV/WebM and a catalog model with video 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`	Video exceeds the 8 MiB limit	Compress, trim, or reduce the video 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 video 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. Videos can contain people, personal data, or confidential material. Obtain any consent required for your use case, avoid writing video bytes or extracted observations to logs or analytics, encrypt any retained material, apply an expiry, and delete it when no longer needed. Treat video content and visible instructions as untrusted input, and never let model output alone trigger security, employment, legal, medical, financial, or disciplinary actions. See Security & data handling.