帮你快速理解、总结文档立即下载
文档中心>短视频 SDK>不含 UI 集成方案>精简版/基础版集成指引>美颜特效>SDK 集成指引>Android

Android

最近更新时间：2026-10-09 15:14:00
我的收藏

本页目录：

开发者环境要求

建议使用 Android 7.0 （SDK API Level 24）及以上设备，Android Studio 3.5 及以上版本。

集成 SDK

腾讯特效 SDK 已经发布到 mavenCentral 库，您可以通过配置 gradle 自动下载更新。
1. 在 dependencies 中添加美颜特效 SDK 的依赖。
dependencies {
 //例如：S1-04套餐如下：
 implementation 'com.tencent.mediacloud:TencentEffect_S1-04:版本号'
//“版本号”可以在官网的“SDK下载/版本历史”页面看到，例如 3.0.0.13。“版本号”也可以使用"latest.release" ，
//但请注意：这会让您使用的SDK始终保持最新版，在一些变化比较大的版本上可能不符合您的预期，请慎重使用"latest.release"
}
2. 在 defaultConfig 中，指定 App 使用的 CPU 架构。
defaultConfig {
 ndk {
     abiFilters "armeabi-v7a", "arm64-v8a"
 }
}
说明：
目前特效 SDK 支持 armeabi-v7a 和 arm64-v8a。
3. 单击
img

Sync Now，自动下载 SDK 并集成到工程里。
各套餐对应的 Maven 地址：
版本
Maven 地址
A1 - 01
implementation 'com.tencent.mediacloud:TencentEffect_A1-01:版本号'
A1 - 02
implementation 'com.tencent.mediacloud:TencentEffect_A1-02:版本号'
A1 - 03
implementation 'com.tencent.mediacloud:TencentEffect_A1-03:版本号'
A1 - 04
implementation 'com.tencent.mediacloud:TencentEffect_A1-04:版本号'
A1 - 05
implementation 'com.tencent.mediacloud:TencentEffect_A1-05:版本号'
A1 - 06
implementation 'com.tencent.mediacloud:TencentEffect_A1-06:版本号'
S1 - 00
implementation 'com.tencent.mediacloud:TencentEffect_S1-00:版本号'
S1 - 01
implementation 'com.tencent.mediacloud:TencentEffect_S1-01:版本号'
S1 - 02
implementation 'com.tencent.mediacloud:TencentEffect_S1-02:版本号'
S1 - 03
implementation 'com.tencent.mediacloud:TencentEffect_S1-03:版本号'
S1 - 04
implementation 'com.tencent.mediacloud:TencentEffect_S1-04:版本号'
S1 - 05
implementation 'com.tencent.mediacloud:TencentEffect_S1-05:版本号'
S1 - 06
implementation 'com.tencent.mediacloud:TencentEffect_S1-06:版本号'
S1 - 07
implementation 'com.tencent.mediacloud:TencentEffect_S1-07:版本号'
注意：
更多集成方式请参考 腾讯特效 SDK 文档。

集成素材

如果您的套餐包含动效和滤镜功能，那么需要在 SDK 下载页面 下载对应的套餐包，解压之后，将 resource 目录下的 lut 和 MotionRes 放置到您工程的 assets 目录下：
动效：..src/main/assets/MotionRes
滤镜：..src/main/assets/lut
更多素材配置可参考 素材使用指南。
注意：
SDK 中包含的素材是测试素材，正式素材需要您在购买套餐之后 联系我们 进行获取。

SDK 使用流程

步骤一：鉴权

1. 申请授权，得到 License URL 和 License KEY，请参见腾讯特效 License 指引。
2. 在相关业务模块的初始化代码中设置 URL 和 KEY，触发 License 下载，避免在使用前才临时去下载。例如我们的 demo 工程是在 Application 的 onCreate 方法里触发下载，但在您的项目中不建议在这里触发，因为此时可能没有网络权限或联网失败率较高，请选择更合适的时机触发 license 下载。
//如果仅仅是为了触发下载或更新license，而不关心鉴权结果，则第4个参数传入null。
TELicenseCheck.getInstance().setTELicense(context, URL, KEY, null);
3. 然后在真正要使用美颜功能前，再去做鉴权：
TELicenseCheck.getInstance().setTELicense(context, URL, KEY, new TELicenseCheckListener() {

         @Override
         public void onLicenseCheckFinish(int errorCode, String msg) {
             //注意：此回调不一定在调用线程
             if (errorCode == TELicenseCheck.ERROR_OK) {
                 //鉴权成功
             } else {
                 //鉴权失败
             }
         }
     });

