Skip to content

Redactor API Basics

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 get you started quickly, we've put together a zip file (sighthound-redactor-api-examples.zip) which uses the Docker version of Redactor and contains various config files used in our examples. Contact sales@sighthound.com to obtain this file 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 using our example zip:

  • Extract sighthound-redactor-api-examples.zip to your computer
  • cd into the newly created 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

Inside of the sighthound-redactor-api-examples.zip folder, there is a folder at ./volumes/data/ that will be mounted into the Redactor container at the /data/ path. This will be used as an output location in several of the examples, and you'll have easy access to it from your host to review the results. There is also a ./volumes/redactor/ folder that stores all of the application state and logs files. If you're encountering into any issues, you can review the log file at ./volumes/redactors/logs/main.log or send it to support@sighthound.com for assistance.

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.

curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json'  --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 FACE_DETECTION and LICENSE_PLATE_DETECTION features. Note: MEDIA_PREPARE does not need to be specified if other features are listed. 

curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json'  --data-raw '{
    "inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
    "features": ["FACE_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
  • FACE_DETECTION - Detect faces
  • VEHICLE_DETECTION - Detect vehicles
  • LICENSE_PLATE_DETECTION - Detect vehicle license plates
  • SPEECH_TRANSCRIPTION - Transcribe the words spoken in a video for a specified language. (Requires Redactor 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 faces, 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. 

curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json'  --data-raw '{
    "inputUri": "https://sh-io-downloads.s3.amazonaws.com/videos/Dancing.mp4",
    "features": ["MEDIA_PREPARE", "FACE_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 utiltize AWS S3 for storing media, you may be interested in checking out our AWS S3 Auto Redaction example.

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.

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.

curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json'  --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"
      }
    }
  }
}'

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.

curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json'  --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.

curl --location --request POST 'http://localhost:9000/api/v1/videos:process' \
--header 'Content-Type: application/json'  --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:

{
   "features": ["MEDIA_PREPARE"],
   "inputUri": "https://example.com/path/to/video1.mp4",
   "notifications": [{
      "method": "HTTP_POST",
      "uri": "https://example.com/mywebhook/endpoint",
      "events": ["START", "PROGRESS", "COMPLETION"]
   }],
   "videoContext": {
        "prepareConfig": {
            "sessionId": "my-media-id1"
        }
   },
   "projectId": "my-project-id"
}

And the data sent to the webhook will look like this:

{
   "name": "projects/{project-id}/locations/{location-id}/operations/{operation-id}",
   "metadata": {
       "@type": "sighthound.cloud.v1.Progress",
       "progress": {
           "inputUri": "http://example.com/path/to/video1.mp4",
           "progressPercent": 100,
           "startTime": "2020-04-01T22:13:17.978847Z",
           "updateTime": "2020-04-01T22:13:29.576004Z"
       }
   },
   "done": true,
   "response": {
       "@type": "sighthound.cloud.v1.videos.ProcessResponse",
       "processResults": {
           "outputUri": "https://{your-azure-account}.blob.core.windows.net/{container-name}/{video-2-data}/"
       },
       "tag": {
        "your": "custom string, object, or array"
       }
   }
}

When the done value is true, the operation is complete, and either a response or error property will exist to indicate success or failure.

Your Example Here!

More examples are coming soon, but let us know if you'd like to see anything specific by reaching out to support@sighthound.com.

Please review the Redactor API Reference 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 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 with Multi-Video Projects example shows how to embed the Redactor UI into your own web application.