---
title: "TypeScript SDK | MakeAIVideo"
description: "@makeaivideo/sdk wraps all 65 API operations in a typed client, with polling, webhook verification and typed errors handled for you."
canonical: https://makeaivideo.ai/docs/sdk
format: markdown
generator: makeaivideo-marketing build-time HTML→MD
---

[Documentation](/docs)v1.2

Guides

-   [Overview](/docs)
-   [Quickstart](/docs/quickstart)
-   [Authentication](/docs/authentication)
-   [Webhooks](/docs/webhooks)

Integrations

-   [MCP server](/docs/mcp)
-   [Agents](/docs/agents)
-   [CLI](/docs/cli)
-   [TypeScript SDK](/docs/sdk)

API reference

-   [All endpoints](/docs/api)
-   [Introspection](/docs/api/introspection)
-   [Videos](/docs/api/videos)
-   [Scripts](/docs/api/scripts)
-   [Characters](/docs/api/characters)
-   [Voices](/docs/api/voices)
-   [Music](/docs/api/music)
-   [Uploads](/docs/api/uploads)
-   [Brand kit](/docs/api/brand-kit)
-   [Workspace](/docs/api/workspace)
-   [Ideas](/docs/api/ideas)
-   [Publishing](/docs/api/publishing)
-   [Webhooks](/docs/api/webhooks)
-   [Auth](/docs/api/auth)

# TypeScript SDK

`@makeaivideo/sdk` is a typed client for all 65 API operations. It handles polling, webhook signature verification and error classes, so the common path is three calls rather than a fetch loop.

shellCopy

```
npm install @makeaivideo/sdk
```

Published on npm as [@makeaivideo/sdk](https://www.npmjs.com/package/@makeaivideo/sdk), source on [GitHub](https://github.com/makeaivideo-ai/sdk). MIT licensed. Create a key under [Developers](/developers) first.

## Brief in, MP4 out

The shortest useful path: list the tools, quote the cost, create, wait. Note the estimate step. It is free, and it turns an irreversible spend into one you can confirm.

typescriptCopy

```
import { MakeAIVideo } from "@makeaivideo/sdk"

const mav = new MakeAIVideo({ apiKey: process.env.MAKEAIVIDEO_API_KEY! })

// 1. See the video tools and the fields each one asks for
const tools = await mav.tools.list()

// 2. Quote the cost, then create
const quote = await mav.videos.estimate({ tool: "explainer", duration_seconds: 30 })
const { video_id } = await mav.videos.create({
  tool: "explainer",
  fields: { topic: "Why octopuses have three hearts" },
  duration_seconds: 30,
  aspect_ratio: "9:16",
})

// 3. Wait for the render and download it
const video = await mav.videos.waitForReady(video_id, {
  onProgress: (v) => console.log(v.status),
})
console.log(video.download) // MP4 URL
```

`waitForReady` polls for you and respects the `poll_after_seconds` hint the API returns, so it will not hammer the endpoint. If you would rather not hold a connection open, use webhooks instead.

## Webhooks instead of polling

typescriptCopy

```
import { verifyWebhookSignature } from "@makeaivideo/sdk"

const hook = await mav.webhooks.create({
  url: "https://example.com/hooks/makeaivideo",
  events: ["video.ready", "video.failed"],
})

// store hook.secret, then in your handler (raw body!):
if (!verifyWebhookSignature(rawBody, req.headers["x-makeaivideo-signature"], secret)) {
  throw new Error("bad signature")
}
```

Verify against the **raw** body, before any JSON parsing, or the signature will not match. The [webhooks guide](/docs/webhooks) covers the event list and the retry schedule.

## What the client exposes

Every resource hangs off the client, plus `mav.me()` and `mav.credits()` for the account itself. Both are free to call.

Resource

Covers

mav.videos

Create, estimate, poll, export, download

mav.tools

The brief-driven video tools and their fields

mav.templates

Saved render configurations

mav.characters

Recurring on-screen people

mav.voices

The voice catalogue and previews

mav.music

Background track generation

mav.ideas

Topic and hook suggestions

mav.ai

Script writing, prompt enhancement, article fetch

mav.uploads

Your own images and audio

mav.brandKit

Colours, logo and type

mav.publishing

Post finished videos to connected social accounts, now or scheduled

mav.webhooks

Delivery endpoints and their health

mav.workspace

Members and settings

## Errors

Every failure is a `MakeAIVideoError` carrying `status`, `code` and `requestId`. Quote the request id in any support mail and we can find the exact call. The subclasses let you branch without string matching:

Class

Status

Meaning

AuthenticationError

401

Key missing, malformed or revoked

PermissionError

403

The key lacks the required scope

ValidationError

400

The request body did not validate

InsufficientCreditsError

402

Not enough credits for the job

NotFoundError

404

No such video, voice or character

RateLimitError

429

A rate-limit tier was exceeded

VideoFailedError

\-

The render failed while waiting on it

## The other packages

[@makeaivideo/mcp](https://www.npmjs.com/package/@makeaivideo/mcp) runs the [MCP server](/docs/mcp) locally over stdio, for assistants that cannot reach the hosted endpoint. [@makeaivideo/cli](https://www.npmjs.com/package/@makeaivideo/cli) is the [command-line client](/docs/cli). All three are MIT licensed and open source under [github.com/makeaivideo-ai](https://github.com/makeaivideo-ai), and all three are included on every plan with no separate rate card.

For the endpoints underneath, see the [API reference](/docs/api), or start with the [quickstart](/docs/quickstart) if you would rather use plain HTTP.

Get an API key

The API and MCP server use the same credits and the same balance as the app, with no separate API plan. Create a key under Settings, Advanced, API keys.

[Start 7 day free trial](https://app.makeaivideo.ai/signup?utm_source=docs&utm_medium=docs_cta&utm_content=%2Fdocs%2Fsdk)[MakeAIVideo plans and pricing](/pricing)

7-day free trial with 350 credits, then plans from $9/mo. Cancel anytime before the trial ends.
