Face Enhancer API

The Face Enhancer feature allows clients to enhance faces in images using advanced AI technology. This feature is accessible through RESTful API endpoints, supporting operations such as initiating a face enhancing process, monitoring progress, and downloading the face enhanced images.

Endpoints Overview

1. Start Face Enhancing Process

Description: Initiates the face enhancing process for a given image.

Details:

• URL: POST /api/v1/Image/FaceEnhancing/AdCreative

• Full Path: https://api.adcreative.ai/api/v1/Image/FaceEnhancing/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	<YOUR_API_KEY>
x-api-secret	Secret Key for the application	<YOUR_API_SECRET>
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 face enhancement is performed.
ariaRatio	Float	No	Ratio for face enhancement area adjustment (default: 0.5).
maxFaceCount	Integer	No	Maximum number of faces to enhance (default: 10).
uploadedImage	File	Yes	Image file to be enhanced (e.g., .jpg or .png).

Example Request: cURL Command:

curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/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 'ariaRatio="0.5"' \\
--form 'maxFaceCount="10"' \\
--form 'uploadedImage=@"/Users/adcreative.ai/Downloads/Images/group_bad_faces.png"'

Example Responses:

• Successful Response: HTTP Status Code: 200 OK Response Body:

  {
    "$id": "1",
    "messageType": "ImageFaceEnhancingProgress",
    "requestRenderState": 1,
    "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
    "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
    "imageRenderProcessId": "c61259ee-ba2d-49ef-9f58-9b2e7d4ad7ab",
    "totalTaskCount": 1,
    "completedTaskCount": 0,
    "progress": 0,
    "tasks": {
      "$id": "2",
      "8f8c84c6-1df7-41a8-9c72-855221f8b7ef": 1
    },
    "renderType": 128,
    "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-ce239b46f43de0766c9b9ce3d272a92a-7eab8b88dd249512-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-d378b545461dcc848f91b9c6ea2e4775-26d09313c3eebb1a-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 face enhancement process for a specific user.

Details:

• Method: GET

• URL: /api/v1/Image/FaceEnhancing/CheckUserProgress

• Full Path: https://api.adcreative.ai/api/v1/Image/FaceEnhancing/CheckUserProgress

Authorization:

Requires a Bearer Token with the following headers:

Header	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.
Accept	application/json	Specifies the response format.

Query Parameters:

Parameter	Type	Required	Description
userId	Guid	Yes	The unique identifier for the user.
imageFaceEnhancerProcessId	Guid	No	(Optional) The ID of the specific face enhancement process.

Example Request:

cURL Command:

curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/CheckUserProgress?userId=2581c740-8e9d-4d63-96bc-5665bb9a646b&imageFaceEnhancerProcessId=2c3a9038-a7c8-4a8a-8821-a66dc433c3dd' \\
--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": "ImageFaceEnhancingProgress",
            "requestRenderState": 5,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "2c3a9038-a7c8-4a8a-8821-a66dc433c3dd",
            "totalTaskCount": 1,
            "completedTaskCount": 1,
            "progress": 100,
            "tasks": {
                "$id": "3",
                "165ce0c4-27a4-4317-a388-3c4064cf8b17": 5
            },
            "renderType": 128,
            "isSuccessful": true,
            "errorMessage": ""
        }
    ]
}

Validation Error Response:

HTTP Status Code: 400 Bad Request

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-2963f16f8ef6ed45095d4ceab4aa4be3-5d89071342730431-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: 2581c740-8e9d-4d63-96bc-5665bb9a646b or the Application: N/A"
        ],
        "business: CheckUserProgress": [
            "Not found error occurred while checking face enhancer process for User: 2581c740-8e9d-4d63-96bc-5665bb9a646b and imageFaceEnhancerProcessId: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
        ]
    },
    "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-3a592608499e51142589ccee0ad1118a-d18b65bd224535c3-00"
    }
}

Notes on Errors:

• 400 Bad Request: Occurs when required parameters (e.g., userId) are missing or invalid.

