Clips

When a clip_generation job completes, the platform stores a ClipGeneration record with timing, transcript text, and per-segment metadata for each rendered clip. MP4 files are not stored on Perchat — the worker uploads renders to your S3 bucket using a saved storage connection.

Create jobs via POST /v1/jobs (serviceType: clip_generation). Poll the job until status: completed, then fetch clip metadata with the endpoints below. Plan-specific clip limits and supported client options are published via GET /v1/jobs/policy (serviceType=clip_generation).

Endpoints

The ClipGeneration object

clipGenerationIdstring
Unique identifier (clp_…).
jobIdstring
Source clip_generation job.
workspaceIdstring
Owning workspace.
projectIdstring
Project scope.
displayNamestring
Human label derived from the job (customer ref or source basename).
sourceDurationSecnumber | null
Duration of the source video in seconds.
clipCountnumber
Number of clips in clips[].
categorystring | null
Detected or client-overridden content category (for example interview, podcast, gaming).
categoryConfidencenumber | null
Confidence score for auto-detected category; null when category was overridden.
layoutstring | null
Resolved output layout for all rendered clips (vertical_9_16, horizontal_in_vertical, horizontal_16_9, or square_1_1).
transcriptPreviewstring
Short preview from the first clip transcript.
clipsarray
Per-clip metadata. Each item includes startSec, endSec, durationSec, transcript, segments[] (each with optional segmentId linking back to the source transcript), optional title / score, and outputKey (S3 object key on your bucket).
createdAttimestamp
When the record was created.
updatedAttimestamp
Last update time.

List clips

GET/v1/clip-generations
Paginated clips records for the project. Optional filter by jobId.

Requires permission

transcript:list

Parameters

pageinteger, optional
Page number (default 1).
limitinteger, optional
Page size (default 20, max 100).
jobIdstring, optional
Filter to one clip_generation job.

Returns

Returns an array of ClipGeneration list items (same shape as retrieve).

See the the clipgeneration object for attribute details.

Retrieve clips

GET/v1/clip-generations/{clipGenerationId}
Returns one ClipGeneration with full clips[] metadata.

Requires permission

transcript:read

Example clip item:
{
      "clipId": "clip_01",
      "candidateId": "clip_01",
      "startSec": 12.4,
      "endSec": 42.8,
      "durationSec": 30.4,
      "transcript": "This is the moment everyone remembers…",
      "segments": [
        {
      "startSec": 12.4,
      "endSec": 18.1,
      "text": "This is the moment everyone remembers.",
      "segmentId": "seg_42"
    }
      ],
      "title": "The hook",
      "reason": "High energy opening with clear payoff",
      "score": 0.91,
      "outputKey": "perchat-media-results/txt_01HX2K9V3JEK4WYZN6F0XQ2W8M/clips/clip_01.mp4"
    }

Parameters

clipGenerationIdstring
Clips record identifier (clp_…).

Returns

Returns a ClipGeneration object.

See the the clipgeneration object for attribute details.