Skip to main content

Create a Clip Job

  • Endpoint: POST /v3/ai-clipping
  • Purpose: Start a clipping job for a source video. Returns an ai_clipping_id to poll.
video takes a public HTTPS URL or an asset_id from POST /v3/assets (see Upload Assets). input_language (ISO-639-1, e.g. en) auto-detects when omitted, and title defaults to the source video’s title. The create reference has the full schema.

Output settings

  • duration_types: 1–4 target durations from "30", "60", "180" and "long". Each duration produces a separate clip.
  • aspect_ratio: portrait (9:16, the default), landscape (16:9) or square (1:1), applied to every clip.
  • captions: burned in by default (true). Set false for clean, caption-free footage. caption_style picks a named preset such as classic or bold.
  • prompt: editorial guidance for the highlight model, such as which speaker or what topics (max 500 chars). Without it, the model selects highlights on its own.
Want captions on some clips and clean footage on others? Captions are a per-job setting, so submit two jobs from the same source video, one with "captions": false, and pick per platform. To style burned-in captions on other footage, caption_style presets like classic and bold keep the look consistent.

Get a Clip Job

GET /v3/ai-clipping/{job_id} returns the job’s live status and progress (0–100), and its clips array populates as each clip renders, empty until the first one finishes. Job status moves pending → running → completed | failed (or cancelled); each clip has its own status plus a model-generated title, duration_seconds, a virality_score (0–100), and pre-signed thumbnail_url and video_url (MP4). On failure, read failure_message.
Each video_url and thumbnail_url is a pre-signed link with a limited lifetime. Download the file (or hand the URL to a downstream step) soon after the job completes rather than caching it for later.
For long recordings, prefer a callback_url over tight polling: HeyGen will POST you the finished job instead (ai_clipping.success / ai_clipping.fail webhook events), echoing your callback_id.

List and Delete

GET /v3/ai-clipping lists jobs with limit (default 10) and a token cursor from next_token. It reports coarse progress; poll Get a Clip Job for live in-flight progress on a specific job. DELETE /v3/ai-clipping/{job_id} permanently deletes a clip job and its clips. Pairing clips with audio? The same Tools suite covers background music and sound effects to score your cuts.