--- canonical: https://amplience.com/developers/docs/ai-services/background-removal-api/ title: Background removal API description: The Background removal API is a GraphQL API that uses AI to detect the most prominent foreground object in an image and then makes the background transparent. image: https://cdn.media.amplience.net/i/ampproduct/wooden-stool-background-removed?w=1200&h=630 image_width: 1200 image_height: 630 audience: Developer date_published: 2023-10-12 date_modified: 2026-02-27 --- # Background removal API The Background removal API is a [GraphQL API](https://amplience.com/developers/docs/apis/asset-management/reference/mutations/ai-tools#removebackgroundfromimage) 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](https://amplience.com/developers/docs/knowledge-center/amplience-labs/#general-availability-ga) release. Each request made to the API will use one [Amplience credit](https://amplience.com/developers/docs/ai-services/credits). ## Using the API The API is implemented as a mutation `removeBackgroundFromImage` as part of the [GraphQL Management API](https://amplience.com/developers/docs/apis/asset-management). The end point for all requests to the GraphQL Management API is: ``` https://api.amplience.net/graphql ``` You can also use the API when logged in to the [GraphQL playground](https://api.amplience.net/graphql). ### Authentication Amplience uses [OAuth2](https://oauth.net/2/) to authorize access to the [GraphQL Management API](https://amplience.com/developers/docs/apis/asset-management/overview). 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 GraphQL Management API. You can also use a [personal access token](https://amplience.com/developers/docs/apis/authorization/personal-access-tokens) instead of the API key and secret. You can find more details on the [authentication](https://amplience.com/developers/docs/apis/asset-management/overview/usage/#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](#finding-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](#using-the-temporary-file-service). ```graphql mutation { removeBackgroundFromImage( input: { organizationId: "T4JnYW5penF0aW9uOm9yZ18QVUI0OU51NDF4eU4zanZQ" imageUrl: "" } ) { 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. ```graphql { "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](https://amplience.com/developers/docs/ai-services/credits). - 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](#using-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. ```graphql 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: ```graphql 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. ![Image with a background to remove](https://cdn.media.amplience.net/i/ampproduct/wooden-stool-unsplash?h=400&fmt=png 'Image with a background to remove') 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: ```graphql 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. ```graphql { "data": { "removeBackgroundFromImage": { "imageUrl": "https://temp-file-upload.amplience.net/fd6dd2c8-6cef-4922-9a53-f97eaa718a4c" } } } ``` The returned image has the background removed. ![The image with the background removed](https://cdn.media.amplience.net/i/ampproduct/wooden-stool-background-removed?h=400&fmt=png 'The image with 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: ```graphql mutation { createTempFileUploadUrl { uploadUrl downloadUrl } } ``` `uploadUrl ` and `downloadUrl` are returned in the response. ```graphql { "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`. ```graphql 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. ```graphql { "data": { "removeBackgroundFromImage": { "imageUrl": "https://temp-file-upload.amplience.net/044f62ed-cced-46b4-ab05-768078152e8e" } } } ``` ## Related pages [GraphQL Management API](https://amplience.com/developers/docs/apis/asset-management/overview) [Remove background from image](https://amplience.com/developers/docs/apis/asset-management/reference/mutations/ai-tools#removebackgroundfromimage) [Generate a temporary file URL](https://amplience.com/developers/docs/apis/asset-management/reference/mutations/#createtempfileuploadurl)