Face Cutout

Get API Key

It automatically segments the face and hair of a person or a pet (cat or dog) in the photo with great accuracy and fast speed. It is suitable for applications including print-on-demand (POD), emojis, avatars, headshot profile pictures, etc.

API Mode 1 : Return binary stream

Sample Code

curl -H 'APIKEY: INSERT_YOUR_API_KEY_HERE' \
  -F 'file=@/path/to/file.jpg'     \
  -f 'https://www.cutout.pro/api/v1/matting?mattingType=3&crop=true' \
  -o out.png

  import requests
  response = requests.post(
    'https://www.cutout.pro/api/v1/matting?mattingType=3',
    files={'file': open('/path/to/file.jpg', 'rb')},
    headers={'APIKEY': 'INSERT_YOUR_API_KEY_HERE'},
  )
  with open('out.png', 'wb') as out:
    out.write(response.content)

  $client = new GuzzleHttp\Client();
  $res = $client->post('https://www.cutout.pro/api/v1/matting?mattingType=3', [
    'multipart' => [
        [
            'name'     => 'file',
            'contents' => fopen('/path/to/file.jpg', 'r')
        ]
    ],
    'headers' => [
        'APIKEY' => 'INSERT_YOUR_API_KEY_HERE'
    ]
  ]);

  $fp = fopen("out.png", "wb");
  fwrite($fp, $res->getBody());
  fclose($fp);

  File file = new File("/Your/Image/File/Path");
  
  CloseableHttpClient client = HttpClients.createDefault();
  
  HttpPost httpPost = new HttpPost("https://www.cutout.pro/api/v1/matting?mattingType=3");
  httpPost.setHeader("APIKEY", "INSERT_YOUR_API_KEY_HERE");
  
  MultipartEntityBuilder multipartEntityBuilder = MultipartEntityBuilder.create();
  multipartEntityBuilder.addBinaryBody("file", file);
  httpPost.setEntity(multipartEntityBuilder.build());
  
  try (CloseableHttpResponse response = client.execute(httpPost)){
    if (response.getStatusLine().getStatusCode() == HttpStatusCode.OK) {
        //save to local storage
        byte[] bytes = EntityUtils.toByteArray(response.getEntity());
        FileOutputStream outputStream = new FileOutputStream("/Image/File/Path");
        outputStream.write(bytes);
    }
  } catch (IOException e) {
    e.printStackTrace();
  }

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

  request.post({
    url: 'https://www.cutout.pro/api/v1/matting?mattingType=3',
    formData: {
    file: fs.createReadStream('/path/to/file.jpg')
    },
    headers: {
    'APIKEY': 'INSERT_YOUR_API_KEY_HERE'
    },
    encoding: null
  }, function(error, response, body) {
    // console.log(response);
  });

  using (var client = new HttpClient())
  using (var formData = new MultipartFormDataContent())
  {
    formData.Headers.Add("APIKEY", "INSERT_YOUR_API_KEY_HERE");
    formData.Add(new ByteArrayContent(File.ReadAllBytes("/path/to/file.jpg")), "file", "file.jpg");
    var response = client.PostAsync("https://www.cutout.pro/api/v1/matting?mattingType=3", formData).Result;
    if(response.IsSuccessStatusCode) {
        //todo: Handle your logic
    } else {
        //todo: Handle your logic
    }
  }

  NSURL *fileUrl = [NSBundle.mainBundle URLForResource:@"file" withExtension:@"jpg"];
  NSData *data = [NSData dataWithContentsOfURL:fileUrl];
  if (!data) {
    return;
  }

  AFHTTPSessionManager *manager =
  [[AFHTTPSessionManager alloc] initWithSessionConfiguration:
   NSURLSessionConfiguration.defaultSessionConfiguration];

  manager.responseSerializer = [AFImageResponseSerializer serializer];
  [manager.requestSerializer setValue:@"INSERT_YOUR_API_KEY_HERE"
                 forHTTPHeaderField:@"APIKEY"];

  NSURLSessionDataTask *dataTask = [manager
      POST:@"https://www.cutout.pro/api/v1/matting?mattingType=3"
      parameters:nil
      constructingBodyWithBlock:^(id  _Nonnull formData) {
          [formData appendPartWithFileData:data
                                      name:@"file"
                                  fileName:@"file.jpg"
                                  mimeType:@"image/jpeg"];
      }
      progress:nil
      success:^(NSURLSessionDataTask * _Nonnull task, id  _Nullable responseObject) {
          // Handle your logic
      } failure:^(NSURLSessionDataTask * _Nullable task, NSError * _Nonnull error) {
          // Handle your logic
      }];

  [dataTask resume];

