---
title: "MakeAIVideo Videos API Reference: Create, Edit, Export"
description: "The video endpoints of the MakeAIVideo API: create from a brief or your own script, poll a render, regenerate scenes, and export or download the MP4."
canonical: https://makeaivideo.ai/docs/api/videos
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)

API reference

# MakeAIVideo Videos API

Create, inspect, edit, regenerate, export and download videos.

22 operations · https://app.makeaivideo.ai/api/v1

## When to use the Videos API

The core of the API. Create a video from a brief we script for you or from a script you supply, watch the render, change parts of it, and export the result.

Creation is asynchronous. POST /videos returns 202 with a video id while the render continues in the background, so a client either polls GET /videos/{id} at the interval the response asks for, or subscribes to a webhook and stops polling entirely.

The editing endpoints are the reason to use the API over a one-shot generator. A finished video is not final: you can regenerate a single scene without re-rendering the rest, swap the voiceover for a different voice, edit the script or caption settings, and export again. Re-running one scene costs a fraction of what re-running the whole video does.

-   [GET`/videos`](/docs/api/videos/list-videos)
-   [POST`/videos`](/docs/api/videos/create-video)
-   [POST`/videos/estimate`](/docs/api/videos/estimate-video)
-   [GET`/videos/{id}`](/docs/api/videos/get-video)
-   [PATCH`/videos/{id}`](/docs/api/videos/update-video)
-   [DELETE`/videos/{id}`](/docs/api/videos/delete-video)
-   [POST`/videos/{id}/generate`](/docs/api/videos/generate-video)
-   [POST`/videos/{id}/cancel`](/docs/api/videos/cancel-video)
-   [GET`/videos/{id}/download`](/docs/api/videos/download-video)
-   [GET`/videos/{id}/renders`](/docs/api/videos/list-renders)
-   [POST`/videos/{id}/renders`](/docs/api/videos/create-render)
-   [GET`/videos/{id}/renders/progress`](/docs/api/videos/render-progress)
-   [POST`/videos/{id}/scenes/{n}/regenerate`](/docs/api/videos/regenerate-scene)
-   [GET`/videos/{id}/voice`](/docs/api/videos/voice-progress)
-   [POST`/videos/{id}/voice`](/docs/api/videos/regenerate-voice)
-   [GET`/videos/{id}/captions`](/docs/api/videos/get-captions)
-   [POST`/videos/{id}/share-link`](/docs/api/videos/create-share-link)
-   [POST`/videos/{id}/report`](/docs/api/videos/report-video)
-   [POST`/videos/image-to-video`](/docs/api/videos/create-image-to-video)
-   [POST`/videos/talking-avatar`](/docs/api/videos/create-talking-avatar)
-   [POST`/videos/character-swap`](/docs/api/videos/create-character-swap)
-   [GET`/templates`](/docs/api/videos/list-templates)

GET`/videos`read

### List videos

GET https://app.makeaivideo.ai/api/v1/videos

#### Responses

-   `200`Videos`VideoList`

POST`/videos`write

### Create a video from a brief or your own script

POST https://app.makeaivideo.ai/api/v1/videos

#### Request body CreateVideorequired

Field

Type

Description

tool

string

Path A: a tool id from GET /tools; we write the script

fields

object

—

duration\_seconds

integer

—

script

object

Path B: your own script (from /videos/script, /videos/scriptify, or hand-written)

title

string

—

topic

string

—

mode

"talking-head" | "cinematic" | "hybrid" | "stock-narrated" | "smart-mix"

—

style

"talking-head" | "cinematic"

—

character\_id

integer | null

—

voice\_id

string

—

music\_id

string

—

caption\_style

string

—

aspect\_ratio

"9:16" | "1:1" | "16:9"

—

language

string

—

start\_generation

boolean

—

idempotency\_key

string

Same key = same video. Set it when retrying.

video\_model

string

Optional. Leave it unset and MakeAIVideo picks the best video model for each scene.

#### Responses

-   `202`Accepted. status is \`generating\`, or \`draft\` when start\_generation is false`VideoCreated`
-   `400`Invalid brief or script`ErrorEnvelope`
-   `402`Not enough credits or no active subscription`ErrorEnvelope`
-   `403`Key lacks the write scope`ErrorEnvelope`
-   `429`Rate or spend limit reached; see Retry-After`ErrorEnvelope`

POST`/videos/estimate`read

### Free credit quote

POST https://app.makeaivideo.ai/api/v1/videos/estimate

#### Responses

-   `200`Quote

GET`/videos/{id}`read

### Video status and progress

GET https://app.makeaivideo.ai/api/v1/videos/{id}

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Status`Video`
-   `404`Unknown video`ErrorEnvelope`

PATCH`/videos/{id}`write

### Edit title, topic, script or caption settings

PATCH https://app.makeaivideo.ai/api/v1/videos/{id}

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Saved. Script changes apply on the next generate
-   `404`Unknown video`ErrorEnvelope`

DELETE`/videos/{id}`write

### Delete a video and its files

DELETE https://app.makeaivideo.ai/api/v1/videos/{id}

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Deleted
-   `404`Unknown video`ErrorEnvelope`

POST`/videos/{id}/generate`write

### Start or re-run generation (drafts, or after edits)

POST https://app.makeaivideo.ai/api/v1/videos/{id}/generate

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `202`Accepted
-   `409`Already generating`ErrorEnvelope`

POST`/videos/{id}/cancel`write

### Cancel a running render and release its credits

POST https://app.makeaivideo.ai/api/v1/videos/{id}/cancel

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Cancelled
-   `409`Not running`ErrorEnvelope`

GET`/videos/{id}/download`read

### Signed download URL for the finished MP4

GET https://app.makeaivideo.ai/api/v1/videos/{id}/download

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`URL valid 15 minutes
-   `404`Unknown video`ErrorEnvelope`
-   `409`Not ready yet (retryable)`ErrorEnvelope`

