TencentEffectApi is the core API class of the Tencent Effect Flutter SDK. It offers capabilities including setting the effect strength and applying animated effects.API | Description |
Set the local storage path for beauty resources (added in V0.3.5.0 version). | |
Initialize the beauty enhancement data. This method must be invoked prior to applying any beauty effects (applicable to versions V0.3.1.1 and earlier). | |
Beauty Filter Authorization | |
Configure the log level of the SDK. It is recommended to set it to Log.DEBUG during development and debugging, and switch to Log.WARN for official releases. Setting Log.DEBUG in production environments may significantly impact performance due to excessive log output. | |
Resume rendering, invoked when the page becomes visible | |
Suspend rendering, invoked when the page becomes invisible | |
Enable the beauty enhancement mode. For detailed instructions, please refer to Enhanced Mode User Guide | |
Specifies the performance and effect mode, with available values of NORMAL and PRO. The NORMAL mode meets the requirements of most scenarios, offering better performance with slightly fewer features. Please select according to your needs. For detailed differences between the two modes, please refer to:EffectMode (High-Performance Mode) Usage Guide | |
Retrieve device tier | |
Enable mute (as some stickers may contain audio) | |
Enable or disable a specific feature | |
Set the image orientation to enable AI recognition of faces in various orientations. If configured, this setting will override the orientation provided by sensorChanged. | |
Update Beauty Enhancement Attributes (New in V0.3.5.0) | |
Set the callback interface when creating the beauty filter object (this interface will be called back if an error occurs) | |
Set the dynamic effect prompt callback function to display the prompt message on the frontend page. | |
Configure the callback for facial landmark data and related information (Note: A valid facial landmark license authorization, such as Atomic Capability X102, is required to enable this callback feature). | |
Configure callback for face, gesture, and body detection status | |
Determine whether the current device supports beauty filters (OpenGL 3.0) | |
Returns the list of atomic capabilities supported by the current device. | |
Check whether the current device supports this asset. | |
Enable synchronous processing of video frames. | |
Set the centered crop ratio of the output texture |
/// Set the local path for storing beauty resources. This method must be called before using beauty effects./// Added in v0.3.5.0. void setResourcePath(String xmagicResDir);
Parameter | Description |
String xmagicResDir | The resource directory. |
V0.3.1.1, this method must be called before using beauty effects. Starting from V0.3.5.0, this method only needs to be called once per version, and the setResourcePath method must be called before this method to set the resource path. In V0.3.5.0, the previous xmagicResDir parameter has been removed. Please refer to the latest demo for more information.void initXmagic(InitXmagicCallBack callBack);typedef InitXmagicCallBack = void Function(bool reslut);
void initXmagic(String xmagicResDir,InitXmagicCallBack callBack);typedef InitXmagicCallBack = void Function(bool reslut);
Parameter | Description |
String xmagicResDir | The resource directory. |
InitXmagicCallBack callBack | The initialization callback. |
///Set the Tencent Effect licensevoid setLicense(String licenseKey, String licenseUrl, LicenseCheckListener checkListener);//The callback of the authorization resulttypedef LicenseCheckListener = void Function(int errorCode, String msg);
Parameter | Description |
String licenseKey | The license key. |
String licenseUrl | The license URL. |
LicenseCheckListener checkListener | The callback of the authorization result. |
void setXmagicLogLevel(int logLevel);
Parameter | Description |
int logLevel | You can set the log level using a type defined for LogLevel. |
void onResume();
void onPause();
void enableEnhancedMode();
void setEffectMode(EffectMode effectMode);
Future<int> getDeviceLevel();
/// Is the background music muted? void setAudioMute(bool isMute);
/// enable or disable one feature void setFeatureEnableDisable(String featureName, bool enable);
Parameter | Meaning |
String featureName | feature Name Values: "ai.segmentation.skin.enable" Skin segmentation capability, when enabled, allows for more precise skin smoothing and whitening areas."ai.segmentation.faceBlock.enable" The facial occlusion detection feature, when enabled, prevents makeup from being applied to obstructed areas."beauty.onlyWhitenSkin" Whitening effects are exclusively applicable to the skin."auto_beauty_switch" Intelligent Beauty Enhancement (with reduced beautification effects for males and infants)"ai.3dmmV2.enable" facial expressions feature."ai.body3dpoint.enable" 3D body data feature."ai.hand.enable" gesture detection. |
boolean enable | "true" indicates enabling a capability, while "false" indicates disabling a capability. Note: If it is in downgrade mode, enabling skin segmentation is not allowed. |
void setImageOrientation(TEImageOrientation orientation);enum TEImageOrientation {ROTATION_0,ROTATION_90,ROTATION_180,ROTATION_270,}

