tencent cloud

腾讯特效 SDK

动态与公告
产品动态
关于腾讯特效 SDK V3.5 版本更新公告
关于腾讯特效 SDK V3.0 版本相关接口及素材变更公告
产品简介
产品概述
产品功能
基本概念
产品优势
应用场景
购买指南
价格总览
购买流程
欠费退费说明
新手指引
Demo 体验
免费测试
License 指引
移动端 License 新增与续期
PC 端 License 新增与续期
Web端 License 新增与续期
常见问题
SDK 下载
功能说明
SDK 下载
版本历史
SDK 集成指引(无 UI)
通用集成腾讯特效
原子能力集成指引
SDK 集成指引(含 UI)
通用集成腾讯特效
直播 SDK 集成腾讯特效
TRTC SDK 集成腾讯特效
短视频 SDK 集成腾讯特效
Avatar 虚拟人集成指引
API 文档
iOS
Android
Flutter
Web
功能实践
SDK 包瘦身
SDK 集成问题排查
性能调优
效果调优
素材使用
美颜参数说明
美颜场景推荐参数
短视频企业版迁移指引
第三方推流接入美颜(Flutter)
小程序美颜特效实践
素材制作工具使用
Web 美颜特效
产品概述
快速上手
SDK 接入
API 文档
控制台指南
Demo 体验
内置素材总览
实践教程
常见问题
常见问题
通用类相关
技术类相关
License 相关
旧版文档
美颜场景推荐参数
美颜参数表
一分钟集成 TRTC
一分钟集成直播
TE SDK 政策
隐私协议
数据处理和安全协议
联系我们

Flutter

PDF
聚焦模式
字号
最后更新时间: 2025-07-15 10:30:31
腾讯特效 SDK Flutter版本核心接口类 TencentEffectApi,更新美颜数值、调用动效等功能。

Public 成员函数

API
描述
设置美颜资源的本地存储路径(V0.3.5.0版本新增)
初始化美颜数据,使用美颜前必须先调用此方法(在V0.3.1.1版本及之前)
进行美颜授权
设置 SDK 的 log 等级,建议开发调试时设为 Log.DEBUG,正式发布时设置为 Log.WARN,如果正式发布设置为 Log.DEBUG,大量的日志会影响性能
onResume
恢复渲染,页面可见时调用
onPause
暂停渲染,页面不可见时调用
开启美颜增强模式,具体请参考增强模式使用指南
调用此方法开启高性能模式。高性能模式开启后,美颜占用的系统 CPU/GPU 资源更少,可减少手机的发热和卡顿现象,更适合低端机长时间使用。注意:需要在调用其他方法之前调用
设置静音(因为有些贴纸中有声音)
开启或关闭某个特性
@Deprecated
更新美颜属性, 可在任意线程调用(此接口已废弃)
setEffect
更新美颜属性(V0.3.5.0版本新增)
设置创建美颜对象时的回调接口(如果出错会回调此接口)
设置动效提示语回调函数,用于将提示语展示到前端页面上
设置人脸点位信息等数据回调,需要获得人脸点位的 Licence 授权(例如原子能力X102)才会有回调。
设置人脸、手势、身体检测状态回调
@Deprecated
判断当前的 lic 授权支持哪些美颜。 仅支持 BEAUTY 和 BODY_BEAUTY 类型的美颜项检测。检测后的结果会赋值到各个美颜对象 XmagicProperty.isAuth 字段中(此接口已废弃)
判断当前机型是否支持美颜(OpenGL3.0)
返回当前设备支持的原子能力表
@Deprecated
将动效资源列表传入 SDK 中做检测,执行后 XmagicProperty.isSupport 字段标识该原子能力是否可用。 根据 XmagicProperty.isSupport 可 UI 层控制单击限制,或者直接从资源列表删除(此接口已废弃)
检测当前设备是否支持此素材
@Deprecated
传入一个动效资源列表,返回每一个资源所使用到的 SDK 原子能力列表(此接口已废弃)

成员函数说明

setResourcePath (V0.3.5.0版本新增)

设置美颜资源存放的本地路径
///设置美颜资源存放的本地路径,使用美颜前必须先调用此方法。 ///v0.3.5.0新增 void setResourcePath(String xmagicResDir);

参数

参数
含义
String xmagicResDir
资源文件放置的目录

initXmagic

初始化美颜数据。在V0.3.1.1版本及之前,使用美颜前必须先调用此方法。在V0.3.5.0版本,此方法每个版本只需要调用一次,并且在调用了此方法之前必须先调用setResourcePath方法设置了资源路径,在V0.3.5.0版本中删除了之前的 xmagicResDir 参数,可参考最新 demo。
V0.3.5.0版本
void initXmagic(InitXmagicCallBack callBack);

