Skip to main content
POST https://api.percify.io/v3/mascot/api makes a complete short video from one request: Percify writes a spoken script from your topic, generates a presenter image and voice, lip-syncs them, then adds captions, b-roll and a music bed. It returns a jobId at once; poll GET /v3/mascot/api/{jobId} until status is done and read videoUrl. The job is charged as the generations it runs and fully refunded if it fails. The same pipeline is the make_video tool on the MCP server.

Start a video

string
What the video is about. Long topics are cut at a sentence boundary around 900 characters. Leave it out and Percify picks an angle itself.
number
default:"45"
Target length from 20 to 180 seconds. It steers the script; the final length is however long the script takes to say.
string
default:"man"
Presenter: man or woman.
string
default:"creator"
Presenter look: creator, newscaster or pixar. Other values fall back to creator.
string
A voice name for the chosen gender from GET /v3/mascot/api/options. Defaults are Archer for man and Lucy for woman; a name that does not match the gender uses the default.
string
Force an edit style, such as classic, reveal, hook-reveal, broll-punch, clean-punch or karaoke. Leave it out for the default edit.
boolean
default:"true"
Apply the edit and burned-in captions.
boolean
default:"true"
Add a background music bed.
string
Send the same value on retries to get the original job back instead of starting and paying for another. On this endpoint it goes in the body, not a header.
string
https URL that receives { jobId, status, videoUrl, creditsSpent } when the job is done, or { jobId, status, error } if it fails. See Webhooks.
201 Response

Read a job

GET /v3/mascot/api/{jobId}
string
scripting, portrait, animating, captioning, then done or failed. stage repeats it.
number | null
From 0 to 1 as the stages advance.
string | null
The script the presenter speaks.
string | null
The presenter image, available during the job.
string | null
The lip-synced talking video before editing.
string | null
The finished, edited video.
integer | null
Credits the job used.
object | null
What the edit delivered: captions, broll, images, music and loudnorm, plus skipped, which names any step that fell back and why.
boolean | null
true when a step was skipped, so the video is plainer than requested.
The object also has jobId, flow, topic, voice, seconds, posterUrl, error, createdAt and updatedAt.
done means the pipeline reached the end. If captions, b-roll, images or music fail, the job still finishes with a plainer video. Check degraded and applied before you publish it as fully edited.

Re-cut a finished video

POST /v3/mascot/api/{jobId}/reedit takes flow, captions and music, reuses the job’s script, voice and lip-sync, and returns a new jobId to poll the same way. It only works on your own jobs that already have a lip-sync.

Errors

A job that runs out of credits partway fails with status: "failed"; the error says how many credits it needed, and the credits it used are refunded.

Async jobs and polling

Statuses for every job type.

Talking avatar pipeline

Build your own presenter video step by step.

MCP server

make_video, reedit_video and get_mascot for agents.

Webhooks

Get the finished video pushed to you.
Last modified on September 16, 2026