---
title: "Create AI Clipping"
method: POST
path: "/v3/ai-clipping"
tags: ["AI Clipping"]
---

# Create AI Clipping

`POST /v3/ai-clipping`

Submit a source video and return a job id immediately. The job runs asynchronously and produces one or more short clips per the requested output_settings. Poll GET /v3/ai-clipping/{id} or subscribe to ai_clipping.success / ai_clipping.fail webhooks.

## Headers

- `Idempotency-Key` string

## Request body

- CreateAiClippingRequest — Request body for POST /v3/ai-clipping.
  - `video` union, required — Source video. Either a URL or an asset_id from POST /v1/asset.
    - AssetUrl — Asset input via publicly accessible HTTPS URL.
      - `type` 'url', required — Input type discriminator
      - `url` string, required — Publicly accessible HTTPS URL for the asset
    - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
      - `type` 'asset_id', required — Input type discriminator
      - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
  - `title` string, nullable — Title for the job. Defaults to the source video's title if omitted.
  - `input_language` string, nullable — ISO-639-1 source language code (e.g. 'en', 'es'). Omit for auto-detect.
  - `output_settings` HighlightOutputSettings — Configuration for the clips the job will produce. Public projection of the internal ``HighlightOutputSettings`` (heygen/temporal/workflow/model/instant_highlight.py:27), minus internal-only fields (``caption_config`` — internal StyleConfig from the frontend, not part of the public contract).
    - `duration_types` OutputDuration[] — One or more target clip durations to produce. Each produces a separate clip.
    - `aspect_ratio` 'landscape' | 'portrait' | 'square' — Output aspect ratio for produced clips.
    - `captions` boolean — Burn captions into the clips. Set false to disable.
    - `caption_style` 'subtle_gray' | 'shadow_mint' | 'subtle_cyan' | 'stamp_red' | 'retro_gold' | 'block_dark' | 'racing' | 'modern_dark' | 'modern_boxed' | 'chunky' | 'clean' | 'shadow_lime' | 'tag_yellow' | 'pop_purple' | 'spotlight' | 'outline_classic' | 'exotic' | 'golden' | 'simple' | 'pop_single' | 'energy' | 'bold' | 'elegant' | 'neon_pink' — Caption style presets. Must stay in sync with the worker preset registry (heygen/jobs/video_repurpose/caption_presets.py); enforced by test_external_api_dto.py::test_caption_style_enum_matches_preset_registry.
    - `prompt` string, nullable — Optional editorial guidance for the highlight model. Max 500 characters.
  - `callback_url` string, nullable — HTTPS URL to receive per-job webhook callbacks. Mirrors /v3/video-translations callback_url. Per-job callback_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret (the signature header is sent only to registered endpoints).
  - `callback_id` string, nullable — Opaque client identifier echoed verbatim in webhook payloads. Mirrors /v3/video-translations callback_id.

## Response `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CreateAiClippingResponse — Response for POST /v3/ai-clipping. Mirrors the v3 single-ID create shape.
    - `ai_clipping_id` string, required — Unique job identifier. Use with all other endpoints.

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed
- `409` — A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heygen/apis/heygen-external-api.md) · [All operations](https://skmtc.net/heygen/apis/heygen-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heygen/heygen-external-api/versions/e2e54726e210/schema)