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:
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"}}'# 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"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.
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.
| Code | Status | Meaning |
|---|---|---|
invalid_request | 400 | A parameter is missing or wrong. details.field names it. |
unauthorized | 401 | No API key, or the key is wrong or revoked. |
quota_exceeded | 402 | No minutes left this month in the pool the project draws on. |
unsupported_media | 400 | The file type isn't one we can read. Upload MP4, MOV, MKV, WebM, MP3, WAV or M4A. |
not_found | 404 | The object doesn't exist in this workspace, or was deleted. |
conflict | 409 | The 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_unreachable | 422 | We couldn't fetch the source_url. |
rate_limited | 429 | More than 60 requests in a minute with this key. Wait Retry-After seconds. |
not_available | 501 | The 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_error | 500 | Something 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.