Get started with the ngram API

Read before this

1. Create and manage your ngram API key

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:

The response is the standard envelope:

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.

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

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.

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.

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.

Getting started FAQ

Where do I get an API key?

Every signed-in user can open Settings → API Keys, create a key, and copy it once. The full value is shown only at creation; rotate or revoke the credential from the same screen.

What does an ngram API key look like?

Every key starts with the prefix ngs_ and is sent as a bearer token: Authorization: Bearer ngs_… . It carries the same permissions as your account.

Is video creation synchronous?

No. Create returns a job with status processing and HTTP 202. Poll GET /api/v1/videos/{id} until status is completed or failed, or subscribe to a webhook so ngram calls you.

How do I know when a video is ready?

Either poll the video by id and watch progress climb to 100, or subscribe to the video.completed and video.failed events. Webhook deliveries are signed with X-Ngram-Signature.

What are the rate limits?

Up to three video jobs may be processing per account at once; further create calls return 429 until a slot frees up. Read-only endpoints follow the standard public-API limits.

Which languages can I use?

Any language that can make an HTTPS request. The API is plain REST with JSON bodies, so cURL, JavaScript, Python, Go, Ruby and the rest all work the same way.

Keep going

• API credentials — Create, copy, rotate, or revoke a self-service bearer credential in Settings.
• MCP server — Render videos from Claude, Cursor and other agents as tool calls.
• Zapier — Automate ngram across thousands of apps with no code.
• n8n — Build self-hosted workflows around the ngram render API.