typedef InitXmagicCallBack = void Function(bool reslut);
V0.3.1.1版本及之前
void initXmagic(String xmagicResDir,InitXmagicCallBack callBack);

typedef InitXmagicCallBack = void Function(bool reslut);

参数

参数
含义
String xmagicResDir
资源文件放置的目录
InitXmagicCallBack callBack
初始化回调接口

setLicense

设置鉴权数据,进行美颜授权。
///美颜进行鉴权处理
void setLicense(String licenseKey, String licenseUrl, LicenseCheckListener checkListener);
///授权校验的结果回调方法
typedef LicenseCheckListener = void Function(int errorCode, String msg);

参数

参数
含义
String licenseKey
鉴权的 LicenseKey
String licenseUrl
鉴权的 LicenseUrl
LicenseCheckListener checkListener
授权结果回调接口

setXmagicLogLevel

设置 SDK 的 log 等级
void setXmagicLogLevel(int logLevel);

参数

参数
含义
int logLevel
可使用 LogLevel 定义好的类型进行设置

onResume

恢复美颜处理
void onResume();

onPause

暂停美颜处理
void onPause();

enableEnhancedMode

开启增强模式,具体请参考增强模式使用指南
void enableEnhancedMode();

setDowngradePerformance(V0.3.1.1新增)

开启性能模式
void setDowngradePerformance();

setAudioMute(V0.3.1.1新增)

设置是否静音。参数:true 表示静音,false 表示非静音。
///背景音乐是否静音 void setAudioMute(bool isMute);

setFeatureEnableDisable(V0.3.1.1新增)

开启或关闭某个能力
/// 开启或关闭某个特性 void setFeatureEnableDisable(String featureName, bool enable);

参数

参数
含义
String featureName
原子能力名称
取值如下:
"ai.3dmmV2.enable" 人脸表情能力
"ai.body3dpoint.enable" 身体点位能力
"ai.hand.enable" 手势检测能力
"beauty.onlyWhitenSkin" 美白仅对皮肤生效
"ai.segmentation.skin.enable" 皮肤分割能力
"auto_beauty_switch" 智能美颜(为男性、宝宝减淡美颜美妆效果)
boolean enable
true 表示开启此能力,false 表示关闭此能力
注:如果是降级模式,则不允许开启皮肤分割

updateProperty(此接口已废弃)

设置某一项美颜数值或者动效、滤镜,可在任意线程调用。
void updateProperty(XmagicProperty xmagicProperty);

参数

参数
含义
XmagicProperty xmagicProperty
美颜属性封装对象

setEffect(V0.3.5.0新增)

设置美颜、美型、滤镜、美妆、贴纸、分割等效果,可在任意线程调用。具体参数请参考 美颜参数说明
///更新美颜属性。 void setEffect(String effectName,int effectValue,String? resourcePath,Map<String,String>? extraInfo);

setOnCreateXmagicApiErrorListener

设置美颜对象创建时的错误回调接口
void setOnCreateXmagicApiErrorListener(OnCreateXmagicApiErrorListener? errorListener);
///创建美颜实例时的错误回调方法
typedef OnCreateXmagicApiErrorListener = void Function(String errorMsg, int code);

参数

参数
含义
OnCreateXmagicApiErrorListener? errorListener
创建美颜对象时错误信息回调接口
返回错误码含义对照表:
错误码
含义
-1
未知错误
-100
3D 引擎资源初始化失败
-200
不支持 GAN 素材
-300
设备不支持此素材组件
-400
模板 JSON 内容为空
-500
SDK 版本过低
-600
不支持分割
-700
不支持 OpenGL
-800
不支持脚本
5000
分割背景图片分辨率超过 2160×3840
5001
分割背景图片所需内存不足
5002
分割背景视频解析失败。
5003
分割背景视频超过200秒
5004
分割背景视频格式不支持

setTipsListener

设置动效提示语回调函数,用于将提示语展示到前端页面上。比如某些素材会提示用户点点头、伸出手掌、比心等。
void setTipsListener(XmagicTipsListener? xmagicTipsListener);

abstract class XmagicTipsListener {
/// 显示tips。Show the tip.
/// @param tips tips字符串。Tip's content
/// @param tipsIcon tips的icon。Tip's icon
/// @param type tips类别,0表示字符串和icon都展示,1表示是pag素材只展示icon。tips category, 0 means that both strings and icons are displayed, 1 means that only the icon is displayed for the pag material
/// @param duration tips显示时长, 毫秒。Tips display duration, milliseconds
void tipsNeedShow(String tips, String tipsIcon, int type, int duration);

/// *
/// 隐藏tips。Hide the tip.
/// @param tips tips字符串。Tip's content
/// @param tipsIcon tips的icon。Tip's icon
/// @param type tips类别,0表示字符串和icon都展示,1表示是pag素材只展示icon。tips category, 0 means that both strings and icons are displayed, 1 means that only the icon is displayed for the pag material
void tipsNeedHide(String tips, String tipsIcon, int type);
}

