Tools / Upload API

Upload API

Introduction

The Upload API allows you to upload media files, and then later interact with them for instance with the Moderation or Redaction APIs.

There are two types of situations where you would want to use the Upload API:

when a video is too large for the standard APIs (more than 50 megabytes). The Upload API supports uploads of video files that are hundreds of megabytes in size
when you want to create an authenticated upload URL for your client applications, so that content can be uploaded directly to Sightengine without needing any intermediary steps.

1. Create an authenticated Sightengine upload URL

The first step is to create a new Upload URL. You can do so by sending a GET request to the create-video endpoint as shown below. The Sightengine API will return:

an authenticated URL that you can use to upload content directly, either from your server or from client apps
a media id that you can use to later interact with the uploaded media.

Remember: this upload URL must be used only once. If you need to upload multiple files, you will need to request multiple signed URLs, one for each file.

Here is an example code to create a new Upload URL:


curl -X GET -G 'https://api.sightengine.com/1.0/upload/create-video.json' \
  -d 'api_user={api_user}' \
  -d 'api_secret={api_secret}'


# this example uses requests
import requests
import json

params = {'api_user': '{api_user}', 'api_secret': '{api_secret}'}
r = requests.get('https://api.sightengine.com/1.0/upload/create-video.json', params=params)

output = json.loads(r.text)


$params = array(
  'api_user' => '{api_user}',
  'api_secret' => '{api_secret}',
);

// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/upload/create-video.json?'.http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$output = json_decode($response, true);


// this example uses axios
const axios = require('axios');

axios.get('https://api.sightengine.com/1.0/upload/create-video.json', {
  params: {
    'api_user': '{api_user}',
    'api_secret': '{api_secret}',
  }
})
.then(function (response) {
  // on success: handle response
  console.log(response.data);
})
.catch(function (error) {
  // handle error
  if (error.response) console.log(error.response.data);
  else console.log(error.message);
});

The Sightengine API will immediately return a JSON response containing the signed upload URL and the media id as shown in the example below:

            
            
{
    "status": "success",
    "request": {
        "id": "req_ak81yRMJAaaKkJQmHHt4R",
        "timestamp": 1630868261.426966,
        "operations": 0
    },
    "upload": {
        "url": "https://storage-eu1.sightengine.com/u/cb5.....",
        "expires": 1630954661
    },
    "media": {
        "id": "med_ak81dAMd3LkZzUVoDFl3a"
    }
}

The signed URL is valid for a limited period of time. The UNIX timestamp of the expiry of the signed URL is given in the expires field.

2. Upload the Video file

Now that you have a signed upload URL. You can upload your video file directly to this URL. Make a PUT request that includes the file in the body. The URL is resumable, meaning that if your file is really large you can send your file in pieces and pause/resume at will.

An upload URL is valid only once. You need to create as many URLs as files you need to upload. If you upload multiple files to the same signed URL, you will end up overwriting the existing file, which can lead to unexpected results.


curl "{PRESIGNED_URL}" --upload-file /path/to/your/file


# this example uses requests
import requests

r = requests.put('{PRESIGNED_URL}', data=open('/path/to/your/file', 'rb'))


// this example uses cURL
$fh_res = fopen('/path/to/your/file', 'r');

$ch = curl_init('{PRESIGNED_URL}');
curl_setopt($ch, CURLOPT_PUT, true);
curl_setopt($ch, CURLOPT_INFILE, $fh_res);
curl_setopt($ch, CURLOPT_INFILESIZE, filesize('/path/to/your/file'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 60); // adapt the timeout to your file size and bandwidth
$response = curl_exec($ch);
curl_close($ch);


const fs = require('fs');
const request = require('request');

fs.createReadStream('/path/to/your/file').pipe(request.put('{PRESIGNED_URL}'));

Once the video file has been uploaded. You can start interacting with it. You can moderate the video with the Video Moderation API or redact it with the Video Redaction and Anonymization API.

3. Use the uploaded Video

Now that you have uploaded a video, you can use the video's media id to moderate the video with the Video Moderation API, redact it with the Video Redaction and Anonymization API, or use it with Video blacklists.

Here are a few examples:

Example A: Video Moderation


curl -X POST 'https://api.sightengine.com/1.0/video/check.json' \
  -F 'media_id=med_ak81dAMd3LkZzUVoDFl3a' \
  -F 'models={models}' \
  -F 'api_user={api_user}' \
  -F 'api_secret={api_secret}'


# this example uses requests
import requests
import json

params = {
  'media_id': 'med_ak81dAMd3LkZzUVoDFl3a',
  # specify the models you want to apply
  'models': '{models}',
  'api_user': '{api_user}',
  'api_secret': '{api_secret}'
}
r = requests.post('https://api.sightengine.com/1.0/video/check.json', data=params)

output = json.loads(r.text)


$params = array(
  'media_id' => 'med_ak81dAMd3LkZzUVoDFl3a',
  // specify the models you want to apply
  'models' => '{models}',
  'api_user' => '{api_user}',
  'api_secret' => '{api_secret}',
);

// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/check.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($ch);
curl_close($ch);

$output = json_decode($response, true);


// this example uses axios and form-data
const axios = require('axios');
const FormData = require('form-data');

data = new FormData();
data.append('media_id', 'med_ak81dAMd3LkZzUVoDFl3a');
// specify the models you want to apply
data.append('models', '{models}');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');

axios({
  method: 'post',
  url:'https://api.sightengine.com/1.0/video/check.json',
  data: data,
  headers: data.getHeaders()
})
.then(function (response) {
  // on success: handle response
  console.log(response.data);
})
.catch(function (error) {
  // handle error
  if (error.response) console.log(error.response.data);
  else console.log(error.message);
});

Example B: Video Redaction


curl -X POST 'https://api.sightengine.com/1.0/video/transform.json' \
    -F 'media_id=med_ak81dAMd3LkZzUVoDFl3a' \
    -F 'concepts={models}' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}'


