Create a Clip Job
- Endpoint:
POST /v3/ai-clipping - Purpose: Start a clipping job for a source video. Returns an
ai_clipping_idto 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) orsquare(1:1), applied to every clip.captions: burned in by default (true). Setfalsefor clean, caption-free footage.caption_stylepicks a named preset such asclassicorbold.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.
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.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.
