Background Remover API

The Background Remover feature allows clients to to remove backgrounds from images using advanced AI technology, preparing the images for creative enhancements. This feature is accessible through RESTful API endpoints, supporting operations such as initiating an background removing process, monitoring progress, and downloading the background removed images.

Endpoints Overview

1. Start BackgroundRemoving Process

Description: Initiates the background removing process for a given image.

Details: URL: POST /api/v1/Image/BackgroundRemoving/AdCreative Full Path: https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/AdCreative

Authorization: Requires a Bearer Token and the following headers:

Header

Description

Example Value

Authorization

Bearer token for authentication

Bearer YOUR_BEARER_TOKEN

x-api-key

API Key for the application

a1c3b5d7e9f6a8c4d2e9b3f7c5a9

x-api-secret

Secret Key for the application

f5c6a7b8e9d4f1a3c7b6e8f3a9d5

Content-Type

Specifies the data format

multipart/form-data

Accept

Expected response format

application/json

Request Body (form-data):

Field

Type

Required

Description

applicationId

GUID

Yes

Unique identifier for the application initiating the request.

userId

GUID

Yes

Unique identifier for the user for whom the background removing is performed.

uploadedImage

File

Yes

Image file to be remove background (e.g., .jpg or .png).

Example Request

cURL Command:

curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/AdCreative' \\
--header 'Content-Type: multipart/form-data' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>' \\
--form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \\
--form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \\
--form 'uploadedImage=@"/path/to/your/image.jpg"'

Example Responses

Successful Response

HTTP Status Code: 200 OK Response Body:

{
  "$id": "1",
  "messageType": "ImageBackgroundRemovingProgress",
  "requestRenderState": 1,
  "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
  "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
  "imageRenderProcessId": "e6c59f37-a794-468d-81aa-c9ef79dc042c",
  "totalTaskCount": 1,
  "completedTaskCount": 0,
  "progress": 0,
  "tasks": {
    "$id": "2",
    "50d04155-2bd9-46c1-85cb-47fa18cd02d7": 1
  },
  "renderType": 8,
  "isSuccessful": true,
  "errorMessage": ""
}

Validation Error Response

HTTP Status Code: 400 Bad Request Response Body:

{
  "$id": "1",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "$id": "2",
    "UploadedImage": [
      "UploadedImage is required.",
      "The request does not contain a file. Please make sure to upload the file."
    ]
  },
  "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}

Authorization Error Response

HTTP Status Code: 401 Unauthorized Response Body:

