---
title: "Generate clips"
method: POST
path: "/api/v1/projects/{projectId}/clips"
tags: ["Jobs"]
---

# Generate clips

`POST /api/v1/projects/{projectId}/clips`

## Request

- Base URL: `https://prismclip.com`
- URL: `https://prismclip.com/api/v1/projects/{projectId}/clips`
- Auth: HTTP bearer

Complete clipping workflow for an owned recording. PrismClip prepares transcripts and visual scenes, selects up to count clips matching instruction, prepares framing, captions and cloud renders internally. Set render=false to review candidate moment sets first. Poll get_workflow for progress, candidates and authenticated media URLs. Stable Idempotency-Key prevents duplicate workflows.

## Path parameters

- `projectId` string, uuid, required

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `instruction` string, required: Requested topics, answers, scenes, or editorial preferences; empty selects general highlights
  - `evidence_mode` 'speech' | 'visual' | 'mixed', required: Speech uses the transcript only; visual skips transcription; mixed prepares both. Audio sources use speech.
  - `count` integer, required
  - `min_duration_seconds` integer, required
  - `max_duration_seconds` integer, required
  - `render` boolean, required: False returns candidate moment sets for review before rendering
  - `aspect_ratio` 'original' | '16:9' | '1:1' | '9:16', required
  - `framing` 'full-frame' | 'background-fill' | 'tracked', required
  - `captions` boolean, required
  - `caption_style` 'progressive' | 'page' | 'scroll', required
  - `caption_size` 'standard' | 'large'
  - `caption_appearance` object
    - `font` 'Inter' | 'Arial' | 'Georgia' | 'Impact' | 'Montserrat' | 'Verdana'
    - `text_color` string
    - `accent_color` string
    - `outline_color` string
  - `style_preset_id` string: Owned saved preset ID, or default
  - `tracking_motion` 'cut' | 'fast-pan' | 'smooth-follow', required
  - `transition` 'hard-cut' | 'fade', required
  - `intro_enabled` boolean
  - `outro_enabled` boolean
  - `audio_motion` 'waveform' | 'bars' | 'pulse'
  - `audio_background_color` string
  - `audio_waveform_color` string

## Response `202`

Durable workflow state; poll get_workflow until terminal.

- object
  - `job` object, required
    - `id` string, uuid, required
    - `projectId` string, uuid, required
    - `kind` 'prepare' | 'framing' | 'generate', required
    - `status` string, required
    - `stage` string, required
    - `errorCategory` string, nullable, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `replayed` boolean, required
    - `pollAfterSeconds` integer, required
    - `result` object, required
      - `analysisId` string, uuid
      - `candidates` object[]
        - `id` string, uuid, required
        - `momentSetId` string, uuid, required
        - `title` string, required
        - `startMs` number, required
        - `endMs` number, required
        - `captions` boolean, required
      - `renders` object[]
        - `id` string, uuid, required
        - `momentSetId` string, uuid, required
        - `status` string, required
        - `downloadUrl` string, nullable, required
        - `previewUrl` string, nullable, required

## Other responses

- `400`: Invalid input.
- `401`: Authentication required.
- `402`: Source allowance exhausted.
- `403`: Required scope missing.
- `404`: Owned resource not found.
- `409`: Prerequisite unavailable or idempotency key reused with changed inputs.
- `429`: Rate limit exceeded.
- `503`: Processing unavailable.

---

[API](https://skmtc.dev/prismclip/apis/prismclip-api.md) · [All operations](https://skmtc.dev/prismclip/apis/prismclip-api/llms.txt) · [OpenAPI document](https://skmtc.dev/prismclip/apis/prismclip-api/revisions/05eda9436f1d?raw)