---
title: "Start a clipping"
method: POST
path: "/clipping"
tags: ["Clipping"]
---

# Start a clipping

`POST /clipping`

## Request

- Base URL: `https://api.postiz.com/public/v1`
- URL: `https://api.postiz.com/public/v1/clipping`
- Auth: API key in header `Authorization`

Turn a long YouTube video into short vertical clips with burned-in captions. The best parts are picked automatically, every clip is saved to the media library, and when integrations are passed a draft post is created for every clip on every integration. Nothing is scheduled or published.

Clipping takes several minutes, so this only starts it and returns the clipping `id`. Poll [Get a clipping](/public-api/clipping/get) until the status is `completed` or `failed`.

## Request body

- ClippingRequest
  - `url` string, uri, required: URL of the YouTube video (`youtube.com` or `youtu.be`)
  - `integrations` string[]: IDs of the integrations to create a draft post for, one draft per clip per integration. Without any, the clips only land in the media library
  - `clips` integer: Maximum number of clips
  - `fit` 'blur' | 'crop': How the horizontal video fills the vertical clip. `blur` keeps the whole picture over a blurred copy of itself. `crop` fills the clip with the middle of the picture and cuts the sides away; there is no face tracking

## Response `200`

Clipping started

- object
  - `id` string: ID of the clipping

## Other responses

- `400`: Not a YouTube URL, or an integration was not found
- `402`: No clipping minutes are left for this month (or the plan has none). Nothing is charged
- `406`: The organization is still in trial
- `429`: A clipping is already running, or the daily cap of 20 was reached
- `503`: Clipping is not configured on this instance

## Changes

- **2026-09-22** `56bc50600b40`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/postiz/apis/postiz-public-api/changes/clipping/post.md)

---

[API](https://skmtc.dev/postiz/apis/postiz-public-api.md) - [All operations](https://skmtc.dev/postiz/apis/postiz-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/postiz/apis/postiz-public-api/revisions/269b4fe5c86b?raw)