Make a short presenter video from a topic with the API

POST /v3/mascot/api turns a topic into a finished short video: script, AI presenter, voice, lip-sync, captions and music, delivered as one video URL.

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.

Method	Path	What it does
POST	/v3/mascot/api	Start a short video
GET	/v3/mascot/api/{jobId}	Read the job
POST	/v3/mascot/api/{jobId}/reedit	Re-cut a finished job with another edit, without a new lip-sync
GET	/v3/mascot/api/options	Voices, presenter presets and script categories

Start a video

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

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

gender · string · default: "man"

Presenter: man or woman.

preset · string · default: "creator"

Presenter look: creator, newscaster or pixar. Other values fall back to creator.

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

flow · string

Force an edit style, such as classic, reveal, hook-reveal, broll-punch, clean-punch or karaoke. Leave it out for the default edit.

captions · boolean · default: "true"

Apply the edit and burned-in captions.

music · boolean · default: "true"

Add a background music bed.

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

webhook · string

https URL that receives { jobId, status, videoUrl, creditsSpent } when the job is done, or { jobId, status, error } if it fails. See Webhooks.

cURL

curl -s -X POST https://api.percify.io/v3/mascot/api \
  -H "Authorization: Bearer $PERCIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Why short onboarding videos beat long help articles",
    "seconds": 40,
    "gender": "woman",
    "preset": "creator",
    "idempotencyKey": "onboarding-short-001"
  }'

201 Response

{ "success": true, "data": { "jobId": "7a1e4c2b-0d9f-4b8e-a3c5-5f2e9d1b6a70", "status": "scripting" } }

Read a job

GET /v3/mascot/api/{jobId}

data.status · string

scripting, portrait, animating, captioning, then done or failed. stage repeats it.

data.progress · number | null

From 0 to 1 as the stages advance.

data.script · string | null

The script the presenter speaks.

data.portraitUrl · string | null

The presenter image, available during the job.

data.rawVideoUrl · string | null

The lip-synced talking video before editing.

data.videoUrl · string | null

The finished, edited video.

data.creditsSpent · integer | null

Credits the job used.

data.applied · object | null

What the edit delivered: captions, broll, images, music and loudnorm, plus skipped, which names any step that fell back and why.

data.degraded · 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

Status	Message	Cause
400	Invalid jobId	The id is not a UUID.
400	webhook must use https and similar	Fix the webhook URL.
404	Job not found	The job does not belong to your account.

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.

Related

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.