{
  "errors": {
    "business:": [
      "Token is missing, invalid or ApplicationId is not found in the token."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more errors occurred.",
  "status": 401,
  "detail": null,
  "instance": null,
  "extensions": {
    "traceId": "00-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
  }
}

Notes on Errors

400 Bad Request: Missing required fields or invalid image format.
401 Unauthorized: Missing or invalid token, or incorrect API credentials.

Ensure all required fields are provided and valid.

2. Check User Progress

Description: Retrieves the progress of the background removing process for a specific user.

Details:

URL: GET /api/v1/Image/BackgroundRemoving/CheckUserProgress
Full Path: https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckUserProgress
Authorization: Requires a Bearer Token and the following headers:

Headers

Header Name

Value

Description

Authorization

Bearer <YOUR_TOKEN>

Required for authentication.

x-api-key

<YOUR_API_KEY>

API Key for accessing the endpoint.

x-api-secret

<YOUR_API_SECRET>

API Secret for accessing the endpoint.

application/json

Specifies the response format.

Query Parameters

Parameter

Type

Required

Description

userId

Guid

Yes

The unique identifier for the user.

imageBackgroundRemoverProcessId

Guid

(Optional) The ID of the specific background removing process.

Example Request

cURL Command:

curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckUserProgress?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&imageBackgroundRemoverProcessId=e6c59f37-a794-468d-81aa-c9ef79dc042c' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'

Example Responses

Successful Response

HTTP Status Code: 200 OK
Response Body:

{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageBackgroundRemovingProgress",
            "requestRenderState": 5,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "e6c59f37-a794-468d-81aa-c9ef79dc042c",
            "totalTaskCount": 1,
            "completedTaskCount": 1,
            "progress": 100,
            "tasks": {
                "$id": "3",
                "50d04155-2bd9-46c1-85cb-47fa18cd02d7": 5
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}

Validation Error Response

HTTP Status Code: 400 Bad Request
Response Body:

{
    "$id": "1",
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "$id": "2",
        "userId": [
            "The userId field is required."
        ]
    },
    "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}

Authorization Error Response

HTTP Status Code: 401 Unauthorized
Response Body:

{
    "errors": {
        "business:": ["Token is missing, invalid or ApplicationId is not found in the token."]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 401,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
    }
}

Notes on Errors

400 Bad Request: Occurs when required parameters (userId) are missing or invalid.
401 Unauthorized: Happens when the token is missing, invalid, or API credentials are incorrect.
Ensure all required headers and query parameters are provided correctly.

3. Check Application All Progresses

Description: Checks the progress of all image background removing processes for a specific application.

Details:

Method: GET
URL: /api/v1/Image/BackgroundRemoving/CheckApplicationAllProgresses
Full Path: https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckApplicationAllProgresses

Authorization

Required: Bearer Token
Headers:
- Accept: application/json
- Authorization: Bearer <YOUR_BEARER_TOKEN>
- x-api-key: <YOUR_API_KEY>
- x-api-secret: <YOUR_API_SECRET>

Query Parameters

Parameter

Type

Required

Description

applicationId

Guid

Yes

The unique identifier of the application.

Example Request

cURL Command

curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckApplicationAllProgresses?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'

Responses

Successful Response

HTTP Status Code: 200 OK
Response Body:

{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageBackgroundRemovingProgress",
            "requestRenderState": 1,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "0f2b39a9-104a-4b8c-b52e-d126413504ac",
            "totalTaskCount": 1,
            "completedTaskCount": 0,
            "progress": 0,
            "tasks": {
                "$id": "3",
                "8dffe58f-3ea7-45aa-ae76-5c4fe6945d86": 1
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        },
        {
            "$id": "4",
            "messageType": "ImageBackgroundRemovingProgress",
            "requestRenderState": 1,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "b747fd87-0ebc-4112-afd0-53af8ce56ce7",
            "totalTaskCount": 1,
            "completedTaskCount": 0,
            "progress": 0,
            "tasks": {
                "$id": "5",
                "95c30efa-95cd-47d6-bb7a-fc5ca44fc3b5": 1
            },
            "renderType": 8,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}

Validation Error Response

HTTP Status Code: 400 Bad Request
Response Body:

{
  "$id": "1",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "applicationId": ["The applicationId field is required."]
  },
  "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00"
}

Authorization Error Response

HTTP Status Code: 401 Unauthorized
Response Body:

{
    "errors": {
        "business:": [
            "Token is missing, invalid or ApplicationId is not found in the token."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 401,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
    }
}

Not Found Error Response

HTTP Status Code: 404 Not Found
Response Body:

{
    "errors": {
        "engine: CheckProgress": [
            "No running or incomplete ImageFaceEnhancingProcess was not found for the User: N/A or the Application: b747fd87-0ebc-4112-afd0-53af8ce56ce7"
        ],
        "business: CheckApplicationAllProgresses": [
            "Not found error occurred while checking image background removing process for the ApplicationId: b747fd87-0ebc-4112-afd0-53af8ce56ce7"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 404,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-1252ddef5b95d69e25141fc0ead96042-a0c01c9be85419ef-00"
    }
}

Error Notes

400 Bad Request: Occurs if applicationId is missing or invalid.
401 Unauthorized: Bearer token is missing, invalid, or API credentials are incorrect.
404 Not Found: No progress data is found for the provided applicationId.

4. Download Background Removed Image

Description:

Retrieves the background removed image content stream based on the provided query parameters.

Details:

Method: GET
URL: /api/v1/Image/BackgroundRemoving/Download
Full Path: https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/Download

Authorization:

Requires a Bearer Token.
The following headers must be included:

Header

Description

Example Value

Authorization

Bearer token for authentication

Bearer <YOUR_BEARER_TOKEN>

x-api-key

API key for client identification

<YOUR_API_KEY>

x-api-secret

API secret for secure access

<YOUR_API_SECRET>

Accept

Expected response format

application/json

Query Parameters:

Parameter

Type

Required

Description

Example Value

applicationId

Guid

Yes

ID of the application making the request

4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6

taskId

Guid

Yes

Unique identifier for the specific task

e6c59f37-a794-234f-56yu-c9ef79dc042c

imageBackgroundRemover

ProcessId

Guid

Yes

ID of the image background removing process

e6c59f37-a794-468d-81aa-c9ef79dc042c

lowResolution

bool

Indicates whether the image is in low resolution

false

Example Request:

cURL Command:

curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=e6c59f37-a794-234f-56yu-c9ef79dc042c&imageBackgroundRemoverProcessId=e6c59f37-a794-468d-81aa-c9ef79dc042c&lowResolution=false' \\
--header 'Accept: application/json' \\
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\
--header 'x-api-key: <YOUR_API_KEY>' \\
--header 'x-api-secret: <YOUR_API_SECRET>'

Example Responses:

Successful Response:

HTTP Status Code: 200 OK
Response Type: FileStream
Details: The requested image file stream will be directly downloaded.

Authorization Error Response

HTTP Status Code: 401 Unauthorized
Response Body:

{
    "errors": {
        "business:": [
            "Token is missing, invalid or ApplicationId is not found in the token."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 401,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-735817749634d9300906511b8291993f-15940a2feb6bac0a-00"
    }
}

Validation Error Response:

HTTP Status Code: 400 Bad Request
Response Body:

{
    "$id": "1",
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "$id": "2",
        "taskId": [
            "The value 'e6c59f37-a794-234f-56yu-c9ef79dc042c' is not valid."
        ]
    },
    "traceId": "00-7f9b779a099abe1bc26babff88ab4d5d-707fdfff822f63ed-00"
}

Not Found Error Response:

HTTP Status Code: 404 Not Found
Response Body:

{
    "errors": {
        "engine: BackgroundRemoving/Download": [
            "Image content not found."
        ],
        "business: BackgroundRemoving/Download": [
            "Not found error occurred while getting original image content stream"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 404,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-87979cce38eb3aaa532fc90bdc73f9df-82aedb262968bc6a-00"
    }
}

Error Notes:

400 Bad Request:
- Occurs when the taskId or other parameters are invalid.
- Ensure all query parameters are properly formatted.
404 Not Found:
- No image content is found for the provided identifiers.
- Verify that applicationId, taskId, and imageBackgroundRemoverProcessId are correct.
401 Unauthorized:
- Bearer token is missing or invalid.
- Ensure proper API key and secret are used in the headers.

Validation Notes

Required Fields: All required fields must be provided in the request.
File Formats: Uploaded files must meet the required formats (e.g., jpeg).
Notification Channel: If notifications are enabled, ensure a valid notification channel is configured.

PreviousImage Upscaler API NextFace Enhancer API

Last updated 3 months ago

curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/AdCreative' \\ --header 'Content-Type: multipart/form-data' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\ --header 'x-api-key: <YOUR_API_KEY>' \\ --header 'x-api-secret: <YOUR_API_SECRET>' \\ --form 'applicationId="4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6"' \\ --form 'userId="2581c740-8e9d-4d63-96bc-5665bb9a646b"' \\ --form 'uploadedImage=@"/path/to/your/image.jpg"'

{ "$id": "1", "messageType": "ImageBackgroundRemovingProgress", "requestRenderState": 1, "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6", "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "imageRenderProcessId": "e6c59f37-a794-468d-81aa-c9ef79dc042c", "totalTaskCount": 1, "completedTaskCount": 0, "progress": 0, "tasks": { "$id": "2", "50d04155-2bd9-46c1-85cb-47fa18cd02d7": 1 }, "renderType": 8, "isSuccessful": true, "errorMessage": "" }

{ "$id": "1", "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "$id": "2", "UploadedImage": [ "UploadedImage is required.", "The request does not contain a file. Please make sure to upload the file." ] }, "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00" }

{ "errors": { "business:": [ "Token is missing, invalid or ApplicationId is not found in the token." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 401, "detail": null, "instance": null, "extensions": { "traceId": "00-735817749634d9300906511b8291993f-15940a2feb6bac0a-00" } }

curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckUserProgress?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&imageBackgroundRemoverProcessId=e6c59f37-a794-468d-81aa-c9ef79dc042c' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\ --header 'x-api-key: <YOUR_API_KEY>' \\ --header 'x-api-secret: <YOUR_API_SECRET>'

{ "$id": "1", "$values": [ { "$id": "2", "messageType": "ImageBackgroundRemovingProgress", "requestRenderState": 5, "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6", "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "imageRenderProcessId": "e6c59f37-a794-468d-81aa-c9ef79dc042c", "totalTaskCount": 1, "completedTaskCount": 1, "progress": 100, "tasks": { "$id": "3", "50d04155-2bd9-46c1-85cb-47fa18cd02d7": 5 }, "renderType": 8, "isSuccessful": true, "errorMessage": "" } ] }

{ "$id": "1", "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "$id": "2", "userId": [ "The userId field is required." ] }, "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00" }

{ "errors": { "business:": ["Token is missing, invalid or ApplicationId is not found in the token."] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 401, "detail": null, "instance": null, "extensions": { "traceId": "00-735817749634d9300906511b8291993f-15940a2feb6bac0a-00" } }

curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/CheckApplicationAllProgresses?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\ --header 'x-api-key: <YOUR_API_KEY>' \\ --header 'x-api-secret: <YOUR_API_SECRET>'

{ "$id": "1", "$values": [ { "$id": "2", "messageType": "ImageBackgroundRemovingProgress", "requestRenderState": 1, "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6", "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "imageRenderProcessId": "0f2b39a9-104a-4b8c-b52e-d126413504ac", "totalTaskCount": 1, "completedTaskCount": 0, "progress": 0, "tasks": { "$id": "3", "8dffe58f-3ea7-45aa-ae76-5c4fe6945d86": 1 }, "renderType": 8, "isSuccessful": true, "errorMessage": "" }, { "$id": "4", "messageType": "ImageBackgroundRemovingProgress", "requestRenderState": 1, "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6", "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b", "imageRenderProcessId": "b747fd87-0ebc-4112-afd0-53af8ce56ce7", "totalTaskCount": 1, "completedTaskCount": 0, "progress": 0, "tasks": { "$id": "5", "95c30efa-95cd-47d6-bb7a-fc5ca44fc3b5": 1 }, "renderType": 8, "isSuccessful": true, "errorMessage": "" } ] }

{ "$id": "1", "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "applicationId": ["The applicationId field is required."] }, "traceId": "00-35fea5107319e5521fddbcc6daeeef12-474bf812d683ae81-00" }

{ "errors": { "engine: CheckProgress": [ "No running or incomplete ImageFaceEnhancingProcess was not found for the User: N/A or the Application: b747fd87-0ebc-4112-afd0-53af8ce56ce7" ], "business: CheckApplicationAllProgresses": [ "Not found error occurred while checking image background removing process for the ApplicationId: b747fd87-0ebc-4112-afd0-53af8ce56ce7" ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 404, "detail": null, "instance": null, "extensions": { "traceId": "00-1252ddef5b95d69e25141fc0ead96042-a0c01c9be85419ef-00" } }

curl --location 'https://api.adcreative.ai/api/v1/Image/BackgroundRemoving/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=e6c59f37-a794-234f-56yu-c9ef79dc042c&imageBackgroundRemoverProcessId=e6c59f37-a794-468d-81aa-c9ef79dc042c&lowResolution=false' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \\ --header 'x-api-key: <YOUR_API_KEY>' \\ --header 'x-api-secret: <YOUR_API_SECRET>'

{ "$id": "1", "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "One or more validation errors occurred.", "status": 400, "errors": { "$id": "2", "taskId": [ "The value 'e6c59f37-a794-234f-56yu-c9ef79dc042c' is not valid." ] }, "traceId": "00-7f9b779a099abe1bc26babff88ab4d5d-707fdfff822f63ed-00" }

{ "errors": { "engine: BackgroundRemoving/Download": [ "Image content not found." ], "business: BackgroundRemoving/Download": [ "Not found error occurred while getting original image content stream" ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 404, "detail": null, "instance": null, "extensions": { "traceId": "00-87979cce38eb3aaa532fc90bdc73f9df-82aedb262968bc6a-00" } }