Developers

The ClipperGen API

Send an episode, get a webhook when its clips are ready, then trim, caption and render them, all from your own code. JSON in and out, one key per workspace.

Create an API keyDownload openapi.json

Quickstart

Create a key in Settings → API keys. Requests go to https://api.clippergen.com/v1. Create a project, send the file to the upload URL you get back, then tell us it's done:

1. Create a project
curl https://api.clippergen.com/v1/projects \
  -H "Authorization: Bearer $CLIPPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-42" \
  -d '{"file_name": "episode-42.mp4", "bytes": 734003200,
       "webhook_url": "https://example.com/hooks/clippergen",
       "options": {"clip_length": "medium", "max_clips": 8, "caption_preset": "karaoke"}}'
2. Upload in chunks, then finish
# upload.url and upload.chunk_size come from step 1. Repeat per chunk.
curl -X PATCH "$UPLOAD_URL" \
  -H "Content-Type: application/offset+octet-stream" \
  -H "Upload-Offset: 0" \
  --data-binary @chunk-000

curl -X POST https://api.clippergen.com/v1/projects/$PROJECT_ID/complete-upload \
  -H "Authorization: Bearer $CLIPPERGEN_API_KEY"
3. When project.ready arrives, list the clips
curl https://api.clippergen.com/v1/projects/$PROJECT_ID/clips \
  -H "Authorization: Bearer $CLIPPERGEN_API_KEY"

Clips come back highest score first, each with a title, hook, the reason it works, and a preview 540 wide in the project's first aspect ratio. Edit one with PATCH /v1/clips/{id}, then POST /v1/clips/{id}/render for a 1080-wide MP4; send aspect_ratio (9:16, 1:1 or 4:5) to pick the shape. Prefer polling? GET /v1/projects/{id} reports status, stage and progress from 0 to 100.

To import from a link instead, send source_url rather than file_name and bytes. Servers without link import answer 501 not_available.

Authentication

Send your key as Authorization: Bearer cg_sk_… on every request. Keys belong to one workspace and only see its projects. We show a key once when you create it and store only a hash, so keep it somewhere safe. Revoke a key in Settings and it stops working immediately. Never put a key in a web page or mobile app; call the API from your server.

Uploads

Uploads are resumable. upload.url is signed and needs no API key, so you can hand it to another process. Send chunks of up to upload.chunk_size bytes with Upload-Offset set to the bytes already sent. If a connection drops, GET the upload URL to read the server's offset and carry on from there; a stale offset gets 409 conflict with the right one in error.details.offset. Upload URLs last 24 hours; GET /v1/projects/{id} hands out a fresh one while the project is still uploading. Files can be up to 4 GB and 3 hours.

Rate limits, idempotency and minutes

Each key can make 60 requests a minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit you get 429 rate_limited with Retry-After in seconds. Chunk uploads don't count.

Send an Idempotency-Key header on any POST. We store the first response for 24 hours and send the same one back, with Idempotent-Replayed: true, if you retry with the same key, so a network error never creates two projects. Using a key for a different request is refused.

Minutes are charged once, when a project is ready; failed projects cost nothing. On plans with an API minute pool, projects created through the API draw on it; on other plans they use your upload minutes. GET /v1/usage shows both.

Endpoints

The endpoint reference loads from the API server, which isn't reachable right now. Try again in a minute, or read /v1/openapi.json on your server.

Webhooks

Add endpoints in Settings → Webhooks, with POST /v1/webhooks, or per project with webhook_url. We POST JSON like this:

POST /hooks/clippergen
Content-Type: application/json
X-ClipperGen-Event: project.ready
X-ClipperGen-Delivery: whd_8d2k1m4q7x0abc
X-ClipperGen-Signature: t=1792214091,v1=5f2b7c…

{"id": "evt_3n8q0w2k5v1abc", "type": "project.ready", "created_at": "2026-10-17T09:06:41.000Z",
 "data": {"project": {"id": "prj_7f3c2a91k2abcd", "status": "ready", "clip_count": 8, …}}}

Events:

  • project.ready — clips are ready to review. data.project.
  • project.failed — processing failed; data.project.error says where and why.
  • render.ready — a 1080p render finished. data.render has a download_url valid 7 days, data.clip the clip.
  • publication.posted — a scheduled or immediate post went out (once publishing is available).
  • publication.failed — a post could not be published (once publishing is available).

Verifying signatures

Every request is signed with your workspace signing secret (Settings → Webhooks). X-ClipperGen-Signature holds a unix timestamp t and v1, the hex HMAC-SHA256 of `${t}.${rawBody}`. Compute it over the raw body, before parsing JSON, compare in constant time, and reject timestamps more than 5 minutes from now so a captured request can't be replayed.

Node, without the SDK
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return parts.v1?.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Answer with any 2xx within 10 seconds. Anything else is retried 5 times over 24 hours: 1 minute, 10 minutes, 1 hour, 6 hours and 24 hours after the first attempt. The event id stays the same on retries, so use it to skip duplicates. Settings shows every delivery with its status, and can send a test event or resend a failed one.

Errors

Errors use one shape: {"error": {"code", "message", "details"?}}. The message says what to do next.

CodeStatusMeaning
invalid_request400A parameter is missing or wrong. details.field names it.
unauthorized401No API key, or the key is wrong or revoked.
quota_exceeded402No minutes left this month in the pool the project draws on.
unsupported_media400The file type isn't one we can read. Upload MP4, MOV, MKV, WebM, MP3, WAV or M4A.
not_found404The object doesn't exist in this workspace, or was deleted.
conflict409The request clashes with the current state, such as an out-of-date upload offset (details.offset) or a reused Idempotency-Key that is still running.
source_unreachable422We couldn't fetch the source_url.
rate_limited429More than 60 requests in a minute with this key. Wait Retry-After seconds.
not_available501The feature isn't enabled on this server yet, such as link import or publishing.
processing_failed—Appears on a failed project in error.code, with the stage and a message.
internal_error500Something broke on our side. Retrying with the same Idempotency-Key is safe.

TypeScript SDK

@clippergen/sdk wraps every endpoint with types, uploads in resumable chunks, waits out rate limits, adds idempotency keys to POSTs, and verifies webhooks.

import { ClipperGen } from '@clippergen/sdk';

const cg = new ClipperGen({ apiKey: process.env.CLIPPERGEN_API_KEY, baseUrl: 'https://api.clippergen.com' });
const project = await cg.upload({ file: './episode-42.mp4', options: { max_clips: 8 } });
await cg.waitForProject(project.id);
const { data: clips } = await cg.projects.clips(project.id);

Zapier and Make

The Zapier integration has two triggers, Project Ready and Clip Rendered, and one action, Create Project From URL. It subscribes with POST /v1/webhooks, so its subscriptions show up in your settings. In Make, use a Custom webhook module as the trigger and HTTP modules with your API key for actions.