鉴权 errorCode 说明：

错误码
说明
0
成功。Success。
-1
输入参数无效，例如 URL 或 KEY 为空。
-3
下载环节失败，请检查网络设置。
-4
从本地读取的 TE 授权信息为空，可能是 IO 失败引起。
-5
读取 VCUBE TEMP License 文件内容为空，可能是 IO 失败引起。
-6
v_cube.license 文件 JSON 字段不对。请联系腾讯云团队处理。
-7
签名校验失败。请联系腾讯云团队处理。
-8
解密失败。请联系腾讯云团队处理。
-9
TELicense 字段里的 JSON 字段不对。请联系腾讯云团队处理。
-10
从网络解析的 TE 授权信息为空。请联系腾讯云团队处理。
-11
把 TE 授权信息写到本地文件时失败，可能是 IO 失败引起。
-12
下载失败，解析本地 asset 也失败。
-13
鉴权失败，请检查 so 是否在包里，或者已正确设置 so 路径。
3004/3005
无效授权。请联系腾讯云团队处理。
3015
Bundle Id / Package Name 不匹配。检查您的 App 使用的 Bundle Id / Package Name 和申请的是否一致，检查是否使用了正确的授权文件。
3018
授权文件已过期，需要向腾讯云申请续期。
其他
请联系腾讯云团队处理。

步骤二：资源拷贝

这里所指的资源文件包含两部分：
SDK 的模型文件，位于 SDK 的 aar 包的 assets 目录。
滤镜和动效资源文件，位于 demo 工程的 assets 目录，命名分别是 lut 和 MotionRes。
使用美颜前需要将上述资源拷贝到 app 的私有目录。在未更新 SDK 版本的情况下，只需要拷贝一次。拷贝成功后，您可以在 App 的 SharedPreference 中记录下来，下次就不用再拷贝了。 具体可以参见 demo 工程的 TEMenuActivity.java
String resPath = new File(getFilesDir(), AppConfig.getInstance().getBeautyFileDirName()).getAbsolutePath();
if (!resPath.endsWith(File.separator)) {
    resPath = resPath + File.separator;
}
AppConfig.resPathForSDK = resPath;
AppConfig.lutFilterPath = resPath + "light_material/lut";
AppConfig.motionResPath = resPath + "MotionRes";


new Thread(() -> {
    Context context = getApplicationContext();
    int addResult = XmagicApi.addAiModeFilesFromAssets(context, AppConfig.resPathForSDK);
    Log.d(TAG, "copyRes, add ai model files result = " + addResult);

    String lutDirNameInAsset = "lut";
    boolean result = FileUtil.copyAssets(context, lutDirNameInAsset, AppConfig.lutFilterPath);
    Log.d(TAG, "copyRes, copy lut, result = " + result);

    String motionResDirNameInAsset = "MotionRes";
    boolean result2 = FileUtil.copyAssets(context, motionResDirNameInAsset, AppConfig.motionResPath);
    Log.d(TAG, "copyRes, copy motion res, result = " + result2);
}).start();

步骤三：SDK 初始化及使用方法

1. 初始化。
XmagicApi xmagicApi = new XmagicApi(context, effectMode, mResPath, (errorMsg, code) -> {
            LogUtils.e(TAG, "createXMagicApi  errorMsg = " + errorMsg + "  code = " + code);
        });
2. 调用 TXUGCRecord 的 setVideoProcessListener 方法设置预处理回调接口。
  TXUGCRecord instance = TXUGCRecord.getInstance(UGCKit.getAppContext());
        instance.setVideoProcessListener(new TXUGCRecord.VideoCustomProcessListener() {
            @Override
            public int onTextureCustomProcess(int textureId, int width, int height) {
                if (xmagicApi != null) {
                    return xmagicApi.process(textureId, width, height);
                }
                return textureId;
            }

            @Override
            public void onDetectFacePoints(float[] floats) {
            }

            @Override
            public void onTextureDestroyed() {
                if (Looper.getMainLooper() != Looper.myLooper()) { //非主线程
                    xmagicApi.onDestroy()
                }
            }
        });
3. 设置美颜属性，具体参数请参考 美颜参数说明。
xmagicApi.seteffect();
4. 销毁，注意需要在 onTextureDestroyed 中判断是 GL 线程时销毁。
xmagicApi.onDestroy()
中国站