> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postqueen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> PostQueen's hosted API is https://api.postqueen.ai. The public API base is https://api.postqueen.ai/public/v1 and takes the raw API key in the Authorization header, with no Bearer prefix.
> The MCP server for posting is https://api.postqueen.ai/mcp/YOUR_API_KEY (or /mcp with Authorization: Bearer YOUR_API_KEY). docs.postqueen.ai/mcp only searches these docs and cannot post.
> The API key is under Connections > API Keys in the app, and only workspace admins can see it.
# Start a clipping
> Turn a YouTube video into short vertical clips with captions, saved to the media library and drafted on the channels you name.
export const ChannelStatus = ({status, children}) => {
const look = ({
available: {
color: 'green',
label: 'Available'
},
'in-review': {
color: 'yellow',
label: 'In review'
},
soon: {
color: 'gray',
label: 'Soon'
}
})[status] || ({
color: 'gray',
label: status
});
return
{look.label}
{children ? {children} : null}
;
};
Not available on PostQueen yet. Every request answers `503` with `Clipping is not configured`.
A clipping runs in the background and takes several minutes. This endpoint starts it and answers at once with its `id`. Follow it with [Get a clipping](/public-api/clipping/get). What the clips look like and how they are picked: [Clipping](/using/clipping).
```bash theme={"system"}
curl -X POST "https://api.postqueen.ai/public/v1/clipping" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID", "integrations": ["YOUR_CHANNEL_ID"], "clips": 3, "fit": "blur"}'
```
```json theme={"system"}
{ "id": "3f0c2a4e-8b1d-4c6e-9f2a-7d5b1e0c4a93" }
```
## The fields
| Field | Default | What it does |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | Required | A YouTube video, on `youtube.com` or `youtu.be` |
| `integrations` | None | Up to 20 channel ids from [List channels](/public-api/integrations/list). Every clip becomes a draft on each of them. Without any, the clips only land in the media library |
| `clips` | `5` | The most clips to make, 1 to 10. A video with fewer good moments gives fewer |
| `fit` | `blur` | How the horizontal picture fills the vertical clip. `blur` keeps the whole picture over a blurred copy of itself. `crop` fills the frame with the middle of the picture and cuts the sides away, with no face tracking |
The drafts are never scheduled or published. Each clip's drafts take the next free time from your [posting times](/using/posting-times), with the network settings left empty: add what the network needs before you schedule them.
## Minutes
A clipping uses one clipping minute for each started minute of the video, however many clips it makes. They are taken once PostQueen knows how long the video is, and given back if no clip is made. See [Clipping minutes](/using/clipping#clipping-minutes).
## If it fails
| Answer | What to do |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` with a `message` list | A field is missing or out of range. The list says which |
| `400 Only YouTube videos can be clipped` | Send a `youtube.com` or `youtu.be` link |
| `400 Channel {id} not found` | One of the `integrations` is not a channel in your workspace, or was deleted. Check it with [List channels](/public-api/integrations/list) |
| `402` | No clipping minutes are left this month. The body has the billing link |
| `406 Clipping is not available in trial mode` | Clipping is not part of the free trial |
| `429 Another clipping is being started` | Two requests arrived at the same moment. Wait a few seconds and send it again |
| `429 A clipping is already running, wait for it to finish` | Poll the running clipping until it is `completed` or `failed`, then start the next one |
| `429 Too many clippings were started today, try again tomorrow` | Starts are counted over the last 24 hours. Try again later |
| `503 Clipping is not configured` | Clipping is not available on PostQueen yet |
| `503 Clipping is not available` | The clipping could not be started. Try again later |
These `429` answers come from clipping itself, not from an hourly limit, so they carry no `Retry-After` header.
A problem found after the start, such as a private video or one longer than your minutes, does not fail this request. It ends the clipping as `failed`, with the reason in `error` on [Get a clipping](/public-api/clipping/get).
## OpenAPI
````yaml POST /clipping
openapi: 3.1.0
info:
title: PostQueen Public API
version: 1.0.0
license:
name: MIT
identifier: MIT
description: >-
Schedule posts, upload media, read analytics and manage the channels of your
PostQueen workspace.
## Authentication
Send your API key in the `Authorization` header exactly as it is, with no
prefix:
```
Authorization: YOUR_API_KEY
```
The key is under **Connections > API Keys** in the app. Only a workspace
Admin or Super Admin can reveal or rotate it. An app your users sign in to
with OAuth sends its `pos_` access token in the same header, also with no
prefix. The workspace needs a subscription, and the free trial counts.
## Rate limits
A workspace can send 30 `POST /posts` requests an hour, and a request
refused with `400` counts too. `POST /upload` and `POST /upload-from-url`
allow 300 requests an hour each, per workspace. Nothing else is limited. A
limited endpoint answers with `X-RateLimit-Limit`, `X-RateLimit-Remaining`
and `X-RateLimit-Reset` headers, and over the limit with `429` and
`Retry-After` (seconds).
## Terminology
The app says channel, the API says integration. They are the same thing: a
connected account on a network.
servers:
- url: https://api.postqueen.ai/public/v1
description: PostQueen
security:
- ApiKeyAuth: []
tags:
- name: Channels
description: Connected channels. The API calls them integrations.
- name: Posts
description: Create, list, change and delete posts
- name: Media
description: Upload files to the media library
- name: Clipping
description: >-
Turn a YouTube video into short vertical clips. Not available on PostQueen
yet
- name: AI video
description: Generate a video with AI into the media library
- name: Analytics
description: Channel and post metrics
- name: Notifications
description: The workspace's notifications
- name: OAuth
description: Sign-in for apps that act for other PostQueen workspaces
paths:
/clipping:
post:
tags:
- Clipping
summary: Start a clipping
description: >-
Not available on PostQueen yet: every request answers `503` with
`Clipping is not configured`.
Starts turning a YouTube video into short vertical clips (1080 × 1920)
with burned-in captions, and answers at once with the clipping's `id`.
Every clip is saved to the media library and, for each channel in
`integrations`, drafted as a post. Nothing is scheduled or published.
The clipping uses one clipping minute for each started minute of the
video, taken once its length is known and given back if no clip is made.
Follow it with `GET /clipping/{id}`.
operationId: startClipping
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClippingRequest'
example:
url: https://www.youtube.com/watch?v=VIDEO_ID
integrations:
- YOUR_CHANNEL_ID
clips: 3
fit: blur
responses:
'201':
description: Started. The clipping runs in the background
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The clipping's id, for `GET /clipping/{id}`
example:
id: 3f0c2a4e-8b1d-4c6e-9f2a-7d5b1e0c4a93
'400':
description: >-
A field failed validation (`message` is a list), `Only YouTube
videos can be clipped`, or `Channel {id} not found`
content:
application/json:
schema:
$ref: '#/components/schemas/NestError'
examples:
validation:
summary: Validation
value:
message:
- clips must not be greater than 10
error: Bad Request
statusCode: 400
youtube:
summary: Not a YouTube link
value:
statusCode: 400
message: Only YouTube videos can be clipped
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: No clipping minutes are left this month
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequired'
example:
statusCode: 402
message: >-
You have used all the clipping minutes of your subscription
for this month. Please upgrade your subscription to clip more
videos.
url: https://app.postqueen.ai/billing
'406':
description: '`Clipping is not available in trial mode`'
content:
application/json:
schema:
$ref: '#/components/schemas/NestError'
example:
statusCode: 406
message: Clipping is not available in trial mode
'429':
description: >-
`Another clipping is being started`, `A clipping is already running,
wait for it to finish`, or `Too many clippings were started today,
try again tomorrow`. These come from clipping itself, not from an
hourly limit, and carry no `Retry-After`
content:
application/json:
schema:
$ref: '#/components/schemas/NestError'
example:
statusCode: 429
message: A clipping is already running, wait for it to finish
'503':
description: >-
`Clipping is not configured`: clipping is not available on PostQueen
yet. `Clipping is not available`: the clipping could not be started,
try again later
content:
application/json:
schema:
$ref: '#/components/schemas/NestError'
example:
statusCode: 503
message: Clipping is not configured
components:
schemas:
ClippingRequest:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: A YouTube video, on youtube.com or youtu.be
integrations:
type: array
maxItems: 20
items:
type: string
description: >-
Channel ids to draft every clip on. Without any, the clips only land
in the media library
clips:
type: integer
minimum: 1
maximum: 10
default: 5
description: The most clips to make. A video with fewer good moments gives fewer
fit:
type: string
enum:
- blur
- crop
default: blur
description: >-
How the horizontal picture fills the vertical clip. `blur` keeps the
whole picture over a blurred copy of itself. `crop` fills the frame
with the middle of the picture and cuts the sides away, with no face
tracking
NestError:
type: object
description: >-
The standard error shape: validation errors, not-found errors and rate
limits
properties:
statusCode:
type: integer
message:
oneOf:
- type: string
- type: array
items:
type: string
error:
type: string
PaymentRequired:
type: object
properties:
statusCode:
type: integer
message:
type: string
url:
type: string
description: The billing page
MessageError:
type: object
description: The error shape of most checks written into the public API itself
properties:
msg:
type: string
responses:
Unauthorized:
description: >-
`No API Key found`, `Invalid API key`, `Invalid OAuth token`, or `No
subscription found` when the workspace has no subscription
content:
application/json:
schema:
$ref: '#/components/schemas/MessageError'
example:
msg: Invalid API key
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Your API key from Connections > API Keys, or an OAuth access token
(`pos_...`). Send it as it is, with no `Bearer` prefix.
````