• 404 Not Found: No progress data is found for the provided userId or imageFaceEnhancerProcessId.

• 401 Unauthorized: Bearer token is missing or invalid.

---

3. Check Application Progress

Description

Checks the progress of all face-enhancing processes for a specific application.

Endpoint Details

• Method: GET

• URL: /api/v1/Image/FaceEnhancing/CheckApplicationAllProgresses

• Full Path: https://api.adcreative.ai/api/v1/Image/FaceEnhancing/CheckApplicationAllProgresses

Authorization

Requires a Bearer Token.

Headers

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

Example Request

cURL Command:

curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/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>'

Example Responses

Successful Response:

• HTTP Status Code: 200 OK

• Response Body:

{
    "$id": "1",
    "$values": [
        {
            "$id": "2",
            "messageType": "ImageFaceEnhancingProgress",
            "requestRenderState": 1,
            "applicationId": "4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6",
            "userId": "2581c740-8e9d-4d63-96bc-5665bb9a646b",
            "imageRenderProcessId": "6dc55293-8c07-4522-950f-265fd38c733c",
            "totalTaskCount": 1,
            "completedTaskCount": 0,
            "progress": 0,
            "tasks": {
                "$id": "3",
                "828a7a62-5462-4fea-9416-642bf201acf7": 1
            },
            "renderType": 128,
            "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",
        "applicationId": [
            "The value '2581c740-8e9d-4d63-96bc-5665bb9a6' is not valid."
        ]
    },
    "traceId": "00-f63a19f0239297745f0493e1ff93f582-3e5099e2cbe621ce-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: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
        ],
        "business: CheckApplicationAllProgresses": [
            "Not found error occurred while checking image face enhancing process for the ApplicationId: 2581c740-8e9d-4d63-96bc-5665bb9a646b"
        ]
    },
    "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-8d925e3ff2b520c283a3fbd504172fce-1df96f7a708f401d-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-95ba97c088b871449fe76ced5f3977a9-7bb06405ad7dce6c-00"
    }
}

Error Notes

• 400 Bad Request: Occurs if applicationId is missing or invalid. Ensure the applicationId is a valid GUID.

• 404 Not Found: No progress data is found for the provided applicationId.

• 401 Unauthorized: Bearer token is missing or invalid. Ensure proper API key and secret are used in the headers.

---

4. Download Face Enhanced Image

Endpoint Details

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

Authorization

The following headers must be included for authentication and identification:

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	165ce0c4-27a4-4317-a388-3c4064cf8b17
imageFaceEnhancerProcessId	Guid	Yes	ID of the face-enhancing process	2c3a9038-a7c8-4a8a-8821-a66dc433c3dd
lowResolution	bool	No	Indicates whether the image is in low resolution	true

---

Example Request

cURL Command:

curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/Download?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6&taskId=165ce0c4-27a4-4317-a388-3c4064cf8b17&imageFaceEnhancerProcessId=2c3a9038-a7c8-4a8a-8821-a66dc433c3dd&lowResolution=true' \\
--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-d378b545461dcc848f91b9c6ea2e4775-26d09313c3eebb1a-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 '165ce0c4-27a4-4317-a388-3c4064cf8b' is not valid."
        ]
    },
    "traceId": "00-a54a3264785cd30b4ee7e454053096bf-0b0d3b01c3bcd870-00"
}

---

Not Found Error Response

HTTP Status Code: 404 Not Found Response Body:

{
    "errors": {
        "engine: FaceEnhancing/Download": [
            "Image content not found."
        ],
        "business: FaceEnhancing/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-80d865ee86529038daf1fef33992439c-4defb5fc45a4f77e-00"
    }
}

---

Error Notes

• 400 Bad Request:

  • Occurs when 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 imageFaceEnhancerProcessId 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.

• Notification Channel: If notifications are enabled, ensure a valid notification channel is configured.

---

Additional Notes

• Notification Requirement: Ensure that an active notification channel is configured for the application before calling these endpoints.

• Validation: Validate all GUIDs and required parameters before making API calls.