# Get started with the ngram API

Source: https://www.ngram.com/docs/getting-started
Published: 2026-07-07T00:00:00Z
Updated: 2026-10-21T00:00:00Z

Create a self-service API key, authenticate with a bearer token, start a video job, poll the result, verify webhooks, and handle limits.

Getting started

Create a bearer key in Settings, check your credits, and start a video job from any language that speaks HTTP.

[Review API access](https://www.ngram.com/docs/api/public-api-v1) [All docs](https://www.ngram.com/docs)

## Read before this

Read these direct prerequisites in order. Each guide lists any earlier context it assumes.

1. [1 API keys Create, copy, rotate, and revoke a self-service API key in Settings.](https://www.ngram.com/docs/api/public-api-v1)

## 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. Video creation with an API key requires Basic or a higher paid plan and enough credits. Creating a key is self-service, but a key alone does not make a Free account eligible to generate videos through the API.

1. Open [Settings → API keys](https://www.ngram.com/app/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" }
}
```

## Check your credits

Video creation with an API key requires Basic or a higher paid plan and enough credits. Creating a key is self-service, but a key alone does not make a Free account eligible to generate videos through the API. Base generation rates are 3 credits per second for ngram-flash and 10 for premium video models. Check the account balance and selected settings before starting a job. Add credits for a balance shortfall; a top-up does not unlock paid-plan access.

## 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](https://www.ngram.com/docs/mcp)  — let Claude, Cursor and other agents render videos as tool calls.
- [Zapier](https://www.ngram.com/docs/zapier)  — wire ngram into thousands of apps with no code.
- [n8n](https://www.ngram.com/docs/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.

### Can I create videos through the API on Free?

API-key video creation requires Basic or higher and enough credits. Supported connected-app sign-in, GitHub, and Notion have separate Free access paths; see the integrations guide for their model and delivery limits.

### 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.](https://www.ngram.com/docs/api/public-api-v1) [MCP server Render videos from Claude, Cursor and other agents as tool calls.](https://www.ngram.com/docs/mcp) [Zapier Automate ngram across thousands of apps with no code.](https://www.ngram.com/docs/zapier) [n8n Build self-hosted workflows around the ngram render API.](https://www.ngram.com/docs/n8n)

## Continue in ngram

Open the workspace and put this guide into practice with your own project.

[Open ngram](https://www.ngram.com/app)