API documentation

User requests to segments the face and hair of a person or a pet (cat or dog) from a picture, and the server returns the transparent image of face and hair in binary format.

Request description

Request URL: https://www.cutout.pro/api/v1/matting?mattingType=3
Request method: POST
Return type: PNG image
Content-Type: multipart/form-data

Input parameters:

(1) Request parameters (Header)

Parameter	Parameter Type	Description
APIKEY	string	Your API Key

Get API Key

(2) Request parameters (Body)

Parameter	Description	Required
file	Picture file	Yes
crop	Whether to crop off all empty areas (default: false). If URL parameter is used, add the “crop” parameter after the URL.	No
bgcolor	Add a solid background color to the resulting image (default: no background color specified). The color is specified in the format of hex color code (e.g., FFFFFF). If URL parameter is used, add the “bgcolor” parameter after the URL.	No
preview	When this parameter is passed in preview image processing, the maximum preview image resolution received is: 500 * 500. If the maximum preview resolution is exceeded, the image will be adjusted to 500 * 500 resolution, and the number of credits deducted from each image is: 0.25, (If this parameter is not passed or the value is false, the number of credits deducted for each image is: 1), the value type: true or false, the default value is: false	No
outputFormat	The output image format, which can be: png, webp, jpg_$quality($quality is the quality used to compress the image, the value is between 0 and 100, for example: jpg_75) the default value is: png	No

Response description

Normal return

Return an image with background removed, in binary format and the content-type is image/png.

Error return

if any error occurs, the response will be in json format.

{
  "code": 1001, //
  "data": null
  "msg": 'Insufficient balance',
  "time": 1590462453264
}

API Mode 2: Return base64 encoded string

Sample Code

