Background removal API

The Background removal API is a GraphQL API that uses AI to remove the background from an image. It detects the most prominent object in the foreground of an image and makes the background transparent. You can then perform further processing on the image, to provide an enhanced product image, for example.

The Background removal API is now a fully supported general availability release.

Each request made to the API will use one Amplience credit.

Using the API

The API is implemented as a mutation removeBackgroundFromImage as part of the GraphQL Asset Management API.

The end point for all requests to the GraphQL Asset Management API is:

https://api.amplience.net/graphql

You can also use the API when logged in to the GraphQL playground.

Authentication

Amplience uses OAuth2 to authorize access to the GraphQL Asset Management API.

To use the API you will need an API key and secret which are used to obtain an access token from the Amplience authorization service. This token must be included in the authorization header of all requests to the Asset Management API. You can also use a personal access token instead of the API key and secret.

You can find more details on the authentication page.

Request

The removeBackgroundFromImage mutation takes two fields as input: organizationId and imageUrl.

You can use a GraphQL query to find the organization id.

If the image that you want to process is stored in Content Hub you can provide the URL as part of the inputs to the mutation. For images stored locally you can upload the file using the temporary file service.

mutation {
  removeBackgroundFromImage(
    input: {
      organizationId: "T4JnYW5penF0aW9uOm9yZ18QVUI0OU51NDF4eU4zanZQ"
      imageUrl: "<image url here>"
    }
  ) {
    imageUrl
  }
}

Response

imageUrl in the response is a URL from where you can download the image with the background removed. This is a temporary URL that will only be available for 24 hours, so you should download the file to continue to work with it.

{
  "data": {
    "removeBackgroundFromImage": {
      "imageUrl": "https://temp-file-upload.amplience.net/74537fe4-52f5-48f8-b3df-a2dc17bae455"
    }
  }
}

Usage notes

• Each request to the Background removal API will use one Amplience credit.
• The API supports images of up to 68MB. Larger images will result in a internal server error.
• The API only supports images with the RGB color space. When using images with any other color space, such as CMYK, the API will return an invalid color space error.
• If the image is stored in Content Hub, then the image URL must be published and a subdomain of amplience.net, such as cdn.media.amplience.net. Static images using bigcontent.io are also supported.
• The API does not support image URLs with custom CNAMEs, but you can still upload the file to the temporary file service.
• The API includes support for images in the following formats: JPEG, PNG, WebP, JPEG 2000, TIFF, BMP and GIF.
• The temporary file URL returned in the response will remain active for 24 hours.

Finding the organization id

You can use the following query to find the organization id to use as input for the API request.

