AI Avatar

AI Avatar is an innovative project that aims to create personalized avatars for users using cutting-edge artificial intelligence techniques. The project utilizes a user's input images, typically a few

1. Filter API

Important! - You have to send 3-20 photo of your face, the photos follow some rules bellow: - Required image format is png, jpeg, jpg, jfif, heic. - At least 2 sides of image must be greater than or equal to 768px. - File size < 8mb. - Image have to include your face. - The face should not be too large or too small:

• The face is considered small when the horizontal aspect ratio of the face is less than 120/768 pixels (Taken from a distance, such as full-body shots - making it difficult to identify the face).

• The face is considered large when the horizontal aspect ratio of the face is greater than 450/768 pixels (Taken too closely - cropping the image into a square would cut into the face).

- The face in the image is different from the majority of faces in the remaining images:

• Faces of different people in various images. The same person's face but significantly different.

- Image must not be blurry. - The image must not be duplicated.

Send request filter input image from at least 3 input images

POST https://avatar-core.apero.vn/api/v1/upload/avatar

Use form-data to send request

Request Body

Name	Type	Description
files*	file	Input image of user
files*	file	Input image of user
files*	file	Input image of user

200: OK Generation request will be process after that

// Successfully response
{
    "responseTime": 1692156075801,
    "isSuccess": true,
    "message": "Sufficient quality images.",
    "data": {
        "sessionId": "a8fHBv8Ps1XRlMo", //SessionID will be used for generate avatar 
        "uploadImages": [ //Images will be used for training
            "sample1.heic",
            "sample2.heic",
            "sample3.heic"
        ]
    }
}

400: Bad Request

{
    "isSuccess": false,
    "error": {
        "name": "Bad Request",
        "status": 400,
        "data": [ //Filename and erorr reason 
            {
                "filename": "sample.jpg",
                "reason": "The provided image is blurry. Please provide a clearer image."
            }
        ]
    },
    "message": "Invalid images",
}

2. Request generate avatar

POST https://avatar-core.apero.vn/api/v1/generate/avatar-session

API Signature is required

Request Body

Name	Type	Description
notifyTo*	String	Gen the token from firebase, if notifyType is email, use receiver email for this field
numImagesEachStyle*	Integer	Min: 3, Max: 20 Number of images output each style
gender*	String	Value: male, female
styles*	String[]	List style available: female: ['queen','angel','forest_girl','iron_woman','snow_girl','cyborg','universal_soldier','chinese_girl','city_girl','star_war','hunter','stylish','mythical_girl','golden_fairy'] male: ['cyborg','victorian_general','elf','cyber_punk','harry_potter','wizard','angel','superman','astronaut','aborigine','ghost','ink_stain',]
notifyType*	String	Value: fcm, email
bundleId	String	Package name if send notification with android platform. IOS will be bundle id
sessionId*	String	Get this field from API Filter
successNotiMessage	Object	The field is an object include title and body. This will be use for FCM notification content.
errorNotiMessage	String	The field is an object include title and body. This will be use for FCM notification content.
bundleId	String	If notifyType is fcm, the field is required

200: OK Generation request will be process after that

{
    "responseTime": 1692160506252,
    "isSuccess": true,
    "message": "Suffient data for training. Please wait to see results.",
    "data": {
        "session": {
            "_id": "64dc51eb230a2d1144fa177b",
            "sessionId": "5wgvF3m8UBJxL4F",
            "canGenerateAvatar": true,
            "results": [],
            "createdAt": "2023-08-16T04:34:51.443Z",
            "updatedAt": "2023-08-16T04:34:51.446Z",
            "__v": 0,
            "status": "init",
            "timestamp": "2023-08-16T04:34:51.446Z"
        }
    }
}

400: Bad Request

{ //Example error response
    "isSuccess": false,
    "error": {
        "name": "INVALID_STYLE_NAME",
        "status": 400,
        "data": {}
    },
    "message": "Invalid style name. Please provide valid styles for male/female character.",
}

Important:

• Styles depend on gender, must have to choose one or many on the list style match with your gender

• Notify in app use firebase credential, you have to integrate firebase SDK on client and add us to your firebase. We will create firebase-service-account from your firebase console for send notification from backend

Good to know: - You will receive numImageEachStyle * amount of styles you choose by email. - Must have to upload at least 3 photos for generate, you should choose photo about half the body including the face, high quality photos and not too many people in one frame. - Usually, you will receive result by email after about 15-30 minutes

3. Tracking process

GET https://avatar-core.apero.vn/api/v1/sessions?sessionId=[sessionId]

200: OK

