Docs Overview/
Avatar APIs/

Avatar APIs

SDK Integration

For how to download and integrate the SDK, how to set the license, as well as how to run a demo project, see Integrating Tencent Effect SDK (Android).

Copying the Avatar Materials

We offer multiple sets of face customization and dress-up materials, which can be found in the MotionRes/avatarRes directory in the SDK package after decompression. Like other animated effect materials, you need to copy them to the assets directory of your project.


Avatar Customization and SDK APIs

Face customization process
Photo-based face customization process


The section below offers descriptions of the APIs of XMagicApi, including the APIs for data loading, avatar customization, and photo-based avatar customization.

1. Load the avatar materials (loadAvatar)

public void loadAvatar(XmagicProperty<?> property, UpdatePropertyListener updatePropertyListener)
The avatar materials are loaded in the same way as other animated effect materials. The loadAvatar API is equivalent to the updateProperty API.

2. Load the avatar source data (getAvatarConfig)

public static Map<String,List<AvatarData>> getAvatarConfig(String avatarResPath, String savedAvatarConfigs)
Input parameters:
avatarResPath: The absolute path of the avatar materials on the user's mobile device, such as /data/data/com.tencent.pitumotiondemo.effects/files/xmagic/MotionRes/avatarRes/animoji_0624.
savedAvatarConfigs: The avatar configuration data (a JSON string) saved from the last time the user customized an avatar. If an avatar is customized for the first time or no configuration data is saved, pass in null.
Output parameters: This API returns a map, in which key corresponds to category and value corresponds to the data of the category. For details, see the AvatarCategory class. After the application layer gets the map, display the data on the UI as needed.

3. Customize the face and dress up (updateAvatar)

public void updateAvatar(List<AvatarData> avatarDataList, UpdateAvatarConfigListener upDataAvatarConfigListener)
When this API is called, the avatar preview will be updated in real time. Each AvatarData object corresponds to a configuration (such as changing the hairstyle). You can pass multiple AvatarData objects to an API call to edit multiple aspects of an avatar, for example, change the hairstyle and hair color. The API will validate the AvatarData objects passed in. If an object is valid, it will be passed to the SDK; if not, a callback will be sent.
For example, if an AvatarData object is passed in to change the hairstyle, but the hair model file (specified by value in AvatarData) cannot be found on the local device, the AvatarData object will be considered invalid.
Also, if an AvatarData object is passed in to change the iris image, but the image file (specified by value in AvatarData) cannot be found on the local device, the AvatarData object will be considered invalid.

4. Export avatar settings (exportAvatar)

public static String exportAvatar(List<AvatarData> avatarDataList)
When the user edits their avatar, the value of selected or shape change values in AvatarData will change. After editing, a new AvatarData list will be generated and can be exported as a JSON string. You can save it locally or upload it to the server. The string is exported for the following purposes:
The next time you call loadAvatar of XMagicApi to load the avatar materials, you need to set customConfigs of XMagicProperty to the JSON string so that the preview will remember the avatar settings from the last time.
Also, you need to pass in this JSON string when you call getAllAvatarData to update selected and the shape values in the avatar source data.

5. Customize an avatar based on a photo (createAvatarByPhoto)

For this API to work, the SDK must be connected to the internet.
public void createAvatarByPhoto(String photoPath, List<String> avatarResPaths, boolean isMale,
            final FaceAttributeListener faceAttributeListener)
photoPath: The photo path. Make sure the face is in the center of the photo. Ideally, the photo should include only one face. If there are multiple, the SDK will select one randomly. To ensure the recognition results, the short side of the photo should preferably be longer than 500 px.
avatarResPaths: You can pass in multiple sets of avatar materials, and the SDK will select the most suitable set based on the photo analysis result.
Note:
Currently, only one set of materials is supported. If multiple sets are passed in, the SDK will use the first one.
isMale: Whether the person is male. Set to true for male and false for female.
faceAttributeListener: If customization fails, void onError(int errCode, String msg) will be returned; if it succeeds, void onFinish(String matchedResPath, String srcData) will be returned, in which the first parameter indicates the path of the matched avatar materials, and the second is the matching result (same as the return value of exportAvatar).
The error codes of onError are defined in FaceAttributeHelper.java:
  public static final int ERROR_NO_AUTH = 1;// Insufficient permission.
  public static final int ERROR_RES_INVALID = 5;// The avatar material path passed in is invalid.
  public static final int ERROR_PHOTO_INVALID = 10;// Failed to read the photo.
  public static final int ERROR_NETWORK_REQUEST_FAILED = 20;// Failed to connect to the internet.
  public static final int ERROR_DATA_PARSE_FAILED = 30;// Failed to parse the data returned from the network.
  public static final int ERROR_ANALYZE_FAILED = 40;// Failed to recognize the face.
  public static final int ERROR_AVATAR_SOURCE_DATA_EMPTY = 50;// Failed to load the avatar source data.