# this example uses requests
import requests
import json

params = {
  'media_id': 'med_ak81dAMd3LkZzUVoDFl3a',
  'concepts': '{models}',
  'api_user': '{api_user}',
  'api_secret': '{api_secret}'
}
r = requests.post('https://api.sightengine.com/1.0/video/transform.json', data=params)

output = json.loads(r.text)


$params = array(
  'media_id' => 'med_ak81dAMd3LkZzUVoDFl3a',
  'concepts' => '{models}',
  'api_user' => '{api_user}',
  'api_secret' => '{api_secret}',
);

// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/transform.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($ch);
curl_close($ch);

$output = json_decode($response, true);


// this example uses axios and form-data
const axios = require('axios');
const FormData = require('form-data');

data = new FormData();
data.append('media_id', 'med_ak81dAMd3LkZzUVoDFl3a');
data.append('concepts', '{models}');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');

axios({
  method: 'post',
  url:'https://api.sightengine.com/1.0/video/transform.json',
  data: data,
  headers: data.getHeaders()
})
.then(function (response) {
  // on success: handle response
  console.log(response.data);
})
.catch(function (error) {
  // handle error
  if (error.response) console.log(error.response.data);
  else console.log(error.message);
});

Example C: Add to a Video List


curl -X POST 'https://api.sightengine.com/1.0/video/add-to-list.json' \
    -F 'media_id=med_ak81dAMd3LkZzUVoDFl3a' \
    -F 'add_to_list={list_id}' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}'


# this example uses requests
import requests
import json

params = {
  'media_id': 'med_ak81dAMd3LkZzUVoDFl3a',
  'add_to_list': '{list_id}',
  'api_user': '{api_user}',
  'api_secret': '{api_secret}'
}
r = requests.post('https://api.sightengine.com/1.0/video/add-to-list.json', data=params)

output = json.loads(r.text)


$params = array(
  'media_id' => 'med_ak81dAMd3LkZzUVoDFl3a',
  'add_to_list' => '{list_id}',
  'api_user' => '{api_user}',
  'api_secret' => '{api_secret}',
);

// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/add-to-list.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($ch);
curl_close($ch);

$output = json_decode($response, true);


// this example uses axios and form-data
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

data = new FormData();
data.append('media_id', 'med_ak81dAMd3LkZzUVoDFl3a');
data.append('add_to_list', '{list_id}');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');

axios({
  method: 'post',
  url:'https://api.sightengine.com/1.0/video/add-to-list.json',
  data: data,
  headers: data.getHeaders()
})
.then(function (response) {
  // on success: handle response
  console.log(response.data);
})
.catch(function (error) {
  // handle error
  if (error.response) console.log(error.response.data);
  else console.log(error.message);
});

Example D: Search for matches in a Video List


curl -X POST 'https://api.sightengine.com/1.0/video/check-list.json' \
    -F 'media_id=med_ak81dAMd3LkZzUVoDFl3a' \
    -F 'lists={list_id}' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}'


# this example uses requests
import requests
import json

params = {
  'media_id': 'med_ak81dAMd3LkZzUVoDFl3a',
  'lists': '{list_id}',
  'api_user': '{api_user}',
  'api_secret': '{api_secret}'
}

r = requests.post('https://api.sightengine.com/1.0/video/check-list.json', data=params)

output = json.loads(r.text)


$params = array(
  'media_id' => 'med_ak81dAMd3LkZzUVoDFl3a',
  'lists' => '{list_id}',
  'api_user' => '{api_user}',
  'api_secret' => '{api_secret}',
);

// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/check-list.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($ch);
curl_close($ch);

$output = json_decode($response, true);


// this example uses axios and form-data
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

data = new FormData();
data.append('media_id', 'med_ak81dAMd3LkZzUVoDFl3a');
data.append('lists', '{list_id}');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');

axios({
  method: 'post',
  url:'https://api.sightengine.com/1.0/video/check-list.json',
  data: data,
  headers: data.getHeaders()
})
.then(function (response) {
  // on success: handle response
  console.log(response.data);
})
.catch(function (error) {
  // handle error
  if (error.response) console.log(error.response.data);
  else console.log(error.message);
});

Was this page helpful?

Products

MODERATION

REDACTION

REFERENCE

Upload API

Introduction

1. Create an authenticated Sightengine upload URL

2. Upload the Video file

3. Use the uploaded Video

Example A: Video Moderation

Example B: Video Redaction

Example C: Add to a Video List

Example D: Search for matches in a Video List