---
title: "List AI Clipping"
method: GET
path: "/v3/ai-clipping"
tags: ["AI Clipping"]
---

# List AI Clipping

`GET /v3/ai-clipping`

Returns a cursor-paginated list of AI clip jobs in the authenticated user's workspace, newest first.

## Query parameters

- `limit` integer
- `token` string

## Response `200`

Successful response

- object
  - `data` AiClippingDetail[]
    - `id` string, required — Unique job identifier.
    - `title` string, nullable — Display title.
    - `status` 'pending' | 'running' | 'completed' | 'failed' | 'cancelled', required — Public job lifecycle. Mirrors the v3 video-translation status set plus a ``cancelled`` terminal state.
    - `input_language` string, nullable — Detected or supplied source language code.
    - `source_duration` number, nullable — Duration of the source video in seconds.
    - `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.
    - `clips` Clip[] — Produced clips. Empty until the job's first clip is rendered.
      - `id` string, required — Unique clip identifier.
      - `status` 'pending' | 'completed' | 'failed', required — Per-clip lifecycle. A job can produce N clips, each completing separately.
      - `duration_seconds` number, nullable — Final clip duration in seconds. Null until status=completed.
      - `aspect_ratio` 'landscape' | 'portrait' | 'square' — Output aspect ratio for produced clips.
      - `title` string, nullable — Model-generated clip title.
      - `virality_score` integer, nullable — Model-predicted virality score (0-100). Null until status=completed.
      - `thumbnail_url` string, nullable — Presigned thumbnail URL. Null until status=completed.
      - `video_url` string, nullable — Presigned MP4 download URL. Null until status=completed.
      - `failure_message` string, nullable — Reserved for future per-clip error surfacing. Currently always null; no per-clip failure reason is persisted.
    - `progress` integer — Approximate progress (0-100). 100 when all clips completed. GET /v3/ai-clipping/{id} returns live in-flight progress; the list endpoint reports a coarse value (0 until completed, then 100) to avoid a per-row status query, so poll the single-get endpoint for granular progress.
    - `callback_id` string, nullable — Client-provided callback ID.
    - `created_at` integer, nullable — Unix timestamp (seconds) of job creation.
    - `failure_message` string, nullable — Error description. Only present when status=failed.
  - `has_more` boolean — Whether more pages are available
  - `next_token` string, nullable — Opaque cursor for the next page

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed
- `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)