MakeAIVideo API quickstart

1. Get an API key

Create one in the app under Settings, Advanced, API keys. Keys start with mav_ and carry scopes. Give this one read, write and ai so it can run the whole loop. See Authentication for what each scope covers.

export MAV_API_KEY="mav_..."

2. See what you can make

Each tool is a video shape with its own fields. Pick an id from the response and use it in the next two calls.

curl https://app.makeaivideo.ai/api/v1/tools \
  -H "Authorization: Bearer $MAV_API_KEY"

3. Quote it first

Estimating is free and tells you the credit cost before you commit.

curl -X POST https://app.makeaivideo.ai/api/v1/videos/estimate \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "<tool id from GET /tools>",
    "duration_seconds": 30
  }'

4. Create the video

Two paths into this endpoint. Pass a tool plus fields and we write the script, or pass your own script object and we render exactly that.

curl -X POST https://app.makeaivideo.ai/api/v1/videos \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "<tool id from GET /tools>",
    "fields": { "topic": "How compound interest works" },
    "duration_seconds": 30,
    "idempotency_key": "quickstart-001"
  }'

Returns 202 Accepted. The render has started; it has not finished.

{
  "data": {
    "video_id": "vid_...",
    "status": "generating",
    "poll_after_seconds": <integer, read it from the response>,
    "next": "..."
  },
  "error": null,
  "meta": { ... }
}

The idempotency_key matters. Renders cost credits, and without a key a retried request creates and charges for a second video.

5. Wait for it

Renders take minutes. Poll the video and respect poll_after_seconds rather than hammering the endpoint.

curl https://app.makeaivideo.ai/api/v1/videos/vid_... \
  -H "Authorization: Bearer $MAV_API_KEY"

For anything long-running, prefer a webhook over polling: subscribe to video.ready and let us call you. See Webhooks.

6. Download the MP4

curl -L https://app.makeaivideo.ai/api/v1/videos/vid_.../download \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -o video.mp4

Quickstart questions

How do I make my first video with the API?

List the tools, estimate the cost, POST to /videos with a tool and fields, poll until it is ready, then download the MP4. That is the whole loop and it is five calls.

Do I have to write the script myself?

No. Pass a tool and a few brief fields and we write the script for you. If you would rather control the words, pass your own script object instead and we render exactly that.

How do I know when the video is finished?

Poll GET /videos/{id} at the interval the create response returns, or subscribe to the video.ready webhook and skip polling altogether. Webhooks are the better choice for anything unattended.

More MakeAIVideo documentation