GET`/videos/{id}/renders`read

### Past exports

GET https://app.makeaivideo.ai/api/v1/videos/{id}/renders

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Renders

POST`/videos/{id}/renders`write

### Export again (after edits)

POST https://app.makeaivideo.ai/api/v1/videos/{id}/renders

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `202`Accepted

GET`/videos/{id}/renders/progress`read

### Current export progress

GET https://app.makeaivideo.ai/api/v1/videos/{id}/renders/progress

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Progress

POST`/videos/{id}/scenes/{n}/regenerate`write

### Regenerate one scene (optionally with new narration)

POST https://app.makeaivideo.ai/api/v1/videos/{id}/scenes/{n}/regenerate

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

nrequired

path

integer

Scene number, 1-based

#### Responses

-   `202`Accepted

GET`/videos/{id}/voice`read

### Voice regeneration progress

GET https://app.makeaivideo.ai/api/v1/videos/{id}/voice

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Progress

POST`/videos/{id}/voice`write

### Regenerate the voiceover with another voice

POST https://app.makeaivideo.ai/api/v1/videos/{id}/voice

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `202`Accepted

GET`/videos/{id}/captions`read

### Caption file (SRT or VTT), returned as text

GET https://app.makeaivideo.ai/api/v1/videos/{id}/captions

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

format

query

"srt" | "vtt"

—

#### Responses

-   `200`Caption file
-   `400`No caption data yet`ErrorEnvelope`

POST`/videos/{id}/share-link`write

### Public, expiring link to the MP4 for people without an account

POST https://app.makeaivideo.ai/api/v1/videos/{id}/share-link

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Link

POST`/videos/{id}/report`write

### Flag a generated video for review

POST https://app.makeaivideo.ai/api/v1/videos/{id}/report

#### Parameters

Name

In

Type

Description

idrequired

path

string

Public video id, e.g. vid\_abc123

#### Responses

-   `200`Reported

POST`/videos/image-to-video`ai

### Animate one image into a 5 or 10 s clip; optional narration makes the subject speak it (voice + lip-sync)

POST https://app.makeaivideo.ai/api/v1/videos/image-to-video

#### Responses

-   `202`Accepted`VideoCreated`
-   `402`Not enough credits`ErrorEnvelope`

POST`/videos/talking-avatar`ai

### Your own filmed video speaks a new script (voice + lip-sync onto your clip). For an AI presenter use POST /videos with mode talking-head

POST https://app.makeaivideo.ai/api/v1/videos/talking-avatar

#### Responses

-   `202`Accepted`VideoCreated`
-   `402`Not enough credits`ErrorEnvelope`

POST`/videos/character-swap`ai

### Character Swap: the person in your video becomes a character or the person in your photos. Motion, camera, room and the original audio are kept; lips stay in sync. 3-60 s

POST https://app.makeaivideo.ai/api/v1/videos/character-swap

#### Responses

-   `202`Accepted`VideoCreated`
-   `402`Not enough credits`ErrorEnvelope`

GET`/templates`read

### Template library

GET https://app.makeaivideo.ai/api/v1/templates

#### Responses

-   `200`Templates

## Videos API questions

How long does an API video render take?

Minutes, not seconds. POST /videos returns immediately with a video id and a poll\_after\_seconds hint; treat the render as a background job rather than something to block a request on.

Can I regenerate one scene instead of the whole video?

Yes. POST /videos/{id}/scenes/{n}/regenerate re-renders a single scene, optionally with new narration, leaving every other scene untouched. It is the cheapest way to fix one bad shot.

How do I avoid being charged twice for a retried request?

Send an idempotency\_key on POST /videos. Without one, a retry after a dropped connection creates and charges for a second video, because the server cannot tell a retry from a new request.

How do I download the finished MP4?

GET /videos/{id}/download returns a signed download URL. Captions come separately from GET /videos/{id}/captions as an SRT or VTT file rather than JSON.

Can I cancel a render that is already running?

Yes. POST /videos/{id}/cancel stops a running render and releases the credits it had reserved.

## MakeAIVideo API guides

-   [Quickstart](/docs/quickstart) — the create, poll and download loop end to end.
-   [Authentication](/docs/authentication) — what the read, write, ai scope on this page mean.
-   [Agents](/docs/agents) — calling these endpoints from an autonomous agent.

## More MakeAIVideo documentation

In the product

-   [Prompt to video](/prompt-to-video): create from a brief
-   [Script to video](/script-to-video): create from your own script
-   [Instagram Reels generator](/instagram-reels-generator): one of the formats these endpoints render
-   [AI Shorts generator](/ai-shorts-generator): vertical short-form
-   [MakeAIVideo pricing](/pricing): what a render costs
-   [AI video generator](/): every create mode in the app, no code

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%2Fapi%2Fvideos)[MakeAIVideo plans and pricing](/pricing)

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

[← Introspection API](/docs/api/introspection)[Scripts API →](/docs/api/scripts)
