Skip to main content
POST
/
v3
/
ai-clipping
Create AI Clipping
curl --request POST \
  --url https://api.heygen.com/v3/ai-clipping \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "video": {
    "type": "<string>",
    "url": "<string>"
  },
  "title": "<string>",
  "input_language": "<string>",
  "output_settings": {
    "duration_types": [],
    "aspect_ratio": "portrait",
    "captions": true,
    "caption_style": "<string>",
    "prompt": "<string>"
  }
}
'
{
  "data": {
    "ai_clipping_id": "<string>"
  }
}

Authorizations

​
x-api-key
string
header
required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

​
Idempotency-Key
string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Required string length: 1 - 255
Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

Request body for POST /v3/ai-clipping.

​
video
AssetUrl · object
required

Asset input via publicly accessible HTTPS URL.

​
title
string | null

Title for the job. Defaults to the source video's title if omitted.

Maximum string length: 255
​
input_language
string | null

ISO-639-1 source language code (e.g. 'en', 'es'). Omit for auto-detect.

​
output_settings
HighlightOutputSettings · object

Configuration for the produced clips (duration mix, aspect ratio, captions, etc.).

Response

Accepted — submission acknowledged; poll for completion.

​
data
CreateAiClippingResponse · object

Response for POST /v3/ai-clipping. Mirrors the v3 single-ID create shape.