query {
  viewer {
    organizations {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

Using the temporary file service

If the file that you want to process is not stored in Content Hub, then you can use the temporary file service to create a temporary file and pass this as a parameter to the API.

You can create a temporary file as follows:

mutation {
  createTempFileUploadUrl {
    uploadUrl
    downloadUrl
  }
}

This will return an upload URL and a download URL.

• Upload the file by making a PUT request to the upload URL we gave you with the file bytes in the request
• Call the Background removal API passing the download URL.

Note that when uploading to the temporary file service you need to ensure that the Content-Type header is set to a valid format for the image: image/jpeg or image/png, for example.

Example

We want to remove the background from the following image.

This image is stored in Content Hub with the URL: https://cdn.media.amplience.net/i/ampproduct/wooden-stool-unsplash

The following query will send a request to the background remover service to remove the background from the image:

mutation {
  removeBackgroundFromImage(
    input: {
      organizationId: "T4JnYW5penF0aW9uOm9yZ18QVUI0OU51NDF4eU4zanZQ"
      imageUrl: "https://cdn.media.amplience.net/i/ampproduct/wooden-stool-unsplash"
    }
  ) {
    imageUrl
  }
}

The URL of a temporary file is returned in the response.

{
  "data": {
    "removeBackgroundFromImage": {
      "imageUrl": "https://temp-file-upload.amplience.net/fd6dd2c8-6cef-4922-9a53-f97eaa718a4c"
    }
  }
}

The returned image has the background removed.

Example using the temp file service

In this example we'll upload an image stored locally to the temporary file service and then send the temporary file URL to the Background removal API.

Generate a temporary file URL

To generate a temporary URL we use the createTempFileUploadUrl mutation:

mutation {
  createTempFileUploadUrl {
    uploadUrl
    downloadUrl
  }
}

uploadUrl and downloadUrl are returned in the response.

{
  "data": {
    "createTempFileUploadUrl": {
      "uploadUrl": "https://temp-file-upload.amplience.net/52a39c0c-f30a-492e-8eaa-106e23e14daa/WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ29udGVudC1TaGEyNTY9VU5TSUdORUQtUEFZTE9BRCZYLUFtei1DcmVkZW50aWFsPUFTSUFSWlNPVlNXVUpTN040SDdYJTJGMjAyMzExMDklMkZldS13ZXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjMxMTA5VDE3NDA1NlomWC1BbXotRXhwaXJlcz0zNjAwJlgtQW16LVNlY3VyaXR5LVRva2VuPUlRb0piM0pwWjJsdVgyVmpFS0glMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkZ3RWFDV1YxTFhkbGMzUXRNU0pHTUVRQ0lGJTJGMlFWbjNIQWY3bHJnQnY3ellLZGNnUVpzJTJGQUV5SUJVJTJCWk96VjN3S0lXQWlBYjElMkJrQkFnNVN4TUxZUHN6Wnh0MktEVUdkN25JdWVwYkdpWGROWWpmJTJGbkNxSEF3alolMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkY4QkVBTWFEREV5TXpZME5UTXdNakU0TkNJTXdobWF0WkN3ZXF4cEpQNFZLdHNDeWFHaUNDVWtHb2ZHWmZkJTJGaHk0RkduQ1MyNEZ0UDJCeXFmaHNidmolMkZHbTloWEVhajlBR2pnMzVNM2pKZU9YNjBGQ2RHeFNNOCUyQkFOSnlQZWRoYjVUWDRBbEFEZ0xKZUc1QjltU1AyOUhNanl5SVVqZ3hYeVNyb053SHBWVERuUDNueElqUldUaHNsVzYyS2JWaFIlMkZNQkclMkZjdyUyRmhwZDMyaFE2R08xdEpjUHRwUmVOY0t0VWglMkZTWEVnTmR2aUF5alRBeG0xd2J1emNveTFVcko1TUhzRTJPNDBCY0xuVFIwbUx3WXl1azNjVzVrUm9sViUyRjVtQnpZNngxQVhDJTJGZmwlMkIwTzVBJTJCakxJOTRKQlNrVnFEZGZjNTByT1ByeXJGdW5xQlFET2ltd1BtS3hlMzJWN0xIcUg3RmMlMkZ5NCUyQk9YNzlhYzBLVlVQbG8lMkJYSzh5emxjOWN1WWVBM2lhMGRobmxVbmVqQWxuUjlhcUZHWDNoUTNUbEhHVGNrbFl3d3duM0JoczhHT3p2TTVkS2FkOTMlMkIzbkRkdG9QMG1yMkthVkNxV2dnOGxLeXZtZ2tLbGlCNGR5YjVvUERzJTJCallNdmpzNXQ1aHVqMFJIdkk3YyUyQkJKSnN3elltMHFnWTZud0hHMFQ1cFBUWGNrWmVrUWE1RGNoeDVBNmFZaTFkS3B2NSUyQlFJTXlsd1RhQ1pXajZFUUVDNTI1Y1pHaUIwQlRYdzdtV3dBZ0gxcU9HRWNUVUl2NFNsJTJGV2pjVmVmaW5lcjZCb1czM2JNeGE0Um1sSmVGbUhsNUxCQ3F1OXpuTXpYTkdmRklNcXJvTG5DajFqVTE5ZVhKYW1KWjFoMHhtUW0zciUyRmNIa0hCQTAxUCUyQjlHT3FrZ3N6S3UlMkJvcDQ2elNwZlJUNmRUQ0xIVjN1TzBoV1JVMWFZMFElM0QmWC1BbXotU2lnbmF0dXJlPTVmZmEzODliNDAwNGVkNDliZjU2YzRkN2NlNTM5NzMyMGRkNTdkMTc2ZDBjYTQwZDEzMzUxOTY3NGQ2OWI5MjUmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JngtaWQ9UHV0T2JqZWN0",
      "downloadUrl": "https://temp-file-upload.amplience.net/52a39c0c-f30a-492e-8eaa-106e23e14daa"
    }
  }
}

Upload the image to the temporary file URL

Send a PUT request to upload to the temp file. This example uses cURL, but apart from your own code you could also use API tools such as Postman or Insomnia to send a PUT request. Note that you must set content-type to one of the supported image types- in this case image/jpg.

The filename is woman-black-beret.jpg.

curl https://temp-file-upload.amplience.net/52a39c0c-f30a-492e-8eaa-106e23e14daa/WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ29udGVudC1TaGEyNTY9VU5TSUdORUQtUEFZTE9BRCZYLUFtei1DcmVkZW50aWFsPUFTSUFSWlNPVlNXVUpTN040SDdYJTJGMjAyMzExMDklMkZldS13ZXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjMxMTA5VDE3NDA1NlomWC1BbXotRXhwaXJlcz0zNjAwJlgtQW16LVNlY3VyaXR5LVRva2VuPUlRb0piM0pwWjJsdVgyVmpFS0glMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkZ3RWFDV1YxTFhkbGMzUXRNU0pHTUVRQ0lGJTJGMlFWbjNIQWY3bHJnQnY3ellLZGNnUVpzJTJGQUV5SUJVJTJCWk96VjN3S0lXQWlBYjElMkJrQkFnNVN4TUxZUHN6Wnh0MktEVUdkN25JdWVwYkdpWGROWWpmJTJGbkNxSEF3alolMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkYlMkY4QkVBTWFEREV5TXpZME5UTXdNakU0TkNJTXdobWF0WkN3ZXF4cEpQNFZLdHNDeWFHaUNDVWtHb2ZHWmZkJTJGaHk0RkduQ1MyNEZ0UDJCeXFmaHNidmolMkZHbTloWEVhajlBR2pnMzVNM2pKZU9YNjBGQ2RHeFNNOCUyQkFOSnlQZWRoYjVUWDRBbEFEZ0xKZUc1QjltU1AyOUhNanl5SVVqZ3hYeVNyb053SHBWVERuUDNueElqUldUaHNsVzYyS2JWaFIlMkZNQkclMkZjdyUyRmhwZDMyaFE2R08xdEpjUHRwUmVOY0t0VWglMkZTWEVnTmR2aUF5alRBeG0xd2J1emNveTFVcko1TUhzRTJPNDBCY0xuVFIwbUx3WXl1azNjVzVrUm9sViUyRjVtQnpZNngxQVhDJTJGZmwlMkIwTzVBJTJCakxJOTRKQlNrVnFEZGZjNTByT1ByeXJGdW5xQlFET2ltd1BtS3hlMzJWN0xIcUg3RmMlMkZ5NCUyQk9YNzlhYzBLVlVQbG8lMkJYSzh5emxjOWN1WWVBM2lhMGRobmxVbmVqQWxuUjlhcUZHWDNoUTNUbEhHVGNrbFl3d3duM0JoczhHT3p2TTVkS2FkOTMlMkIzbkRkdG9QMG1yMkthVkNxV2dnOGxLeXZtZ2tLbGlCNGR5YjVvUERzJTJCallNdmpzNXQ1aHVqMFJIdkk3YyUyQkJKSnN3elltMHFnWTZud0hHMFQ1cFBUWGNrWmVrUWE1RGNoeDVBNmFZaTFkS3B2NSUyQlFJTXlsd1RhQ1pXajZFUUVDNTI1Y1pHaUIwQlRYdzdtV3dBZ0gxcU9HRWNUVUl2NFNsJTJGV2pjVmVmaW5lcjZCb1czM2JNeGE0Um1sSmVGbUhsNUxCQ3F1OXpuTXpYTkdmRklNcXJvTG5DajFqVTE5ZVhKYW1KWjFoMHhtUW0zciUyRmNIa0hCQTAxUCUyQjlHT3FrZ3N6S3UlMkJvcDQ2elNwZlJUNmRUQ0xIVjN1TzBoV1JVMWFZMFElM0QmWC1BbXotU2lnbmF0dXJlPTVmZmEzODliNDAwNGVkNDliZjU2YzRkN2NlNTM5NzMyMGRkNTdkMTc2ZDBjYTQwZDEzMzUxOTY3NGQ2OWI5MjUmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JngtaWQ9UHV0T2JqZWN0 --upload-file /Users/jonlansdell/woman-black-beret.jpg -H "Content-Type: image/jpg"

When the upload is complete you can check the contents of the downloadUrl returned by the temporary file service. This should contain the image you uploaded.

Send a request to the Background removal API

When the file has uploaded, send the downloadUrl to the Background removal API. In this example the URL is https://temp-file-upload.amplience.net/52a39c0c-f30a-492e-8eaa-106e23e14daa.

mutation {
  removeBackgroundFromImage(
    input: {
      organizationId: "T4JnYW5penF0aW9uOm9yZ18QVUI0OU51NDF4eU4zanZQ"
      imageUrl: "https://temp-file-upload.amplience.net/52a39c0c-f30a-492e-8eaa-106e23e14daa"
    }
  ) {
    imageUrl
  }
}

The API will return a response with a imageUrl set to a temporary URL of the image with the background removed.

{
  "data": {
    "removeBackgroundFromImage": {
      "imageUrl": "https://temp-file-upload.amplience.net/044f62ed-cced-46b4-ab05-768078152e8e"
    }
  }
}

Related pages

GraphQL Asset Management API

Remove background from image

Generate a temporary file URL