What the redaction API does
Redaction hides part of the picture for part of the video. You describe regions: a rectangle or an oval, filled with either a blur or a solid black bar ("type": "blur" or "box"), each active between a start and an end time. You can send up to 20 regions per video. Positions are fractions of the frame from 0 to 1, so the same numbers work at every quality level; for a screen plus camera video they refer to the combined picture, so the camera bubble can be hidden too.
Redactions are applied before the quality ladder is made. Every rendition, the downloadable MP4, the HLS stream and the poster image are all redacted, not just one output.
Example
Redactions travel in the body of complete (or of a reprocess or an edit). Times are seconds on the output timeline, after any trim, and an end of null means until the end.
POST /videos/3f1c…/complete
{
"trim": { "start": 4.5, "end": 312 },
"redactions": [
{ "type": "box", "x": 0.05, "y": 0.04, "w": 0.30, "h": 0.06, "start": 0, "end": null },
{ "type": "blur", "shape": "ellipse", "x": 0.62, "y": 0.55, "w": 0.20, "h": 0.30, "start": 12.5, "end": 20 }
],
"deleteOriginal": true
}The first region is a black bar across the top of the frame for the whole video, such as a name or account number on screen. The second is an oval blur for seven and a half seconds.
Following moving content
People and objects move. For anything that does, replace x, y, w and h with a track of keyframes. The region glides smoothly between them and changes size as it goes. This is how the documentation hides a face walking across the frame:
{ "type": "blur", "shape": "ellipse", "start": 4, "end": 12,
"track": [ { "time": 4, "x": 0.10, "y": 0.30, "w": 0.15, "h": 0.25 },
{ "time": 8, "x": 0.45, "y": 0.28, "w": 0.18, "h": 0.30 },
{ "time": 12, "x": 0.80, "y": 0.30, "w": 0.15, "h": 0.25 } ] }Add a keyframe wherever the motion changes direction or speed; a region can have up to 50. The keyframes are yours to supply: in the web app you drag a box on the video, click Follow motion, pause where the object has moved and drag a new box, with a live preview of the path. From the API, send the coordinates your own detection or review step produces.
Redaction you can rely on
Black bars are irreversible
A solid bar can't be undone, which makes it the safest choice for text. A blur of small text can sometimes be guessed.
Delete the original
Set deleteOriginal to remove every stored version of the upload once the redacted output is published. Such videos can't be reprocessed later.
Checked before it runs
Boxes outside the frame and times after the video ends are rejected up front, each with its field path, and ?dryRun=true checks a request without creating anything.
Keep in mind that without deleteOriginal the unredacted original stays in your private source storage, so decide deliberately which you want. Redaction also isn't limited to uploads: a finished video can be reprocessed with new redactions from the app's Trim / redact & reprocess action or the API, with nothing re-uploaded, and an edit takes redactions on its own timeline.
A typical workflow
- Upload the video and call
completewith your redactions, or tick Review & redact first in the web app to draw regions before processing starts. - Wait for the
video.readywebhook, or poll the status. - Share the redacted MP4 or stream. If the original must not be kept, set
deleteOriginalin the same request as the redactions.
Which plans include redaction
Redaction, including motion tracking, is a Pro and Scale feature. On Free and Starter a request that includes redactions is refused with a 403 PLAN_UPGRADE_REQUIRED error that names the plan that has it, and a dry run reports the same error without creating anything.
| Plan | Price | Processing minutes | Max quality | Redaction |
|---|---|---|---|---|
| Free | $0/mo | 30 | 720p | Not included |
| Starter | $49/mo | 400 | 1080p | Not included |
| Pro | $199/mo | 1,500 | 4K | Included |
| Scale | $699/mo | 6,000 | 4K | Included |
Usage beyond a paid plan is billed at $0.09 per processing minute, $0.15 per GB-month of storage and $0.55 per GB of delivery. Full details are on the pricing page.
In the documentation
- Redaction and moving content
- Processing options and redaction fields
- Validation and dry runs
- Edits (redactions on an edit's timeline)
- Limits
Frequently asked questions
What can the redaction API hide?
Rectangles or ovals, filled with a blur or a solid black bar. Each region has its own start and end time, so it can appear for a few seconds or for the whole video. A video can carry up to 20 regions.
How does motion tracking work?
For something that moves, you give the region a track of up to 50 keyframes instead of a fixed position. The region glides smoothly between the keyframes, resizing as it goes. In the web app you click Follow motion, pause where the object has moved and drag a new box.
Should I use blur or a black bar?
A black bar is irreversible, so it is the safest choice for text; a blur of small text can sometimes be guessed. Use a blur where a softer look is enough.
Is the unredacted original kept?
Only if you want it. Without deleteOriginal the original stays in your private storage; with deleteOriginal true every stored version of the upload is removed once the redacted output is published, and the video can't be reprocessed afterwards.
Which plans include redaction?
Pro and Scale. Free and Starter get a 403 PLAN_UPGRADE_REQUIRED error that says which plan has it.