void setSyncMode(bool isSync , int syncFrameCount);
Parameter | Meaning |
isSync | Whether to process image frames synchronously. |
syncFrameCount | The number of frames to be processed synchronously, with a value >=0. A value of -1 indicates an unlimited number of frames. |
///update beautification parameters void setEffect(String effectName,int effectValue,String? resourcePath,Map<String,String>? extraInfo);
void setOnCreateXmagicApiErrorListener(OnCreateXmagicApiErrorListener? errorListener);/// The callback for errors for the creation of an effect objecttypedef OnCreateXmagicApiErrorListener = void Function(String errorMsg, int code);
Parameter | Description |
OnCreateXmagicApiErrorListener? errorListener | The callback for errors for the creation of an effect object. |
Error Code | Description |
-1 | Unknown error. |
-100 | Failed to initialize the 3D engine. |
-200 | GAN materials are not supported. |
-300 | The device does not support this material component. |
-400 | The JSON template is empty. |
-500 | The SDK version is too old. |
-600 | Keying is not supported. |
-700 | OpenGL is not supported. |
-800 | The script is not supported. |
5000 | The resolution of the video to be keyed exceeds 2160 x 3840. |
5001 | Insufficient memory for keying. |
5002 | Failed to parse the video to be keyed. |
5003 | The video to be keyed is longer than 200 seconds. |
5004 | Unsupported video format for keying. |
void setTipsListener(XmagicTipsListener? xmagicTipsListener);abstract class XmagicTipsListener {/// Show the tip/// @param tips: The content of the tip (string)./// @param tipsIcon: The icon for the tip./// @param type: The display type. If it is set to `0`, both the tip string and icon will be displayed. If it is set to `1`, only the icon will be displayed for PAG materials./// @param duration: How long (milliseconds) to show the tip.void tipsNeedShow(String tips, String tipsIcon, int type, int duration);/// */// Hide the tip/// @param tips: The content of the tip (string)./// @param tipsIcon: The icon for the tip./// @param type: The display type. If it is set to `0`, both the tip string and icon will be displayed. If it is set to `1`, only the icon will be displayed for PAG materials.void tipsNeedHide(String tips, String tipsIcon, int type);}
Parameter | Description |
XmagicTipsListener xmagicTipsListener | The callback implementation class. |
/// Configure the callback of facial keypoints and other data (only available in S1 - 05 and S1 - 06)void setYTDataListener(XmagicYTDataListener? xmagicYTDataListener);Configure the callback of facial keypoints and other dataabstract class XmagicYTDataListener {// YouTu AI datavoid onYTDataUpdate(String data);}
onYTDataUpdate returns a JSON string structure that contains the information of up to 5 faces:{"face_info":[{"trace_id":5,"face_256_point":[180.0,112.2,...],"face_256_visible":[0.85,...],"out_of_screen":true,"left_eye_high_vis_ratio:1.0,"right_eye_high_vis_ratio":1.0,"left_eyebrow_high_vis_ratio":1.0,"right_eyebrow_high_vis_ratio":1.0,"mouth_high_vis_ratio":1.0},...]}
Field | Type | Range | Description |
trace_id | int | [1,INF) | The face ID. If the faces obtained from a continuous video stream have the same face ID, they belong to the same person. |
face_256_point | float | [0,screenWidth] or [0,screenHeight] | 512 values in total for 256 facial keypoints. (0,0) is the top-left corner of the screen. |
face_256_visible | float | [0,1] | The visibility of the 256 facial keypoints. |
out_of_screen | bool | true/false | Whether only part of the face is captured. |
left_eye_high_vis_ratio | float | [0,1] | The percentage of keypoints with high visibility for the left eye. |
right_eye_high_vis_ratio | float | [0,1] | The percentage of keypoints with high visibility for the right eye. |
left_eyebrow_high_vis_ratio | float | [0,1] | The percentage of keypoints with high visibility for the left eyebrow. |
right_eyebrow_high_vis_ratio | float | [0,1] | The percentage of keypoints with high visibility for the right eyebrow. |
mouth_high_vis_ratio | float | [0,1] | The percentage of keypoints with high visibility for the mouth. |
Parameter | Description |
XmagicYTDataListener | The callback implementation class. |
void setAIDataListener(XmagicAIDataListener? aiDataListener);abstract class XmagicAIDataListener {void onFaceDataUpdated(String faceDataList);void onHandDataUpdated(String handDataList);void onBodyDataUpdated(String bodyDataList);}
Future<bool> isSupportBeauty();
getPropertyRequiredAbilities.Future<Map<String, bool>> getDeviceAbilities();
Map<String,Boolean>:Future<bool> isDeviceSupportMotion(String motionResPath);
Parameter | Description |
motionResPath | The sticker local file path |
void setOutputTextureKeepRatio(float ratio)
Parameter | Meaning |
ratio | Crop ratio, value range (0, 1]. For example, 0.8f means keeping 80% of the original output texture's center after cropping; 1f means no cropping. If an invalid value is passed, this call will be ignored. |
void setDowngradePerformance();
void updateProperty(XmagicProperty xmagicProperty);
Parameter | Meaning |
XmagicProperty xmagicProperty | Beauty attribute encapsulation object |
Future<List<XmagicProperty>> isBeautyAuthorized(List<XmagicProperty> properties);
Parameter | Meaning |
List<XmagicProperty> properties | Beauty enhancement items to be detected |
Future<List<XmagicProperty>> isDeviceSupport(List<XmagicProperty> assetsList);
Parameter | Meaning |
List<XmagicProperty> assetsList | List of motion graphic assets requiring inspection |
getDeviceAbilities first to get the capabilities supported by their device. The result is then passed to the server. For example, if a user’s device supports capabilities A, B, and C, but not D, the server will not provide material 2 to the user.Future<Map<XmagicProperty, List<String>?>> getPropertyRequiredAbilities(List<XmagicProperty> assetsList);
Parameter | Description |
List<XmagicProperty> assetsList | A list of the animated effects to check. |
Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback