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 (iOS).

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. Get the avatar source data (getAvatarConfig)

+ (NSDictionary <NSString *, NSArray *>* _Nullable)getAvatarConfig:(NSString * _Nullable)resPath exportedAvatar:(NSString *_Nullable)exportedAvatar;
Input parameters:
resPath: The absolute path of avatar materials on the user's mobile device, such as /var/mobile/Containers/Data/Application/C82F1F7A-01A1-4404-8CF6-131B26B4DA1A/Library/Caches/avatarMotionRes.bundle/avatar_v2.0_male.
exportedAvatar: 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 nil.
Output parameters: This API returns an NSDictionary object, in which key is the category (for details, see the TEDefine class below) and value is the data of the category. After the application layer gets the dictionary data, display it on the UI as needed.

2. Load the avatar materials (loadAvatar)

- (void)loadAvatar:(NSString * _Nullable)resPath exportedAvatar:(NSString * _Nullable)exportedAvatar;
Input parameters:
resPath: The absolute path of avatar materials on the user's mobile device, such as /var/mobile/Containers/Data/Application/C82F1F7A-01A1-4404-8CF6-131B26B4DA1A/Library/Caches/avatarMotionRes.bundle/avatar_v2.0_male.
exportedAvatar: The data saved after the user's last face customization, which is a JSON string. If the user uses the face customization feature for the first time or no data has been saved before, the parameter value will be nil.
Output parameters: This API returns an NSDictionary object, in which key is the category (for details, see the TEDefine class below) and value is the data of the category. After the application layer gets the dictionary data, display it on the UI as needed.

3. Customize the face and dress up (updateAvatar)

- (void)updateAvatar:(NSArray<AvatarData *> *_Nonnull)avatarDataList;
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)

+ (NSString *_Nullable)exportAvatar:(NSArray <AvatarData *>*_Nullable)avatarDataList;
When the user edits their avatar, the value of selected or shape 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 Xmagic to load the avatar materials, you need to set exportedAvatar 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.
+ (void)createAvatarByPhoto:(NSString * _Nullable)photoPath avatarResPaths:(NSArray <NSString *>* _Nullable)avatarResPaths isMale:(BOOL)isMale success:(nullable void (^)(NSString *_Nullable matchedResPath, NSString *_Nullable srcData))success failure:(nullable void (^)(NSInteger code, NSString *_Nullable msg))failure;
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. Currently, this property is not used. However, it may be in the future. We recommend that you pass in a correct value.
success: The callback for successful configuration, in which matchedResPath indicates the path of the matched materials and srcData indicates the matching result (same as the return value of exportAvatar).
failure: The callback when configuration fails, in which code indicates the error code and msg indicates the error message.

6. Save the downloaded configuration file (addAvatarResource)

+ (void)addAvatarResource:(NSString * _Nullable)rootPath category:(NSString * _Nullable)category filePath:(NSString * _Nullable)filePath completion:(nullable void (^)(NSError * _Nullable error, NSArray <AvatarData *>* _Nullable avatarList))completion;
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 getAllAvatarData the next time, the SDK will return the newly added data.
Parameters:
rootPath: The root directory of avatar materials, such as /var/mobile/Containers/Data/Application/C82F1F7A-01A1-4404-8CF6-131B26B4DA1A/Library/Caches/avatarMotionRes.bundle/avatar_v2.0_male.
category: The category of the downloaded material.
zipFilePath: The local path of the downloaded ZIP file.
completion: The result callback, in which error indicates the error message, and avatarList indicates the avatar data array obtained after parsing.

7. Send a custom event (sendCustomEvent)

This API is used to send a custom event, for example, to display the idle status when no face is detected.
- (void)sendCustomEvent:(NSString * _Nullable)eventKey eventValue:(NSString * _Nullable)eventValue;
eventKey: The key of the custom event. For details, see AvatarCustomEventKey of TEDefine.
eventValue: The value of the custom event, which is a JSON string. For example, you can convert @{@"enable" : @(YES)} to a JSON string or directly enter @"{\\"enable\\" : true}".

8. Call AvatarData

The AvatarData class is at the core of the above APIs. AvatarData contains the following fields:
/// @brief The configuration type.
@interface AvatarData : NSObject
// Such as face shape changing or eye adjustment. If the standard categories defined in `TEDefine` cannot meet your requirements, you can customize a category (make sure it’s not the same as an existing one). This filed cannot be empty.
@property (nonatomic, copy) NSString * _Nonnull 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.
@property (nonatomic, copy) NSString * _Nonnull Id;
// The type, which can be `selector` or `AvatarDataTypeSlider`.
@property (nonatomic, assign) AvatarDataType type;
/// If `type` is `selector`, this field indicates whether the item is selected.
@property (nonatomic, assign) BOOL isSelected;

/// The part of an avatar to be edited, for example, face, eyes, hair, shirt, or shoes. For how to configure this, refer to our documentation.
@property (nonatomic, copy) NSString * _Nonnull entityName;
/// The action to be performed on `entityName`. For details, see our documentation.
@property (nonatomic, copy) NSString * _Nonnull action;
/// The details of the action to be performed on `entityName`. For details, see our documentation.
@property (nonatomic, copy) NSDictionary * _Nonnull value;
@end
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.

More About AvatarData

The SDK gets AvatarData by parsing the custom_configs directory of the material root directory and sends it to the application layer. Generally, you don't need to manually construct 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.

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 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 and run the "resource_generator_gui" app we provide (only available on macOS currently). For details, see Design Specifications.