Redactor example guide
Start with the core Redactor API workflow: load media, run detection, export output, organize sessions, and inspect asynchronous operation results.
[Review API requests](#example-api-requests)
[Open videos:process reference](../../reference/videos/process/)
Load media
Prepare videos from HTTP, local filesystem, file shares, Azure SAS URLs, AWS S3, or saved session folders.
Detect and redact
Run detection features for faces, heads, plates, people, screens, documents, IDs, and speech transcripts.
Export and notify
Render redacted media, persist state, and subscribe to operation completion through webhooks.
This guide shows several ways to work with the Redactor API. Whether you want to streamline your organization's redaction workflow by uploading videos into Redactor from your video management system, or you want a fully-automated redaction pipeline, this guide includes several basic API calls to get you started.
## Project Files and Setup
To help you get started quickly, Sighthound provides the [Redactor Agent Toolkit](../reference/agent-toolkit.md): a package with Docker Compose configurations, reference materials, and LLM-optimized documentation so you can ask your AI coding agent questions about Redactor as you work. Contact [sales@sighthound.com](mailto:sales@sighthound.com) to obtain the toolkit and an evaluation serial number. If you prefer, a Windows version of Redactor is available, but you will need to modify the examples below to fit your specific deployment.
To start the Redactor service in Docker:
- Extract the toolkit zip and `cd` into the `redactor-api-toolkit/sighthound-redactor-api-examples` folder
- Start the Redactor container: `docker compose up -d`
- If this is your first time running this instance of Redactor (particularly with this Docker Compose), you will need to set up your initial admin user and add a license: http://localhost:9000/admin
See the [Agent Toolkit](../reference/agent-toolkit.md) page for full details on the folder structure, volume mounts, and additional resources included in the toolkit.
## Example API Requests
!!! Note
It's best to have Redactor open in a browser while you work through the examples below. You'll be able to see the progress of the API calls and see the results of the redactions. Assuming you have Redactor running locally, it's typically available at http://localhost:9000.
### Load Video
To load a video into Redactor, provide the path to the source video in `inputUri` and add `MEDIA_PREPARE` to the `features` array. This will import the video and prepare it for redaction in the editor.
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": ["MEDIA_PREPARE"]
}'
```
After the API call completes, you will see a new video in the browser with the name "Dancing.mp4".
Supported `inputUri` formats include:
- HTTP/HTTPS:
`https://example.com/my-video.mp4`
- File System Path:
`file:///path/to/my-video.mp4`
- Windows File Path:
`file:///C:/path/to/my-video.mp4`
- File Share Path:
`file://hostname/path/to/my-video.mp4`
- Azure SAS:
`https://my-storage-account.blob.core.windows.net/container/path/to/my-video.mp4?sig=Sec...`
- AWS S3:
`s3://bucket-name/path/to/my-video.mp4`
- Redactor State Folder (Reloads/resumes a previous redaction session):
`file:///path/to/my-video/redaction-data/`
### Load Video and Auto-Detect
In cases where you know the redaction users will want to run auto-detection, you can kick off that process for them immediately after loading a video via API. To do this, provide a path to the input video in the `inputUri` field and add the `HEAD_DETECTION` and `LICENSE_PLATE_DETECTION` features. Note: `MEDIA_PREPARE` does not need to be specified if other features are listed.
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": ["HEAD_DETECTION", "LICENSE_PLATE_DETECTION"]
}'
```
The video will appear in the editor after it is loaded, and the user will see an "In-Use" message and progress bar in their browser while the auto-detection is running.
Other auto-detection types available:
- `PERSON_DETECTION` - Detect people
- `HEAD_DETECTION` - Detect heads (v6+)
- `FACE_DETECTION` - Detect faces
- `VEHICLE_DETECTION` - Detect vehicles
- `LICENSE_PLATE_DETECTION` - Detect vehicle license plates
- `ID_DETECTION` - Detect identification like driver's licenses, passports, and other IDs (v7+)
- `SCREEN_DETECTION` - Detect screens like monitors, laptops, and phones (v7+)
- `DOCUMENT_DETECTION` - Detect documents and other papers (v7+)
- `SPEECH_TRANSCRIPTION` - Transcribe the words spoken in a video for a specified language. (v5+)
### Load, Auto-Detect, and Export
Some use cases require a fully-automated redaction workflow without any user interaction. In the following example, Redactor will load the specified video, auto-detect heads, and export the redacted video to a specified location. The `outputUri` is a path where either a single video or all of the Redaction state data for the video will be stored. If an `outputUri` is not provided, all of the files will be stored in Redactor's internal storage and can be moved to a different location (e.g., AWS S3, Azure Blob Storage, local filesystem, etc.) in subsequent API calls when you're ready.
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": ["MEDIA_PREPARE", "HEAD_DETECTION", "MEDIA_RENDER"],
"outputUri": "file:///data/examples/dancing3/Dancing-redacted.mp4"
}'
```
After the redaction is done, the redacted video can be found on the host machine in:
`./sighthound-redactor-api-examples/volumes/data/examples/dancing3/`
If you utilize AWS S3 for storing media, you may be interested in checking out our [AWS S3 Auto Redaction example](aws-s3-auto-redact.md).
Supported `outputUri` formats include:
- File System Path
`file:///path/to/my-video.mp4` or `file:///path/to/my-bucket/`
- Windows File Path
`file:///C:/path/to/my-video.mp4` or `file:///C:/path/to/my-bucket/`
- File Share Path
`file://hostname/path/to/my-video.mp4` or `file://hostname/path/to/my-bucket/`
- 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...`
- AWS S3
`s3://bucket-name/path/to/my-video.mp4` or `s3://bucket-name/path/to/my-bucket/`
Redactor determines whether to output only the redacted video or all of the redaction state if the outputUri ends in a trailing slash. If so, it will output all of the redaction state, including the redacted video named redacted.mp4. If there is no trailing slash, Redactor will name the redacted video with your provided filename.
### Load Video into a Folder
To keep things organized, a path can be specified to place the video into a folder. These folders are used solely for organization in the UI. Note that a folder will never be empty unless it contains other non-empty folders. Additionally, users can move media files between folders during editing.
Here, we’re placing our video into the nested folder `2024/review/`:
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": [
"MEDIA_PREPARE"
],
"videoContext": {
"prepareConfig": {
"metadata": {
"etc_media_path": ["2024", "review"]
}
}
}
}'
```
### Display custom video name
The name displayed in the editor defaults to the filename of the video, but you can set a custom display name for the video by providing `etc_media_title`.
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": [
"MEDIA_PREPARE"
],
"videoContext": {
"prepareConfig": {
"metadata": {
"etc_media_title": "my custom video name"
}
}
}
}'
```
### Using Custom Session IDs
Every video loaded into Redactor creates a unique "session" that is referenced internally by a `sessionId`. By default, Redactor automatically generates these IDs, but you can specify your own custom `sessionId` when loading a video. This is particularly useful when you need to make multiple API calls over the lifetime of a redaction session that target the same video.
For example, you might load a video with `MEDIA_PREPARE` and specify a custom `sessionId`. A user can then make edits in the Redactor UI editor. Later, you can make another API call from your backend to render the redacted video and output it to a specific location—all by referencing the same `sessionId`.
**Step 1: Load a video with a custom sessionId**
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": [
"MEDIA_PREPARE"
],
"videoContext": {
"prepareConfig": {
"sessionId": "my-media-id1"
}
}
}'
```
The video is now loaded and ready for editing in the UI, with the session identified by `my-media-id1`.
**Step 2: Render the redacted video using the sessionId**
After the user has completed their edits, you can trigger a render and export by referencing the session using the `session://` URI scheme:
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "session://my-media-id1",
"features": [
"MEDIA_RENDER"
],
"outputUri": "file:///data/my-media-id1/redacted.mp4"
}'
```
This approach gives you full control over the video processing workflow while maintaining a clear reference to each video session throughout its lifecycle.
### Assign video to a user
This will load a video and assign it to one or more specified Redactor users. By default, users in Redactor's User group can only see videos they've personally uploaded or that they've been assigned to.
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": [
"MEDIA_PREPARE"
],
"acl": [
"username1",
"username2@domain.local"
]
}'
```
### Prevent Download or Deletion
If you want to prevent users from deleting videos from Redactor or being able to download the redacted videos, you can set `etc_customize.export.download` and `etc_customize.export.remove` to `hide`. This example also displays a new "save" button which emits a click event when clicked.
```sh
curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourRedactorApiToken' \
--data-raw '{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": [
"MEDIA_PREPARE"
],
"videoContext": {
"prepareConfig": {
"metadata": {
"etc_customize": {
"export": {
"download": "hide",
"save": "show"
},
"session": {
"remove": "hide",
"deleteRedactionData": "show"
}
}
}
}
}
}'
```
### Receive Webhook Notifications
Webhook notifications can be enabled using the `notifications` property as part of your API request. It's recommended that `COMPLETION` events are used, but `START` and `PROGRESS` are available if they also fit your use case. The Redactor server will POST messages that contain the same content as Get Operation Status above to the `uri` you provide.
Here is an example of what a request body may look like with webhooks:
```json
{
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"features": ["MEDIA_PREPARE"],
"videoContext": {
"prepareConfig": {
"sessionId": "my-media-id51"
}
},
"notifications": [{
"method": "HTTP_POST",
"uri": "https://webhook.site/6e1c31c1-70e0-46c5-a9d3-a5b967a74c6c",
"events": ["COMPLETION"]
}]
}
```
And the data sent to the webhook will look like this:
```json
{
"done": true,
"metadata": {
"@type": "sighthound.redactor.v11.Progress",
"progress": {
"inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
"progressPercent": 100,
"startTime": "2025-12-16T15:53:40.577Z",
"updateTime": "2025-12-16T15:53:44.774Z",
"sessionId": "my-media-id51"
}
},
"name": "projects/0/locations/0/operations/93a522407f26",
"response": {
"@type": "sighthound.redactor.v11.ProcessResponse",
"processResult": {
"outputUri": ""
}
}
}
```
When the `done` value is `true`, the operation is complete, and either a `response` or `error` property will exist to indicate success or failure.
### Next Steps
Use the reference page below when you need the full list of request options, supported features, and response fields for `videos:process`.
Please review the [Redactor API Reference](../reference/videos/process.md){target=apireference} for more information on the available options.
## Advanced Examples
We have a few more examples that show how to use Redactor in more advanced scenarios.
### AWS S3 Auto Redaction
The [AWS S3 Auto Redaction example](aws-s3-auto-redact.md) shows how to set up a fully-automated redaction workflow where videos that are placed in an "input" AWS S3 bucket will be automatically redacted and sent to an "output" S3 bucket.
### Embed Redactor UI in your App
The [Embedded Redactor UI](embedded-ui.md) guide shows how to embed the Redactor editor into your own web application, including same-domain and cross-domain deployment options.
## Development Support
### TypeScript
Type definitions for the Redactor API are available here: [sh-types_3.1.0.zip](../../bin/sh-types_3.1.0.zip). TypeScript types are also included in the [Redactor Agent Toolkit](../reference/agent-toolkit.md).
Please refer to the `README.md` in the ZIP file on how to add it to your own project.
---
# 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.