Get started with the ngram API

What the ngram API is

The ngram public API generates videos and images programmatically. The base URL is https://www.ngram.com/api/v1, every request is authenticated with a bearer key, and every response is wrapped in a { success, data } envelope. The same key powers the MCP server and the Zapier and n8n connectors, so anything you can do here you can do from those surfaces too.

Get an API key

1. Open Settings → API keys in your ngram dashboard.
2. Create a key. It starts with ngs_ and carries the same permissions as your account.
3. Copy it once and store it as a secret — the full key is shown only at creation. You can rotate or revoke it from the same screen at any time.

Authenticate

Send your key as a bearer token on every request. A request without a valid key returns 401. A quick way to confirm your key works is to read your credit balance:

curl https://www.ngram.com/api/v1/account/credits \
  -H "Authorization: Bearer ngs_your_key"

The response is the standard envelope:

{
  "success": true,
  "data": { "available": 1200, "reserved": 0, "effective": 1200, "plan": "pro" }
}

Create a video

Video generation is asynchronous. You POST a prompt, get a job back with status processing and an HTTP 202, then either poll for the result or wait for a webhook. Send an Idempotency-Key header so a retried request never starts a second render.

curl -X POST https://www.ngram.com/api/v1/videos:fromText \
  -H "Authorization: Bearer ngs_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-2026-07-07-01" \
  -d '{
    "prompt": "A 60-second explainer for our new analytics dashboard",
    "aspect_ratio": "16:9",
    "duration": 60,
    "webhook_url": "https://example.com/hooks/ngram"
  }'

The response returns the job id you will use to track it:

{
  "success": true,
  "data": {
    "id": "vid_9aXk2mQ",
    "status": "processing",
    "created_at": "2026-07-07T18:20:00Z"
  }
}

Check status

Poll the job by id. progress runs from 0 to 100, and when status is completed the finished MP4 is at result.url.

curl https://www.ngram.com/api/v1/videos/vid_9aXk2mQ \
  -H "Authorization: Bearer ngs_your_key"

{
  "success": true,
  "data": {
    "id": "vid_9aXk2mQ",
    "status": "completed",
    "progress": 100,
    "result": { "url": "https://cdn.ngram.com/renders/final.mp4", "duration_ms": 60000 }
  }
}

Get notified with a webhook

Instead of polling, subscribe to events. ngram emits video.completed and video.failed, and signs each delivery with an X-Ngram-Signature HMAC and an X-Ngram-Timestamp header so you can verify it came from ngram.

curl -X POST https://www.ngram.com/api/v1/webhooks/subscriptions \
  -H "Authorization: Bearer ngs_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "video.completed",
    "target_url": "https://example.com/hooks/ngram"
  }'

The response includes a per-subscription secret — store it and use it to check the signature on each delivery.

Limits and errors

• Up to three video jobs can be processing per account at once. Beyond that, create returns 429.
• Errors come back as an { error: { code, message } } envelope with the matching HTTP status.
• Insufficient credits return 402, so check the balance endpoint before a batch.

Pick your surface

The same key drives four ways to call ngram — choose the one that fits how you build:

• REST API — the endpoints on this page, callable from any language.
• MCP server — let Claude, Cursor and other agents render videos as tool calls.
• Zapier — wire ngram into thousands of apps with no code.
• n8n — build self-hosted workflows around the render API.