---
source: sighthound-developer-portal
url: https://dev.sighthound.com/redactor/reference/videos/process/
markdown-url: https://dev.sighthound.com/redactor/reference/videos/process.md
title: "Process Videos"
description: "Redactor videos:process API request and response schema for preparing, detecting, rendering, and exporting video sessions."
content-type: text/markdown
---

> For AI agents: a documentation index is available at [llms.txt](https://dev.sighthound.com/llms.txt). Markdown versions are available at matching `.md` URLs.

# Process Videos

<div class="portal-reference-panel">
<div class="portal-reference-panel__header">
    <span class="portal-reference-method">POST</span>
    <span class="portal-reference-endpoint"><code>/api/v1/videos:process</code></span>
</div>
<p class="portal-reference-summary">Create an asynchronous Redactor video operation to prepare media, run detection, render redacted output, persist state, or notify external systems.</p>
<div class="portal-reference-grid">
    <div class="portal-reference-item">
        <strong>Request body</strong>
        <span><code>inputUri</code> and <code>features</code> are required. Output, notification, tag, ACL, and video context fields are optional.</span>
    </div>
    <div class="portal-reference-item">
        <strong>Response</strong>
        <span>Returns an operation name that can be polled or correlated with webhook completion events.</span>
    </div>
    <div class="portal-reference-item">
        <strong>Common use</strong>
        <span>Load media, auto-detect sensitive objects, render output, or save reusable redaction state.</span>
    </div>
</div>
</div>

## HTTP Request

`POST /api/v1/videos:process`

## Request Body

| Fields      |                                      |
| ----------- | ------------------------------------ |
| `inputUri`
<sup>Required</sup> | <sup>string</sup>
The Input URI can either point to a single video or a storage bucket which contains existing Redactor state to load. The URI must end in a trailing slash if using a storage bucket.<p>Examples:<ul><li>HTTP/HTTPS
`https://example.com/my-video.mp4`</li><li>Filesystem Path
`file:///path/to/my-video.mp4` or `file:///path/to/my-bucket/`</li><li>Windows Path
`file:///C:/path/to/my-video.mp4` or `file:///C:/path/to/my-bucket/`</li><li>Azure SAS
`https://my-storage-account.blob.core.windows.net/container/path/to/my-video.mp4?sig=Sec...` or `https://my-storage-account.blob.core.windows.net/container/path/to/my-bucket/?sig=Sec...`</li><li>AWS S3
`s3://bucket-name/path/to/my-video.mp4` or `s3://bucket-name/path/to/my-bucket/`</li></ul></p>|
| `features`
<sup>Required</sup>  | <sup>Array of strings</sup>
Enum: `MEDIA_PREPARE` `PERSON_DETECTION` `HEAD_DETECTION` `FACE_DETECTION` `VEHICLE_DETECTION` `LICENSE_PLATE_DETECTION` `ID_DETECTION` `SCREEN_DETECTION` `DOCUMENT_DETECTION` `SPEECH_TRANSCRIPTION` `MEDIA_RENDERING` `STATE_DROP` 

Array of the desired processing features
<ul><li>`MEDIA_PREPARE` - Import media and prepare for use with Redactor. This can be omitted if other "features" are also in the request.</li><li>`PERSON_DETECTION` - Detect people</li><li>`HEAD_DETECTION` - Detect heads (v6+)</li><li>`FACE_DETECTION` - Detect faces</li><li>`VEHICLE_DETECTION` - Detect vehicles</li><li>`LICENSE_PLATE_DETECTION` - Detect vehicle license plates</li><li>`ID_DETECTION` - Detect identification like driver's licenses, passports, and other IDs (v7+)</li><li>`SCREEN_DETECTION` - Detect screens like monitors, laptops, and phones (v7+)</li><li>`DOCUMENT_DETECTION` - Detect documents and other papers (v7+)</li><li>`SPEECH_TRANSCRIPTION` - Transcribe the words spoken in a video for a specified language. (v5+)</li><li>`MEDIA_RENDER` - Render processed media. Required if output desired. (Redactor v4 used `MEDIA_RENDERING` which is now an alias.)</li><li>`STATE_DROP` - Remove all internal, persisted state from the Redactor server for the video/session. This includes videos, thumbnails, and redaction data. This does NOT remove data from the output locations you specified like the local filesystem directories, S3, Azure, etc. (v5+)</li></ul>|
| `outputUri` | <sup>string</sup>
 The URI of the storage bucket to use for persisting Redactor's state for the video, or the storage bucket and filename of the redacted video. <p>If outputUri ends in a trailing slash, all of the redaction state for the video will be persisted in the output bucket. This bucket can be used as the `inputUri` for subsequent API calls so that none of your previous work is lost. If a `MEDIA_RENDER` call is made, the redacted video will be saved to the bucket with the filename `redacted.mp4`. <ul><li>Filesystem Path
`file:///path/to/my-bucket/` or `file:///C:/path/to/my-bucket/`</li><li>Azure SAS
`https://my-storage-account.blob.core.windows.net/container/path/to/my-bucket/?sig=Sec...`</li><li>AWS S3
`s3://bucket-name/path/to/my-bucket/`</li></ul></p><p>If outputUri does NOT end in a trailing slash, Redactor will assume it is a filename and only the redacted video will be output using that filename (if `MEDIA_RENDER` is listed as a `feature`). You can name the output file anything you like, but it will be an MP4 container for videos and a JPG for images.<ul><li>Filesystem Path
`file:///path/to/my-video.mp4` or `file:///C:/path/to/my-video.mp4`</li><li>Azure SAS
`https://my-storage-account.blob.core.windows.net/container/path/to/my-video.mp4?sig=Sec...`</li><li>AWS S3
`s3://bucket-name/path/to/my-video.mp4`</li></ul></p><p>If outputUri is omitted from the API request body, all redaction state will be kept in Redactor's internal filesystem, which is helpful if you only need to push videos into Redactor for end users that perform their work using the native UI.</p>|
| `notifications` | <sup>Array of objects (NotificationConfig)</sup> 
Notification webhook descriptor. Users can enable webhooks to receive messages for their operation. |
| `videoContext` | <sup>object (VideoContext)</sup> 
Additional configuration options. All optional.|
| `projectId` | <sup>string</sup>
Allows Embedded UI users to define a project identifier to that multiple videos can be loaded and presented to the end user in the editor. <p>Requirements: 6 to 36 characters in length; only contains lowercase letters, numbers, and hyphens; cannot end with a hyphen.</p>|
| `tag` |<sup>object</sup> 
 User-defined object that is returned in every notification.|
| `acl` 
<sup>v4.4.5+</sup> |<sup>Array of strings</sup> 
Optional list of one or more Redactor usernames that will have access to the video in the standard Redactor UI. E.g. `["user1", "user3"]`|

## Types

### VideoContext

| Fields      |                          |
| ----------- | -------------------------|
| `prepareConfig` | object (PrepareConfig)|
| `processConfig` | object (ProcessConfig)|
| `renderConfig` | object (RenderConfig) |

### PrepareConfig

| Fields      |                          |
| ----------- | -------------------------|
| `sessionId` | <sup>string</sup>
Default: auto-generated UUID
Allows the setting of the unique identifier for this specific video/session if the default value isn't desired. Can not be changed once its defined.|
| `ignoreCertificateErrors` | <sup>boolean</sup>
Default: `false`
Ignores certificate errors for inputUri. Only enable if you trust the source's certificate (e.g. internal development server with self-signed certificate).|
| `hashTypes` | <sup>Array of strings</sup>
Default: `["sha256"]`
Hash types (md5,sha1,sha256,sha512) to be computed over the original media file.|

### ProcessConfig

| Fields      |                          |
| ----------- | -------------------------|
| `objectsConfidenceThreshold` | <sup>number</sup>
Default: `0.3` for `gen6_standard` profile
Confidence threshold for detection of all primary objects (people and vehicles). Value should be between 0 and 1. (Redactor v4 used `confidenceThreshold` which is now an alias.)|
| `innerObjectsConfidenceThreshold` | <sup>number</sup>
Default: `0.15` for `gen6_standard` profile
Confidence threshold for detection of all objects contained in primary objects (faces and license plates). Value should be between 0 and 1. (Redactor v4 used `confidenceThresholdSub` which is now an alias.)|
| `faceBoxExpansionFactor` | <sup>number</sup>
Default: `1.5`
Scales the face detection bounding box size returned after auto-redaction. Value should be between 1 and 5. The default value was `2.0` in releases v4.3.0 and earlier. (Redactor v4 used `faceboxExpand` which is now an alias.)|
| `profileName` |  <sup>string</sup>
Default: `"gen6_standard"`
Enum: `"gen6_standard"` `"gen6_highMotion"` `"gen6_conference"` `"gen5_standard"` `"gen5_highMotion"` 
Presets for the computer vision parameters used for auto-detection. While the `_standard` profile works well across a wide variety of videos, `gen6_highMotion` is recommended for body/dash camera footage or other videos with fast moving objects. Gen6 profiles are recommended over the older Gen5.|

### RenderConfig

| Fields      |                          |
| ----------- | -------------------------|
| `redactionStyle` | <sup>string</sup>
Default: `"MOSAIC"`
Enum: `"OUTLINE"` `"FILL"` `"PIXELATE"` `"BLUR"` `"MOSAIC"` `"SMART"` |
| `redactionShape` | <sup>string</sup>
Default: `"RECTANGLE"`
Enum: `"RECTANGLE"` `"ELLIPSE"` |
| `redactionIntensity` | <sup>string</sup>
Default: `"MEDIUM"`
Enum: `"LOW"` `"MEDIUM"` `"HIGH"` |
| `redactionColor` | <sup>string</sup>
Default: `"#9F0500"`
The color used for OUTLINE and FILL redaction styles. Not used for other styles. |
| `maskAudio` | <sup>string</sup>
Enum: `"SILENCE"` `"BEEP"` `"SCRAMBLE"`
If defined, all audio in the video will be masked using the method/type provided. |
| `maskAudioParams` | <sup>Array of numbers 2 items</sup>
Default: `[0.32,-0.24]`
Only applicable when using SCRAMBLE maskAudio. Adjust the 2 values to modify the scramble strength and quality. Allowed values are between -1.0 and 1.0. |
| `videoQuality` | <sup>number `[ 0 .. 1 ]`</sup>
Default: `0.65`
Video encoding quality which impacts the size of output. 0 is the lowest quality, 1 is highest, and 0.65 is the default. |
| `videoPreset` | <sup>string</sup>
Default: `"ULTRAFAST"`
Enum: `"ULTRAFAST"` `"SUPERFAST"` `"VERYFAST"` `"FASTER"` `"FAST"` `"MEDIUM"` `"SLOW"` `"SLOWER"` `"VERYSLOW"`
Controls the speed versus compression ratio. Reduce the preset to receive better compression. |
| `exportHashes` | <sup>Array of strings</sup>
Hash types (md5,sha1,sha256,sha512) to be computed over the exported media file, saved in the exported metadata.|

### NotificationConfig

| Fields      |                                      |
| ----------- | ------------------------------------ |
| `method` | <sup>string</sup>
 Value: `"HTTP_POST"` |
| `uri` | <sup>string</sup>
 The storage bucket URI to use for output. |
| `events` | <sup>Array of string</sup>
Items Enum: `"START"` `"PROGRESS"` `"COMPLETION"` |

## Response Body

A success response returns an object with an Operation name in the format:

```projects/{project-id}/locations/{location-id}/operations/{operation-id} ```

| RESPONSE SCHEMA: | application/json   |
| ----------- | ----------------------- |
| `name`  | string&lt;operationName&gt; |


## Samples

### Request

```json
{
  "inputUri": "http://example.com/path/to/video.mp4",
  "features": [
    "FACE_DETECTION",
    "LICENSE_PLATE_DETECTION",
    "MEDIA_RENDERING"
  ],
  "outputUri": "s3://bucket-name/keyname/",
  "notifications": [
    {
      "method": "HTTP_POST",
      "uri": "https://example.com/mywebhook/endpoint",
      "events": [
        "START",
        "PROGRESS",
        "COMPLETION"
      ]
    }
  ],
  "videoContext": {
    "renderConfig": {
      "redactionStyle": "MOSAIC",
      "redactionShape": "ELLIPSE",
      "redactionIntensity": "HIGH",
      "redactionColor": "#CC3399",
      "maskAudio": "SCRAMBLE"
    },
    "processConfig": {
      "confidenceThreshold": 0.3,
      "confidenceThresholdSub": 0.05,
      "faceboxExpand": 2
    }
  },
  "tag": {
    "city": "Mountain View",
    "state": "CA",
    "validUntil": 1607111026726
  }
}
```

### Response

```json
{
  "name": "projects/{project-id}/locations/{location-id}/operations/{operation-id}"
}
```

---

# Agent Instructions

Use this Markdown page as context for Sighthound Developer Portal questions. For broader navigation, read https://dev.sighthound.com/llms.txt. Answer from Sighthound documentation, cite relevant source URLs, and do not ask users to paste secrets, tokens, license keys, or credentials into chat.