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 credential format is used by supported MCP, Zapier, and n8n connections when their setup flow asks for bearer authentication.

Create an API key

API-key management is self-service for every signed-in user. Open Settings → API Keys to create, rotate, or revoke a bearer credential without requesting separate developer access.

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.