参数

参数
含义
XmagicTipsListener xmagicTipsListener
回调函数实现类

setYTDataListener

设置人脸点位信息等数据回调。
///设置人脸点位信息等数据回调(S1-05 和 S1-06 套餐才会有回调)
void setYTDataListener(XmagicYTDataListener? xmagicYTDataListener);
设置人脸信息等数据回调

abstract class XmagicYTDataListener {
//优图AI数据回调。
void onYTDataUpdate(String data);
}
onYTDataUpdate 返回 JSON string 结构,最多返回5个人脸信息:
{
"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
},
...
]
}

字段含义

字段
类型
值域
说明
trace_id
int
[1,INF)
人脸 ID,连续取流过程中,ID 相同的可以认为是同一张人脸
face_256_point
float
[0,screenWidth] 或 [0,screenHeight]
共512个数,人脸256个关键点,屏幕左上角为(0,0)
face_256_visible
float
[0,1]
人脸256关键点可见度
out_of_screen
bool
true/false
人脸是否出框
left_eye_high_vis_ratio
float
[0,1]
左眼高可见度点位占比
right_eye_high_vis_ratio
float
[0,1]
右眼高可见度点位占比
left_eyebrow_high_vis_ratio
float
[0,1]
左眉高可见度点位占比
right_eyebrow_high_vis_ratio
float
[0,1]
右眉高可见度点位占比
mouth_high_vis_ratio
float
[0,1]
嘴高可见度点位占比

参数

参数
含义
XmagicYTDataListener xmagicYTDataListener
回调函数实现类

setAIDataListener

检测到人脸、身体、手势时,会回调这些部位的点位信息。
void setAIDataListener(XmagicAIDataListener? aiDataListener);

abstract class XmagicAIDataListener {
void onFaceDataUpdated(String faceDataList);

void onHandDataUpdated(String handDataList);

void onBodyDataUpdated(String bodyDataList);
}

isBeautyAuthorized(此接口已废弃)

判断当前的 License 授权支持哪些美颜或美体项。 仅支持 BEAUTY 和 BODY_BEAUTY 类型的美颜项检测。检测后的结果会赋值到各个美颜对象 XmagicProperty.isAuth 字段中。如果 isAuth 字段为 false,可以在 UI 上屏蔽这些项的入口。
Future<List<XmagicProperty>> isBeautyAuthorized(
List<XmagicProperty> properties);

参数

参数
含义
List<XmagicProperty> properties
需要检测的美颜项

isSupportBeauty

判断当前机型是否支持美颜(OpenGL3.0)。
Future<bool> isSupportBeauty();

返回

返回值 bool:是否支持支持美颜。

getDeviceAbilities

返回当前设备支持的原子能力表。与 getPropertyRequiredAbilities 方法搭配使用.
Future<Map<String, bool>> getDeviceAbilities();

返回

返回值 Map<String,bool>
key:原子能力名(与素材能力名字对应)。
value:当前设备是否支持。

isDeviceSupport

将动效资源列表传入 SDK 中做检测,执行后 XmagicProperty.isSupport 字段标识该素材是否可用。根据XmagicProperty.isSupport 可 UI 层控制单击限制,或者直接从资源列表删除。
Future<List<XmagicProperty>> isDeviceSupport(List<XmagicProperty> assetsList);

参数

参数
含义
List<XmagicProperty> assetsList
需要检测的动效素材列表

isDeviceSupportMotion (V0.3.5.0版本新增)

检测当前设备是否支持此素材
Future<bool> isDeviceSupportMotion(String motionResPath);

参数

参数
含义
motionResPath
需要检测的动效素材的本地文件地址

getPropertyRequiredAbilities

传入一个动效资源列表,返回每一个资源所使用到的 SDK 原子能力列表。 方法的使用场景为: 您购买或制作了若干款动效素材,调用这个方法,会返回每一个素材需要使用的原子能力列表。例如素材1需要使用能力 A、B、C,素材2需要使用能力 B、C、D,然后您把这样的能力列表保持在服务器上。之后,当用户要从服务器下载动效素材时,用户先通过 getDeviceAbilities 方法获取他手机具备的原子能力列表(比如这台手机具备能力 A、B、C,但不具备能力 D),把他的能力列表传给服务器,服务器判断该设备不具备能力 D,因此不给该用户下发素材2。
Future<Map<XmagicProperty, List<String>?>> getPropertyRequiredAbilities(
List<XmagicProperty> assetsList);

参数

参数
含义
List<XmagicProperty> assetsList
需要检测原子能力的动效资源列表

返回

返回值 Map<XmagicProperty, List<String>?> :
key:动效资源素材实体类。
value:所使用到的原子能力列表。

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