curl -H 'APIKEY: INSERT_YOUR_API_KEY_HERE' \
  -F 'file=@/path/to/file.jpg'     \
  -f 'https://www.cutout.pro/api/v1/matting2?mattingType=3&crop=true' \
  -o out.png

  import requests
  response = requests.post(
    'https://www.cutout.pro/api/v1/matting2?mattingType=3',
    files={'file': open('/path/to/file.jpg', 'rb')},
    headers={'APIKEY': 'INSERT_YOUR_API_KEY_HERE'},
  )

  $client = new GuzzleHttp\Client();
  $res = $client->post('https://www.cutout.pro/api/v1/matting?mattingType=3', [
    'multipart' => [
        [
            'name'     => 'file',
            'contents' => fopen('/path/to/file.jpg', 'r')
        ]
    ],
    'headers' => [
        'APIKEY' => 'INSERT_YOUR_API_KEY_HERE'
    ]
  ]);

  File file = new File("/Your/Image/File/Path");
  
  CloseableHttpClient client = HttpClients.createDefault();
  
  HttpPost httpPost = new HttpPost("https://www.cutout.pro/api/v1/matting2?mattingType=3");
  httpPost.setHeader("APIKEY", "INSERT_YOUR_API_KEY_HERE");
  
  MultipartEntityBuilder multipartEntityBuilder = MultipartEntityBuilder.create();
  multipartEntityBuilder.addBinaryBody("file", file);
  httpPost.setEntity(multipartEntityBuilder.build());
  
  CloseableHttpResponse response = client.execute(httpPost);

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

  request.post({
    url: 'https://www.cutout.pro/api/v1/matting2?mattingType=3',
    formData: {
    file: fs.createReadStream('/path/to/file.jpg')
    },
    headers: {
    'APIKEY': 'INSERT_YOUR_API_KEY_HERE'
    },
    encoding: null
  }, function(error, response, body) {
    // console.log(response);
  });

  using (var client = new HttpClient())
  using (var formData = new MultipartFormDataContent())
  {
    formData.Headers.Add("APIKEY", "INSERT_YOUR_API_KEY_HERE");
    formData.Add(new ByteArrayContent(File.ReadAllBytes("/path/to/file.jpg")), "file", "file.jpg");
    var response = client.PostAsync("https://www.cutout.pro/api/v1/matting2?mattingType=3", formData).Result;
    if(response.IsSuccessStatusCode) {
        //todo: Handle your logic
    } else {
        //todo: Handle your logic
    }
  }

  NSURL *fileUrl = [NSBundle.mainBundle URLForResource:@"file" withExtension:@"jpg"];
  NSData *data = [NSData dataWithContentsOfURL:fileUrl];
  if (!data) {
    return;
  }

  AFHTTPSessionManager *manager =
  [[AFHTTPSessionManager alloc] initWithSessionConfiguration:
   NSURLSessionConfiguration.defaultSessionConfiguration];

  manager.responseSerializer = [AFJSONResponseSerializer serializer];
  [manager.requestSerializer setValue:@"INSERT_YOUR_API_KEY_HERE"
                 forHTTPHeaderField:@"APIKEY"];

  NSURLSessionDataTask *dataTask = [manager
      POST:@"https://www.cutout.pro/api/v1/matting2?mattingType=3"
      parameters:nil
      constructingBodyWithBlock:^(id  _Nonnull formData) {
          [formData appendPartWithFileData:data
                                      name:@"file"
                                  fileName:@"file.jpg"
                                  mimeType:@"image/jpeg"];
      }
      progress:nil
      success:^(NSURLSessionDataTask * _Nonnull task, id  _Nullable responseObject) {
          // Handle your logic
      } failure:^(NSURLSessionDataTask * _Nullable task, NSError * _Nonnull error) {
          // Handle your logic
      }];

  [dataTask resume];

API documentation

User requests to segments the face and hair of a person or a pet (cat or dog) from a picture, and the server returns the transparent image of face and hair in base64 encoded format.

Request description

Request URL: https://www.cutout.pro/api/v1/matting?mattingType=3
Request method: POST
Return type: PNG image
Content-Type: multipart/form-data

Input parameters:

(1) Request parameters (Header)

Parameter	Parameter Type	Description
APIKEY	string	Your API Key

Get API Key

(2) Request parameters (Body)

Parameter	Description	Required
file	Picture file	Yes
crop	Whether to crop off all empty areas (default: false). If URL parameter is used, add the “crop” parameter after the URL.	No
bgcolor	Add a solid background color to the resulting image (default: no background color specified). The color is specified in the format of hex color code (e.g., FFFFFF). If URL parameter is used, add the “bgcolor” parameter after the URL.	No
preview	When this parameter is passed in preview image processing, the maximum preview image resolution received is: 500 * 500. If the maximum preview resolution is exceeded, the image will be adjusted to 500 * 500 resolution, and the number of credits deducted from each image is: 0.25, (If this parameter is not passed or the value is false, the number of credits deducted for each image is: 1), the value type: true or false, the default value is: false	No
faceAnalysis	Boolean value: true or false. When true, the information with face detection points is returned.	No
outputFormat	The output image format, which can be: png, webp, jpg_$quality($quality is the quality used to compress the image, the value is between 0 and 100, for example: jpg_75) the default value is: png	No

Response description

Normal return

