Video Background Removal

Removing background from videos takes longer time than images relatively. Therefore, the video background removal API is designed in such a way that users are able to obtain results in asynchronous mode. Overall, three interfaces are provided for users to carry out video background removal tasks per the need.

API documentation

Interface for removing background from the submitted video：

• Request URL: https://www.cutout.pro/api/v1/video/submitTaskByUrl
• Request method: GET
• Return type: json data
• Input parameters:

(1)Request parameters (Header)

Parameter	Parameter Type	Description
APIKEY	string	Your API Key

(2) Query String

Parameter	Parameter Type	Description
videoUrl	url	the URL of a video or a GIF, required
outputFormat	string	output format of the result video, valid values are: webm, mov. The default output format is mov.

(3) Response data

 {
    "code":0, // 0 indicates success, and the other values are the corresponding error codes
    "data":{
        "taskFlag": "08ba8388bdb54498a3bb0fc92ce2341e" //The task id of the submission
    }, 
    "msg":null, // if code is not 0, the error msg of the error
    "time": 1615368038661 // the unix timestamp of server
 }

Sample Code

bash

curl -H 'APIKEY: INSERT_YOUR_API_KEY_HERE' \
  'https://www.cutout.pro/api/v1/video/submitTaskByUrl?videoUrl=xxxx&outputFormat=mov'

python

  import requests
  response = requests.get(
  	'https://www.cutout.pro/api/v1/video/submitTaskByUrl?videoUrl=xxxx&outputFormat=mov',
  	headers={'APIKEY': 'INSERT_YOUR_API_KEY_HERE'},
  )

php

  $client = new GuzzleHttp\Client();
  $res = $client->get('https://www.cutout.pro/api/v1/video/submitTaskByUrl?videoUrl=xxxx&outputFormat=mov', [
  	'headers' => [
  		'APIKEY' => 'INSERT_YOUR_API_KEY_HERE'
  	]
  ]);

java

  CloseableHttpClient client = HttpClients.createDefault();
  URIBuilder uriBuilder = new URIBuilder("https://www.cutout.pro/api/v1/video/submitTaskByUrl");
  uriBuilder.addParameter("videoUrl", "video url");
  uriBuilder.addParameter("outputFormat", "mov");
  HttpGet httpGet = new HttpGet(uriBuilder.build());
  httpGet.setHeader("APIKEY", "INSERT_YOUR_API_KEY_HERE");

  try (CloseableHttpResponse response = client.execute(httpGet)){
  	if (response.getStatusLine().getStatusCode() == HttpStatusCode.OK) {
  		//todo your logic
  	}
  } catch (IOException e) {
  	e.printStackTrace();
  }

nodejs

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

  request.get({
    url: 'https://www.cutout.pro/api/v1/video/submitTaskByUrl?videoUrl=xxxx&outputFormat=mov',
    headers: {
  	'APIKEY': 'INSERT_YOUR_API_KEY_HERE'
    },
    encoding: null
  }, function(error, response, body) {
    // console.log(response);
  });

Interface for obtaining asynchronous webhook notifications：

• A specified API address is required to be provided to receive asynchronous notifications, Notifications are returned in json format and posted to the specified address.
• Since webhooks are not yet a common demand, there is currently no management interface to set the webhook address. Currently, you can send an email to tech@cutout.pro and the technicians will set it up in the internal system.
• json exmple:

{
    "eventName":"EVENT_VIDEO_TASK_FINISHED",
    "eventData": {
        "taskFlag": "08ba8388bdb54498a3bb0fc92ce2341e",
        "resultUrl": "http://xxxxxxxxxxx", //the resulting video url with background removed
        "status": "done"
    }
}

Interface for checking task status：

• Request URL: https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx
• Request method: GET
• Input parameters:

(1) Request parameters (Header)

Parameter	Parameter Type	Description
APIKEY	string	Your API key

(2) Query String

Parameter	Parameter Type	Description
taskFlag	string	the task id returned by the submission

(3) Response data

{
    "code":0, //0 indicates success, and the other values are the corresponding error codes
    "data":{
        "taskFlag": "08ba8388bdb54498a3bb0fc92ce2341e",
        "resultUrl": "http://xxxxxxxxxxx", //the resulting video url with background removed
        "status": "done", //valid values are: processing, done
        "percentage": "100", //Indicates the percentage of task completion
    },
    "msg":"error msg",if code is not 0, the error msg of the error
    "time": 1615368038661the unix timestamp of server
}

Sample Code

bash

curl -H 'APIKEY: INSERT_YOUR_API_KEY_HERE' \
  'https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx'

python

  import requests
  response = requests.get(
  	'https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx',
  	headers={'APIKEY': 'INSERT_YOUR_API_KEY_HERE'},
  )

php

  $client = new GuzzleHttp\Client();
  $res = $client->get('https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx', [
  	'headers' => [
  		'APIKEY' => 'INSERT_YOUR_API_KEY_HERE'
  	]
  ]);

java

  CloseableHttpClient client = HttpClients.createDefault();
  
  HttpGet httpGet = new HttpGet("https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx");
  httpGet.setHeader("APIKEY", "INSERT_YOUR_API_KEY_HERE");

  try (CloseableHttpResponse response = client.execute(httpGet)){
  	if (response.getStatusLine().getStatusCode() == HttpStatusCode.OK) {
  		//todo your logic
  	}
  } catch (IOException e) {
  	e.printStackTrace();
  }

