MakeAIVideo
Start trial

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/videosread

List videos

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

Responses

  • 200VideosVideoList
POST/videoswrite

Create a video from a brief or your own script

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

Request body CreateVideorequired

FieldTypeDescription
toolstringPath A: a tool id from GET /tools; we write the script
fieldsobject—
duration_secondsinteger—
scriptobjectPath B: your own script (from /videos/script, /videos/scriptify, or hand-written)
titlestring—
topicstring—
mode"talking-head" | "cinematic" | "hybrid" | "stock-narrated" | "smart-mix"—
style"talking-head" | "cinematic"—
character_idinteger | null—
voice_idstring—
music_idstring—
caption_stylestring—
aspect_ratio"9:16" | "1:1" | "16:9"—
languagestring—
start_generationboolean—
idempotency_keystringSame key = same video. Set it when retrying.
video_modelstringOptional. Leave it unset and MakeAIVideo picks the best video model for each scene.

Responses

  • 202Accepted. status is `generating`, or `draft` when start_generation is falseVideoCreated
  • 400Invalid brief or scriptErrorEnvelope
  • 402Not enough credits or no active subscriptionErrorEnvelope
  • 403Key lacks the write scopeErrorEnvelope
  • 429Rate or spend limit reached; see Retry-AfterErrorEnvelope
POST/videos/estimateread

Free credit quote

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

Responses

  • 200Quote
GET/videos/{id}read

Video status and progress

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200StatusVideo
  • 404Unknown videoErrorEnvelope
PATCH/videos/{id}write

Edit title, topic, script or caption settings

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200Saved. Script changes apply on the next generate
  • 404Unknown videoErrorEnvelope
DELETE/videos/{id}write

Delete a video and its files

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200Deleted
  • 404Unknown videoErrorEnvelope
POST/videos/{id}/generatewrite

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

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 202Accepted
  • 409Already generatingErrorEnvelope
POST/videos/{id}/cancelwrite

Cancel a running render and release its credits

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200Cancelled
  • 409Not runningErrorEnvelope
GET/videos/{id}/downloadread

Signed download URL for the finished MP4

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200URL valid 15 minutes
  • 404Unknown videoErrorEnvelope
  • 409Not ready yet (retryable)ErrorEnvelope
GET/videos/{id}/rendersread

Past exports

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200Renders
POST/videos/{id}/renderswrite

Export again (after edits)

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 202Accepted
GET/videos/{id}/renders/progressread

Current export progress

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200Progress
POST/videos/{id}/scenes/{n}/regeneratewrite

Regenerate one scene (optionally with new narration)

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123
nrequiredpathintegerScene number, 1-based

Responses

  • 202Accepted
GET/videos/{id}/voiceread

Voice regeneration progress

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200Progress
POST/videos/{id}/voicewrite

Regenerate the voiceover with another voice

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 202Accepted
GET/videos/{id}/captionsread

Caption file (SRT or VTT), returned as text

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123
formatquery"srt" | "vtt"—

Responses

  • 200Caption file
  • 400No caption data yetErrorEnvelope
POST/videos/{id}/share-linkwrite

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

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200Link
POST/videos/{id}/reportwrite

Flag a generated video for review

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

Parameters

NameInTypeDescription
idrequiredpathstringPublic video id, e.g. vid_abc123

Responses

  • 200Reported
POST/videos/image-to-videoai

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

  • 202AcceptedVideoCreated
  • 402Not enough creditsErrorEnvelope
POST/videos/talking-avatarai

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

  • 202AcceptedVideoCreated
  • 402Not enough creditsErrorEnvelope
POST/videos/character-swapai

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

  • 202AcceptedVideoCreated
  • 402Not enough creditsErrorEnvelope
GET/templatesread

Template library

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

Responses

  • 200Templates

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 — the create, poll and download loop end to end.
  • Authentication — what the read, write, ai scope on this page mean.
  • Agents — calling these endpoints from an autonomous agent.

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 trialMakeAIVideo plans and pricing

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

← Introspection APIScripts API →