# 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:
HeaderDescriptionExample Value
AuthorizationBearer token for authenticationBearer <YOUR_BEARER_TOKEN>
x-api-keyAPI Key for the application<YOUR_API_KEY>
x-api-secretSecret Key for the application<YOUR_API_SECRET>
Content-TypeSpecifies the data formatmultipart/form-data
AcceptExpected response formatapplication/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: ```bash curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/AdCreative' \\ --header 'Content-Type: multipart/form-data' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer ' \\ --header 'x-api-key: ' \\ --header 'x-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: ```json { "$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: ```json { "$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: ```json { "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 `` | Required for authentication. | | x-api-key | `` | API Key for accessing the endpoint. | | x-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:** ```bash 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 ' \\ --header 'x-api-key: ' \\ --header 'x-api-secret: ' ``` #### Example Responses: **Successful Response:** **HTTP Status Code:** `200 OK` **Response Body:** ```json { "$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:** ```json { "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:** ```json { "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 `` | | x-api-key | API key for client identification | `` | | x-api-secret | API secret for secure access | `` | | Accept | Expected response format | application/json | #### Query Parameters
ParameterTypeRequiredDescriptionExample Value
applicationIdGuidYesID of the application making the request4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
#### Example Request **cURL Command:** ```bash curl --location 'https://api.adcreative.ai/api/v1/Image/FaceEnhancing/CheckApplicationAllProgresses?applicationId=4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer ' \\ --header 'x-api-key: ' \\ --header 'x-api-secret: ' ``` #### Example Responses **Successful Response:** * **HTTP Status Code**: 200 OK * **Response Body**: ```json { "$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**: ```json { "$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**: ```json { "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**: ```json { "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 `` | | `x-api-key` | API key for client identification | `` | | `x-api-secret` | API secret for secure access | `` | | `Accept` | Expected response format | `application/json` | *** ### Query Parameters
ParameterTypeRequiredDescriptionExample Value
applicationIdGuidYesID of the application making the request4f7d8a9c-b5e6-4d3e-b7a9-d5c3e1b7a4f6
taskIdGuidYesUnique identifier for the specific task165ce0c4-27a4-4317-a388-3c4064cf8b17
imageFaceEnhancerProcessIdGuidYesID of the face-enhancing process2c3a9038-a7c8-4a8a-8821-a66dc433c3dd
lowResolutionboolNoIndicates whether the image is in low resolutiontrue
*** ### Example Request **cURL Command**: ```bash 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 ' \\ --header 'x-api-key: ' \\ --header 'x-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**: ```json { "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**: ```json { "$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**: ```json { "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.