nodejs

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

  request.get({
    url: 'https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx',
    headers: {
  	'APIKEY': 'INSERT_YOUR_API_KEY_HERE'
    },
    encoding: null
  }, function(error, response, body) {
    // console.log(response);
  });

Interface for preview the frame images of the video after removing background：

• Request URL: https://www.cutout.pro/api/v1/video/submitVideoImagePreviewTaskByUrl
• Request method: GET
• Input parameters:

(1) Request parameters (Header)

Parameter	Parameter Type	Description
APIKEY	string	Your API key

(2) Query String

Parameter	Parameter Type	Description
videoUrl	string	the URL of a video or a GIF, required

(3) Response data

{
    "code":0, //0 indicates success, and the other values are the corresponding error codes
    "data":{
    "taskFlag": "08ba8388bdb54498a3bb0fc92ce2341e" //The task id of the submission、
    },
    "msg":"msg", //if code is not 0, the error msg of the error
    "time": 1615368038661 //the unix timestamp of server
}

Sample Code

bash

curl -H 'APIKEY: INSERT_YOUR_API_KEY_HERE' \
  'https://www.cutout.pro/api/v1/video/submitVideoImagePreviewTaskByUrl?videoUrl=xxxx'

python

  import requests
  response = requests.get(
  	'https://www.cutout.pro/api/v1/video/submitVideoImagePreviewTaskByUrl?videoUrl=xxxx',
  	headers={'APIKEY': 'INSERT_YOUR_API_KEY_HERE'},
  )

php

  $client = new GuzzleHttp\Client();
  $res = $client->get('https://www.cutout.pro/api/v1/video/submitVideoImagePreviewTaskByUrl?videoUrl=xxxx', [
  	'headers' => [
  		'APIKEY' => 'INSERT_YOUR_API_KEY_HERE'
  	]
  ]);

java

  CloseableHttpClient client = HttpClients.createDefault();
  
  HttpGet httpGet = new HttpGet("https://www.cutout.pro/api/v1/video/submitVideoImagePreviewTaskByUrl?videoUrl=xxxx");
  httpGet.setHeader("APIKEY", "INSERT_YOUR_API_KEY_HERE");

  try (CloseableHttpResponse response = client.execute(httpGet)){
  	if (response.getStatusLine().getStatusCode() == HttpStatusCode.OK) {
  		//todo your logic
  	}
  } catch (IOException e) {
  	e.printStackTrace();
  }

nodejs

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

  request.get({
    url: 'https://www.cutout.pro/api/v1/video/submitVideoImagePreviewTaskByUrl?videoUrl=xxxx',
    headers: {
  	'APIKEY': 'INSERT_YOUR_API_KEY_HERE'
    },
    encoding: null
  }, function(error, response, body) {
    // console.log(response);
  });

Interface for checking preview task status：

• Request URL: https://www.cutout.pro/api/v1/video/getVideoImagePreviewTaskInfo?taskFlag=xxxx
• Request method: GET
• Input parameters:

(1) Request parameters (Header)

Parameter	Parameter Type	Description
APIKEY	string	Your API key

(2) Query String

Parameter	Parameter Type	Description
taskFlag	string	the task id returned by the submission

(3) Response data

{
    "code":0,0 indicates success, and the other values are the corresponding error codes
    "data":{
        "taskFlag": "08ba8388bdb54498a3bb0fc92ce2341e",
        "previewImage": [
            {
                "time": 1.2, //the time of the video frame
                "image":"http://xxxxxxxxxxx", //the image of the original video frame
                "matting": "http://xxxxxxxxxxx" //the image after background removal
            },
            {
                "time": 2.3, //the time of the video frame
                "image":"http://xxxxxxxxxxx", //the image of the original video frame
                "matting": "http://xxxxxxxxxxx" //the image after background removal
            },
            ...
        ],
        "status": "done",valid values are: processing, done
    },
    "msg":"error msg", //if code is not 0, the error msg of the error
    "time": 1615368038661 //the unix timestamp of server
}

Sample Code

bash

curl -H 'APIKEY: INSERT_YOUR_API_KEY_HERE' \
  'https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx'

python

  import requests
  response = requests.get(
  	'https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx',
  	headers={'APIKEY': 'INSERT_YOUR_API_KEY_HERE'},
  )

php

  $client = new GuzzleHttp\Client();
  $res = $client->get('https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx', [
  	'headers' => [
  		'APIKEY' => 'INSERT_YOUR_API_KEY_HERE'
  	]
  ]);

java

  CloseableHttpClient client = HttpClients.createDefault();
  
  HttpGet httpGet = new HttpGet("https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx");
  httpGet.setHeader("APIKEY", "INSERT_YOUR_API_KEY_HERE");

  try (CloseableHttpResponse response = client.execute(httpGet)){
  	if (response.getStatusLine().getStatusCode() == HttpStatusCode.OK) {
  		//todo your logic
  	}
  } catch (IOException e) {
  	e.printStackTrace();
  }

nodejs

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

  request.get({
    url: 'https://www.cutout.pro/api/v1/video/getTaskInfo?taskFlag=xxxx',
    headers: {
  	'APIKEY': 'INSERT_YOUR_API_KEY_HERE'
    },
    encoding: null
  }, function(error, response, body) {
    // console.log(response);
  });