Video Generation

Video Generation lets you generate a short video from a text prompt through a catalog model whose output modality is video. Generation is asynchronous — a request returns a job_id immediately and the video is produced behind the scenes over tens of seconds to minutes, so you poll for the result and download the finished file through Ngamia rather than a raw provider URL.

Submit a generation

Send a JSON body with a model slug and a prompt. model and prompt are required; every other parameter — duration, resolution, aspect_ratio, generate_audio, seed, and anything else the selected model accepts — passes through to the upstream unmodified. The request is authenticated by API key or JWT, rate-limited, and deduplicated by Idempotency-Key like the other gateway requests. Generation itself runs asynchronously, so there is no streaming mode — a replay key deduplicates identical submissions rather than re-running upstream work.

curl -X POST "https://api.ngamia.cc/v1/videos" \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A golden retriever playing fetch on a sunny beach",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

A successful submit returns 202 Accepted with the standard envelope:

{
  "status": "success",
  "code": 202,
  "data": {
    "job_id": "54f8cbd2-1f6a-4a3c-bbd7-0a2f4e3b6c10",
    "status": "pending",
    "created_at": "2026-08-30T07:12:29Z"
  },
  "request_id": "req_..."
}

Poll a job

Poll with the job_id until the status reaches a terminal value. Ownership is enforced: a job belonging to another principal returns 404, so never leak or guess job ids. The response carries status and settled cost only — the finished video is served separately through the content endpoint.

{
  "status": "success",
  "code": 200,
  "data": {
    "job_id": "54f8cbd2-1f6a-4a3c-bbd7-0a2f4e3b6c10",
    "status": "completed",
    "usage": {
      "cost_credits": 450.5
    }
  },
  "request_id": "req_..."
}

There is no fixed completion deadline published here — realistic generation times span tens of seconds to minutes depending on the model, duration, and resolution. Poll with a modest interval (for example every 30–60 seconds) rather than busy-looping.

Download the finished video

Once the status is completed, GET the content endpoint to stream the video bytes (Content-Type: video/mp4). Ngamia fetches the bytes server-side with its own upstream key, so the client never sees a provider URL. The response is Cache-Control: no-store and is only servable while the job is completed and within the temporary upstream retention period.

curl -o generated.mp4 \
  "https://api.ngamia.cc/v1/videos/54f8cbd2-1f6a-4a3c-bbd7-0a2f4e3b6c10/content" \
  -H "Authorization: Bearer $NGAMIA_API_KEY"

If the job is not finished yet the endpoint returns 409; if the upstream content has lapsed or is no longer retrievable it returns 410 gone — in that case resubmit the generation rather than retrying the download.

Credits and billing

Video generation runs the gateway's reservation lifecycle: a conservative credit hold is placed when you submit (pending), the hold is renewed while the job is legitimately still running (processing), and it is settled when the generation completes or released when the job fails, cancels, or expires. Settlement uses the upstream's reported usage.cost converted to credits by the platform's VIDEO_USD_TO_CREDIT_RATE, falling back to the catalog's per-request price when usage is unavailable. A generation that never completes is never billed.

The selected model must advertise video output in the catalog; models whose output_modalities exclude video are rejected up front with a 400.

Errors

Non-success responses are standard Ngamia error envelopes. Always check the HTTP status before treating a download as a finished video.

Discover compatible models

Fetch the live catalog and select a record whose output_modalities includes video:

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. Different models support different durations, resolutions, and aspect ratios — confirm the parameters your generated videos need before picking a model.

Security and privacy

Keep the API key on your server, not in a browser or mobile bundle. Prompts and generated videos may contain sensitive, personal, or branded material. Obtain any consent required for your use case, avoid writing prompt text or generated bytes to logs or analytics, encrypt any retained content, apply an expiry, and delete it when no longer needed. Generated videos are not verified facts or asset records — review them before publishing and apply the same content rules as any other user media. See Security & data handling.