Video Crop API
POST /crop
About this tool
The `/crop` endpoint exposes FFmpeg’s rectangle filters to automation engineers who must remove letterboxing, isolate regions of interest, or prepare square social renditions from landscape masters. You provide `video_url`, `w`, `h`, `x`, and `y` in JSON; our service validates geometry, schedules GPU/CPU workers according to queue depth, and returns another async task with the same polling semantics as every Droid Apps route. Multipart uploads remain unsupported so that large cinematic mezzanines never traverse your application servers twice.
Cropping is deceptively sensitive to pixel aspect ratios and clean-aperture metadata. When producers deliver anamorphic footage, specify pixel dimensions that match the displayed image, not just the encoded frame size. The API documentation enumerates how rounding works when odd widths appear; reading those notes prevents one-off black bars that only show up on certain players. Active subscriptions include rate limits high enough for batch reprocessing, but you should still exponential-back off when capacity errors appear.
This tool differs from consumer sites that promise “magic reframing.” You are responsible for choosing coordinates—ideal for ML pipelines that already output bounding boxes translated into `x`/`y` pairs. Pair `/crop` with `/cut` when you need both temporal and spatial edits, or follow with `/captions/auto` so text overlays respect the newly centered subject. Each hop reuses the same API key and JSON-only contract, which keeps compliance reviews straightforward.
Expect encoding time to scale with output resolution and whether downstream filters require full decodes. HDR or high-bit-depth sources may demand more CPU than phone footage; plan budgets accordingly. Debug failures by correlating FFmpeg stderr snippets returned in task JSON; they’re the same messages power users see locally, just routed through our observability stack.
When you graduate from manual coordinate entry, feed outputs from object-detection jobs straight into this route: convert bounding boxes to top-left `x`/`y` pairs, clamp to frame edges, and fire batches overnight with the same API key you use for `/cut`. Document expected aspect ratios in your style guide so producers know whether to deliver center-cropped masters or full sensor reads. If downstream players still show thin borders, verify whether your player applies safe-area overlays unrelated to FFmpeg output.
Try it now
How it works
Measure your target window
Determine `w`, `h`, `x`, and `y` in pixels relative to the decoded frame, then point `video_url` to a public HTTPS asset that matches those measurements once decoded.
POST JSON to `/crop`
Include your API key header and application/json body. Workers fetch the remote file, apply the crop graph, and enqueue muxing just like any other FFmpeg job.
Track the async task
Poll `status_url` until completion. Intermediate states let UIs show progress bars without blocking HTTP connections for minutes.
Deliver the cropped rendition
Grab the download link from the finished task, verify visually, and push to your CDN. Re-run with tweaked coordinates if QC finds sub-pixel drift.
Frequently asked questions
What units does the API expect?
All crop parameters are pixel integers after decode. If your ML model outputs normalized floats, multiply by frame width and height server-side before calling us.
Will audio survive the crop?
Yes—audio tracks pass through unless another endpoint strips them. If you need silent exports, run a dedicated mute job or manipulate audio separately with `/redub` variants.
Can I crop and resize in one step?
This route focuses on rectangular crops. Chain `/crop` with other processing tasks or consult the docs for complementary scale parameters if offered.
Why do I see validation errors before processing?
We reject impossible rectangles (negative width, out-of-frame boxes) synchronously so you don’t waste queue slots. Fix the payload and retry immediately.
How do subscriptions affect throughput?
Higher tiers raise concurrent job caps and sometimes priority. Without an active key, every call is rejected regardless of payload quality.