MakeAIVideo
Start free trial

API reference

Videos API

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

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

What the videos endpoints are for

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.

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
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.

Related

  • Quickstart — the create, poll and download loop end to end.
  • Authentication — what the read, write scope on this page mean.
  • Agents — calling these endpoints from an autonomous agent.
← Introspection APIScripts API →