Clipping API

When an API is the right answer

An API earns its place when clipping stops being something a person does and becomes something that happens. Three situations qualify: a show that publishes on a schedule and wants clips without anybody remembering to make them; a product whose own users need clips from their own video; and a backlog large enough that working through it by hand is not a plan.

It does not earn its place for a single clip, or for a handful a week. Integration is a fixed cost paid up front and maintained afterwards, and a trimmer finishes a one-off before an upload would have. The question to ask is not whether an API would be convenient but whether the volume is high enough that a person in the loop is the bottleneck.

Why it cannot be a function call

The first version anybody writes is a single blocking request: send a video, wait, get clips. It cannot work, and the reason is arithmetic rather than design preference.

Clipping a long recording takes minutes to hours. An HTTP request gives up in seconds. A ninety-minute source has to be fetched, decoded, transcribed and scanned before a single cut is made, and no amount of patience on the client side survives the gateways and proxies in between. The diagram at the top of this page is the whole of it: the request dies long before the work finishes.

So every clipping API is submit then collect. You post a source, you get an identifier back immediately, and the clips reach you later – pushed to a webhook, or pulled when you ask. That is not a quirk of one provider, it is what the workload forces, and an integration designed around it will survive changing providers.

The practical consequence is that the interesting part of the integration is not the request, it is everything after it: where you keep the job id, what you do while you wait, how you react when half the clips arrive. That is the next section.

Try it: the states of a job

Any asynchronous clipping job moves through the same handful of states. Most integration bugs live in two of them, and one is the state people forget exists.

The one worth dwelling on is partial. A job that produced six clips out of ten is not a success and not a failure, and a system with no branch for it will treat it as one or the other – silently losing four clips, or throwing away six good ones. It is the single most common way a clipping integration corrupts its own data, and it costs about ten lines to handle properly.

After that, the expensive mistakes are a client timeout shorter than the job, and one retry path for every kind of failure so that permanent errors cycle forever. Both are easy to avoid when you are thinking in job states and nearly invisible when you are thinking in requests.

Three ways people integrate it

Which shape you are building decides what your error handling is actually for, and the three shapes fail in genuinely different ways.

The one with a person waiting is the easiest to get right, because failure is immediately visible and somebody complains. The unattended shapes are where integrations quietly rot – a back-office job that stops working produces no clips and no signal, and the first anybody knows is when someone asks why there have been no clips this month.

So for anything unattended, the rule is: alert on absence, not just on error. A job that failed loudly is fine. A job that stopped being submitted at all is the one that goes unnoticed, and it needs something checking that the expected number of clips arrived.

What actually meters

Whatever the pricing eventually looks like, the thing that scales is worth understanding now, because it changes how you design the integration rather than just what you pay.

The work is in the source, not in the request. Producing a clip scales with the number of clips; finding one scales with the length of the recording, because the whole thing has to be processed before anything can be selected. Ten clips from a four-hour stream is a far larger job than ten clips from a half-hour episode, and any sensible metering reflects that.

Two design consequences follow. Do not send more source than you need: if you already know the interesting half hour is in the middle of a three-hour stream, submitting that section is cheaper and faster than submitting the lot. And do not re-submit a source you have already processed just to ask for different clip lengths – cache what came back, because the expensive part has already been paid for.

Packaging clipping work runs the same arithmetic from the human side, and reaches the same conclusion: price and plan around the recording, not around the clips.

What not to send

Four things worth deciding before the integration exists rather than after, because all four are much harder to change once something is running.

• Footage you are not free to sendAn API call ships the material to somebody else’s machines. Customer recordings, unreleased work and anything under an agreement need that decision made deliberately, not by whoever wired up the integration.
• Your key, in anything a browser can readA key in front-end code is a public key, whatever it is called. Calls belong on your server, with the browser talking to your server instead.
• A webhook endpoint that trusts its callerIf you take results by webhook, that URL is reachable by anyone who finds it. Verify that a delivery really came from where it claims, and treat the body as input rather than instruction.
• More than you need to keepClips, transcripts and source URLs accumulate quietly. Decide what you retain and for how long at the point you build it, because retrofitting deletion to a system that assumed permanence is unpleasant work.

The first is the one that catches organisations rather than individuals. An API call moves footage to somebody else’s infrastructure, and that is a decision about rights and confidentiality as much as about architecture – the sort of thing that ought to be made by someone who knows what the agreements say, not by whoever was assigned the ticket.

What we are building

• Submit a source and get a job backA long video in, a job identifier out, immediately. No blocking calls.
• Results by webhook, with polling as the fallbackBecause a webhook that is never delivered has to be recoverable, and polling is what recovers it.
• Clip specs rather than clip commandsLength range, aspect ratios, caption handling – described once per request rather than as a sequence of imperative steps.
• Honest partial resultsA job that produced six of ten clips should say so, rather than reporting success or failure and making you guess.

Two things we are deliberately not claiming. We are not promising that it will find better moments than you would – choosing the best moments is judgement, and an API does not transfer it. And we are not promising that automatic output will be publishable without checking: captions will still need a correction pass, because the words a machine gets wrong are the names and numbers that matter most.

If you are planning something that would use this, the useful thing you can do now is tell us what shape it is – which of the three integrations above, how long your sources run, what you need back. That is more likely to affect what gets built than anything else.

FAQ

Related: several clips from one source, the clipping route and private clipping.