{
    "responseTime": 1692168679297,
    "isSuccess": true,
    "message": "success",
    "data": {
        "session": {
            "_id": "64dc51eb230a2d1144fa177b",
            "sessionId": "5wgvF3m8UBJxL4F",
            "canGenerateAvatar": true,
            "results": {
                "ink_stain": [
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/ink_stain_f37de994-4440-11ee-b652-0242c0a84004.png",
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/ink_stain_f64f79b2-4440-11ee-b652-0242c0a84004.png",
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/ink_stain_f4e69fa6-4440-11ee-b652-0242c0a84004.png"
                ],
                "aborigine": [
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/aborigine_fa883154-4440-11ee-b652-0242c0a84004.png",
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/aborigine_f7b35350-4440-11ee-b652-0242c0a84004.png",
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/aborigine_f9199574-4440-11ee-b652-0242c0a84004.png"
                ],
                "wizard": [
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/wizard_fbefccaa-4440-11ee-b652-0242c0a84004.png",
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/wizard_fecc048e-4440-11ee-b652-0242c0a84004.png",
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/wizard_fd5d42c0-4440-11ee-b652-0242c0a84004.png"
                ],
                "angel": [
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/angel_01af340a-4441-11ee-b652-0242c0a84004.png",
                    "ai-avatar/qKdSyKeDlh3AN2J/output/angel_0038d89c-4441-11ee-b652-0242c0a84004.png",
                    "ai-avatar/qKdSyKeDlh3AN2J/output/angel_0325f026-4441-11ee-b652-0242c0a84004.png"
                ],
                "harry_potter": [
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/harry_potter_077ad394-4441-11ee-b652-0242c0a84004.png",
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/harry_potter_049b9640-4441-11ee-b652-0242c0a84004.png",
                    "https://static.apero.vn/ai-avatar/qKdSyKeDlh3AN2J/output/harry_potter_060a1484-4441-11ee-b652-0242c0a84004.png"
                ]
            },
            "createdAt": "2023-08-16T04:34:51.443Z",
            "updatedAt": "2023-08-16T04:44:36.249Z",
            "status": "complete", //["init", "active", "process", "complete", "error"]
            "timestamp": "2023-08-16T04:44:36.248Z",
            "notifyBy": "system",
            "notifyTo": "[e-mail]",
            "notifyType": "email"
        },
        "events": [ //history
            {
                "_id": "64dc5434230a2d1144fa1789",
                "sessionId": "5wgvF3m8UBJxL4F",
                "status": "complete", // After notified
                "actionFrom": "image_wrapper_service",
                "createdAt": "2023-08-16T04:44:36.250Z",
                "updatedAt": "2023-08-16T04:44:36.250Z",
            },
            {
                "_id": "64dc5434230a2d1144fa1789",
                "sessionId": "5wgvF3m8UBJxL4F",
                "status": "success", // Training success
                "actionFrom": "image_wrapper_service",
                "createdAt": "2023-08-16T04:44:36.250Z",
                "updatedAt": "2023-08-16T04:44:36.250Z",
            },
            {
                "_id": "64dc5434230a2d1144fa1789",
                "sessionId": "5wgvF3m8UBJxL4F",
                "status": "error", // Training error
                "actionFrom": "image_wrapper_service",
                "createdAt": "2023-08-16T04:44:36.250Z",
                "updatedAt": "2023-08-16T04:44:36.250Z",
            },
            {
                "_id": "64dc51fa230a2d1144fa1784",
                "sessionId": "5wgvF3m8UBJxL4F",
                "status": "active", // Request training is received
                "actionFrom": "ai_avatar_store",
                "createdAt": "2023-08-16T04:35:06.249Z",
                "updatedAt": "2023-08-16T04:35:06.249Z",
            },
            {
                "_id": "64dc51eb230a2d1144fa177e",
                "sessionId": "5wgvF3m8UBJxL4F",
                "status": "init", // After input images is filtered
                "actionFrom": "ai_avatar_store",
                "createdAt": "2023-08-16T04:34:51.449Z",
                "updatedAt": "2023-08-16T04:34:51.449Z",
            }
        ]
    }
}

400: Bad Request

{ //Example error response
    "isSuccess": false,
    "error": {
        "name": "INVALID_STYLE_NAME",
        "status": 400,
        "data": {}
    },
    "message": "Invalid style name. Please provide valid styles for male/female character.",
}

4. List styles

GET https://avatar-core.apero.vn/api/v1/resources/avatar-styles

Query Parameters

Name	Type	Description
groupBy	String	Field you want to group. Default: gender
orderBy	String	Field you want to order Default: priority
orderType	String	Way you want to order: ascending or descending Accept 2 values: asc and desc Default: asc

200: OK

{
  "responseTime": 1692328446339,
  "isSuccess": true,
  "message": "success",
  "data": {
    "groups": ["female", "male"],
    "values": {
      "female": [
        {
          "_id": "64ded4508f1f5e29ffb88262",
          "priority": 1,
          "category": "all",
          "thumbnail": "", // thumbnail is JPG image
          "displayName": "Queen",// the field use for display on UI
          "alias": "queen", // the field use for API
          "gender": "female",
          "__v": 0,
          "createdAt": "2023-08-18T02:15:44.531Z",
          "updatedAt": "2023-08-18T02:15:44.531Z"
        }
      ],
      "male": [
        {
          "_id": "64ded4508f1f5e29ffb88270",
          "priority": 15,
          "category": "all",
          "thumbnail": "",
          "displayName": "Cyborg",
          "alias": "cyborg",
          "gender": "male",
          "__v": 0,
          "createdAt": "2023-08-18T02:15:44.533Z",
          "updatedAt": "2023-08-18T02:15:44.533Z"
        }
      ]
    }
  }
}

400: Bad Request

{ //Example error response
    "isSuccess": false,
    "error": {
        "name": "INVALID_STYLE_NAME",
        "status": 400,
        "data": {}
    },
    "message": "Invalid style name. Please provide valid styles for male/female character.",
}