6. Save the downloaded configuration file (addAvatarResource)

public static Pair<Integer, List<AvatarData>> addAvatarResource(String resourceRootPath, String category, String zipFilePath)
This API is used if avatar materials are downloaded dynamically. For example, suppose you offer 10 hairstyles and one of them is dynamically downloaded to a device. You need to call this API to pass the path of the downloaded ZIP file to the SDK. The SDK will parse the file and save it to the folder of the corresponding category. When you call getAvatarConfig the next time, the SDK will return the newly added data. Parameters:
resourceRootPath: The root directory of the avatar materials, such as /data/data/com.tencent.pitumotiondemo.effects/files/xmagic/MotionRes/avatarRes/animoji_0624.
category: The category of the downloaded material.
zipFilePath: The path of the downloaded ZIP file.
The API returns Pair<Integer, List<AvatarData>>, where pair.first is the error code, and pair.second is the newly added data.
The error codes are as follows:
  public interface AvatarActionErrorCode {
      int OK = 0;
      int ADD_AVATAR_RES_INVALID_PARAMS = 1000;
      int ADD_AVATAR_RES_ROOT_RESOURCE_NOT_EXIST = 1001;
      int ADD_AVATAR_RES_ZIP_FILE_NOT_EXIST = 1002;
      int ADD_AVATAR_RES_UNZIP_FILE_FAILED = 1003;
      int ADD_AVATAR_RES_COPY_FILE_FAILED = 1004;
  }

7. Call AvatarData

The AvatarData class is at the core of the above APIs. AvatarData contains the following fields:
public class AvatarData {
    /**
     * The selector data. For example, for glasses, different types of glasses are offered, and only one can be selected.
     */
    public static final int TYPE_SELECTOR = 0;

    /**
     * The slider data, such as cheek width.
     */
    public static final int TYPE_SLIDER = 1;

    // The category, such as face shape and eye adjustment. Standard categories are defined in `AvatarCategory.java`. If they cannot meet your requirements, you can customize a category (make sure it’s not the same as an existing one).
    // This field cannot be empty.
    public String category;

    // The ID of an avatar configuration item.
    // For example, each type of glasses has a unique ID. So does each adjustment item.
    // This field cannot be empty.
    public String id;

    // `TYPE_SELECTOR` or `TYPE_SLIDER`
    public int type;

    // If `type` is `TYPE_SELECTOR`, this field indicates whether the item is selected.
    public boolean selected = false;

    // Each icon or adjustment item has three aspects of configuration details:
    public String entityName;
    public String action;
    public JsonObject value;
}
An AvatarData object is the smallest unit of configuration, for example, hairstyle change or cheek adjustment.
Hairstyle change
Cheek adjustment


If an item is the selector type, configure it by changing the value of selected in AvatarData. For example, suppose there are four types of glasses: A, B, C, and D. If the user selects A, set selected of A to true and that of B, C, and D to false. If the user selects B, set selected of B to true and that of A, C, and D to false.
If an item is the slider type, configure it by changing value in AvatarData. The value field is a JSON object that includes multiple key-value pairs. Set the value of a key-value pair to the slider value.

8. Get the avatar animation data (getAvatarAnimations)

public static List<AvatarAnimation> getAvatarAnimations(String avatarResPath)
Input parameter: avatarResPath
The absolute path of the avatar materials on the user's mobile device, such as /data/data/com.tencent.pitumotiondemo.effects/files/xmagic/MotionRes/avatarRes/animoji_0624.
Output parameter: All animation resource data is returned in a list. For more information, see the AvatarAnimation class.

9. Save the downloaded animation configuration file (addAvatarAnimation)