{
    "code": 0,
    "data": {
        "imageBase: "iVBORw0KGgo..." //base64 encoded string of the image with background removed
    },
    "msg": null,
    "time": 1590462453264
}

Information return with face detection points

{
   "code": 0,
   "data":{
      "imageBase64":"iVBORw0KGgoAAAANSUhEUgAABqMAAAg3CAYAAAC7wX7xAAAgAElE....",
      "faceAnalysis":{
          "face_num": 1, //face nums
          "faces": [  //face_num*8 array, from index order:p1(x,y),p3(x,y),p2(x,y),p4(x,y).  Please refer to the picture below!
               [
                   236.4606096446514,
                   497.67069862782955,
                   1492.7539091706276,
                   2050.210829436779,
                   236.4606096446514,
                   497.67069862782955,
                   1492.7539091706276,
                   2050.210829436779
               ]
           ]
          "point":[
             [
                [
                   213.5859375, //Coordinate x point
                   1035.0703125 //Coordinate y point
                ],
                [
                   221.80078125,
                   1219.904296875
                ]
                ......//A total of 68 points are returned. Please refer to the point picture below in the order of array index values.
             ]
          ]
      }
   },
   "msg": null,
   "time": 1620798570850
}

Point sample picture
Error return

if any error occurs, the response will be in json format.

{
  "code": 1001, //
  "data": null
  "msg": 'Insufficient balance',
  "time": 1590462453264
}

API Mode 3: Return base64 encoded via image URL

Sample Code

  curl -X GET --header 'Accept: application/json' \
  --header 'APIKEY: INSERT_YOUR_API_KEY_HERE' \
  'https://www.cutout.pro/api/v1/mattingByUrl?url=https%3A%2F%2Fd38b044pevnwc9.cloudfront.net%2Fsite%2Fen%2FcutoutImg%2Fheadcutout%2Fh-4.jpg&mattingType=3'

API documentation

User requests to segments the face and hair of a person or a pet (cat or dog) from a picture by url, and the server returns the transparent image of face and hair in base64 encoded format.

Request description

Request URL: https://www.cutout.pro/api/v1/mattingByUrl?mattingType=3
Request method: GET
Content-Type: multipart/form-data

Input parameters:

(1) Request parameters (Header)

Parameter	Parameter Type	Description
APIKEY	string	Your API Key

Get API Key

(2) Request parameters (query string)

Parameter	Description	Required
url	The URL of the source picture	Yes
crop	Whether to crop off all empty areas (default: false). If URL parameter is used, add the “crop” parameter after the URL.	No
bgcolor	Add a solid background color to the resulting image (default: no background color specified). The color is specified in the format of hex color code (e.g., FFFFFF). If URL parameter is used, add the “bgcolor” parameter after the URL.	No
preview	When this parameter is passed in preview image processing, the maximum preview image resolution received is: 500 * 500. If the maximum preview resolution is exceeded, the image will be adjusted to 500 * 500 resolution, and the number of credits deducted from each image is: 0.25, (If this parameter is not passed or the value is false, the number of credits deducted for each image is: 1), the value type: true or false, the default value is: false	No
outputFormat	The output image format, which can be: png, webp, jpg_$quality($quality is the quality used to compress the image, the value is between 0 and 100, for example: jpg_75) the default value is: png	No

Response description

Normal return

{
    "code": 0,
    "data": {
        "imageBase: "iVBORw0KGgo..." //base64 encoded string of the image with background removed
    },
    "msg": null,
    "time": 1590462453264
}

Error return

if any error occurs, the response will be in json format.

{
  "code": 1001, //
  "data": null
  "msg": 'Insufficient balance',
  "time": 1590462453264
}

Frequently asked questions

Q: What are the requirements for the input image format?
A: Support PNG, JPG, JPEG, BMP, WEBP
Q: Is there a limit to the supported image size?
A: The maximum resolution uploaded at present is 4096x4096 pixels, and the image file size is less than 15MB
Q: Request QPS limit?
A: Supports 5 simultaneous requests per second