public static Pair<Integer, List<AvatarAnimation>> addAvatarAnimation(String avatarResPath, String zipFilePath)
This API is used if avatar animation materials are downloaded dynamically. For example, suppose you offer one animation and it is dynamically downloaded to a device. You need to call this API to pass the path of the downloaded ZIP file to the SDK. The SDK will parse the file and save it to the folder of the corresponding animation resource. When you call getAvatarAnimations the next time, the SDK will return the newly added data. Parameters:
avatarResPath: The root directory of the avatar materials, such as /data/data/com.tencent.pitumotiondemo.effects/files/xmagic/MotionRes/avatarRes/animoji_0624.
zipFilePath: The path of the downloaded ZIP file.
The API returns Pair<Integer, List<AvatarAnimation>>, where pair.first is the error code, and pair.second is the newly added data.
The error codes are as follows:
  public interface AvatarActionErrorCode {
      int OK = 0;
      int ADD_AVATAR_RES_INVALID_PARAMS = 1000;
      int ADD_AVATAR_RES_ROOT_RESOURCE_NOT_EXIST = 1001;
      int ADD_AVATAR_RES_ZIP_FILE_NOT_EXIST = 1002;
      int ADD_AVATAR_RES_UNZIP_FILE_FAILED = 1003;
      int ADD_AVATAR_RES_COPY_FILE_FAILED = 1004;
      int ADD_AVATAR_RES_PARSE_JSON_FILE_FAILED = 1005;
  }

10. Play back/Pause the avatar animation (playAvatarAnimation)

public void playAvatarAnimation(AnimationPlayConfig animationConfig)
Input parameters:
AnimationPlayConfig: Animation playback information class. This class mainly contains the following information.
public class AnimationPlayConfig {  
     // The action description. It specifies whether to play back or pause the animation.
     public static final String ACTION_PLAY = "play";   
     public static final String ACTION_PAUSE = "pause";   
     public static final String ACTION_RESUME = "resume";   
     public static final String ACTION_STOP = "stop";  
    
     public String entityName;
     /** * The path of the animation folder. It can be the relative path to the material root directory, such as `custom_configs/animations/Waving`. 
     /** It can also be the relative path on the mobile phone, such as `/data/data/xxx/xxx/Waving`.*/
     public String animPath;
     // The value can be `ACTION_PLAY`, `ACTION_PAUSE`, `ACTION_RESUME`, or `ACTION_STOP`.
     public String action;
     /** * The animation name */
     public String animName;
     /** * The number of loops. `-1` indicates an infinite loop.*/
     public int loopCount = -1;
     /** * The playback start position of the animation in μs */
     public long startPositionUs = 0;
    }

More About AvatarData

The three key fields of AvatarData are entityName, action, and value, whose values are automatically entered when the SDK parses the configuration data. In most cases, you won’t need to deal with the details of these three fields. However, for slider data, you need to parse the key-value pairs in the value field and configure them based on the slider values set on the UI. Here, the AvatarData element consists of the entityName, action, and value fields.

entityName

entityName specifies which part of an avatar is to be edited, for example, face, eyes, hair, shirt, or shoes.

action and value

The action field indicates the action to be performed on entityName. Five action options are defined in AvatarAction.java in the SDK, which are detailed below:
action
Description
Requirements for value
changeColor
Changes the color of the current material. Color attributes include basic color and emission color.
This field is of JsonObject type and is required. It is generated automatically by the material customization tool.
changeTexture
Modifies the maps of the current material, including color texture map, metal/roughness texture map, ambient occlusion (AO) map, normal map, and emission map.
This field is of JsonObject type and is required. It is generated automatically by the material customization tool.
shapeValue
Modifies the shape change value of blendShape. This parameter is generally used for slight adjustment of detailed facial features.
This field is of JsonObject type and is required. Its key is the shape change name and value is of float type. It is generated automatically by the material customization tool.
replace
Replaces a submodel, for example, glasses, hairstyles, or clothes.
value must be a JSON object that describes the 3D transformation information, model path, and material path of the new submodel. It is generated automatically by the material customization tool. To hide a submodel, set it to null.
basicTransform
Adjusts the position, rotation, and scaling settings. This field is generally used to adjust the camera distance and angle so as to switch between the full and half-length views of the model.
This field is of JsonObject type and is required. It is generated automatically by the material customization tool.

Configuring Avatar Customization Data

Avatar configurations are stored in the resources folder (in material/custom_configs/resources):

In most cases, the configuration files are generated automatically and don't need to be configured manually. To automatically generate the configurations, design your materials using Tencent Effect Studio according to our standards and run the "resource_generator_gui" app we provide (only available on macOS currently). For details, see Design Specifications.