帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>直播与语聊房（含 UI）>UI 组件库>美颜调节面板>美颜调节面板 (Android Java)

美颜调节面板 (Android Java)

最近更新时间：2026-09-09 16:58:43
我的收藏

本页目录：

TUILiveKit 提供了两种美颜特效方案：基础美颜（内置）和高级美颜（需额外集成和付费）。您可以根据自己的需求选择合适的方案。
基础美颜
基础美颜功能已默认集成在 TUILiveKit 中，无需任何额外配置。它提供了美白、磨皮和红润效果，并支持美颜强度调节。
高级美颜
高级美颜采用腾讯特效 SDK，提供了更加丰富和专业的美颜效果，例如 V 脸、眼距、瘦鼻、3D 贴纸等。
注意：
高级美颜功能需要单独付费，详情请参见 腾讯特效 SDK。

效果展示

v 脸
眼距
瘦鼻
3D 贴纸













前提条件

参考 准备工作 完成 TUILiveKit 组件接入。

组件接入

步骤 1：集成 tebeautykit 适配模块

下载并拷贝文件：下载并解压 TUILiveKit，将 Android/tebeautykit 文件夹拷贝到您工程的根目录，使其与 app 文件夹同级。

注意：
该模块是 TUILiveKit 与腾讯特效 SDK 之间的适配层。模块内置的 TEBeautyProvider（ContentProvider）会在 App 启动时自动通过 TUICore 注册扩展与服务，TUILiveKit 检测到后会自动启用高级美颜面板与视频处理链路；未集成时则自动回退到基础美颜。

步骤 2：下载并导入美颜面板资源（必做）

高级美颜面板的 UI 与素材（面板配置 JSON、滤镜 LUT、2D/3D 动效贴纸、美妆、人像分割、面板图标等）不随 tebeautykit 模块发布，也不在 TUILiveKit 的开源仓库中。您需要从腾讯特效 SDK 官方按所购套餐获取完整资源包，再合并到 tebeautykit 模块的 assets/ 目录下。
1. 前往 腾讯特效 SDK 资源下载页 下载与您所购套餐匹配的 Android 资源包；如果下载页未提供，请联系腾讯特效 SDK 商务支持获取与 License 匹配的资源包。
2. 把官方资源包解压后的内容按以下结构合并到 tebeautykit/src/main/assets/ 目录下：
tebeautykit/src/main/assets/
├── beauty_panel/                  # 面板 JSON 配置 + 图标
│   ├── beauty.json
│   ├── beauty_template.json
│   ├── beauty_image.json
│   ├── beauty_shape.json
│   ├── beauty_base_shape.json
│   ├── beauty_general_shape.json
│   ├── beauty_makeup.json
│   ├── beauty_body.json
│   ├── light_makeup.json
│   ├── makeup.json
│   ├── motion_2d.json
│   ├── motion_3d.json
│   ├── motion_gesture.json
│   ├── segmentation.json
│   ├── lut.json
│   └── panel_icon/                # 面板内的所有 PNG 图标
├── lut/                           # 滤镜 LUT 调色图
│   ├── baixi_lf.png
│   ├── dongjing_lf.png
│   ├── moren_lf.png
│   ├── xindong_lf.png
│   └── ziran_lf.png
└── MotionRes/                     # 动效 / 美妆 / 分割素材
    ├── 2dMotionRes/               # 2D 动效贴纸
    ├── 3dMotionRes/               # 3D 动效贴纸
    ├── handMotionRes/             # 手势贴纸
    ├── ganMotionRes/              # 一镜到底动效
    ├── makeupRes/                 # 整妆套装
    ├── light_makeup/              # 轻美妆
    └── segmentMotionRes/          # 人像分割 / 绿幕
注意：
实际包含哪些 JSON 与子目录，由您所购买的套餐能力决定，详见下方的「套餐 → JSON 清单」对照表。
3. 各资源用途说明：
资源
用途
对应面板能力
assets/beauty_panel/*.json
面板 UI 配置（分组、按钮、滑杆）
整体面板
assets/beauty_panel/panel_icon/
面板按钮图标 PNG
整体面板
assets/lut/
滤镜调色查找表
滤镜 Tab
assets/MotionRes/2dMotionRes/
2D 动态贴纸 / 大头特效
贴纸 Tab
assets/MotionRes/3dMotionRes/
3D 模型贴纸
贴纸 Tab
assets/MotionRes/handMotionRes/
手势触发贴纸
手势 Tab
assets/MotionRes/makeupRes/
整妆套装（口红 + 眼影 + 腮红 等）
美妆 Tab
assets/MotionRes/light_makeup/
轻美妆素材
轻美妆 Tab
assets/MotionRes/segmentMotionRes/
人像分割（绿幕 / 抠图 / 背景虚化）
分割 Tab
4. 套餐与 panel JSON 对照表——必须把所选 BeautyLevel 对应的所有 JSON 都导入，否则相关 Tab 会缺失或空白：
套餐 (BeautyLevel)
需要导入的 panel JSON（全集）
A1_00
beauty_template, beauty, lut
A1_01
beauty_template, beauty, beauty_image, beauty_base_shape, lut
A1_02
beauty_template, beauty, beauty_image, beauty_base_shape, lut, motion_2d
A1_03
beauty_template, beauty, beauty_image, beauty_general_shape, lut, motion_2d
A1_04
beauty_template, beauty, beauty_image, beauty_general_shape, lut
A1_05
beauty_template, beauty, beauty_image, beauty_general_shape, lut, motion_2d, segmentation
A1_06
beauty_template, beauty, beauty_image, beauty_general_shape, lut, motion_2d, makeup
S1_00
beauty_template, beauty, beauty_image, beauty_shape, beauty_makeup, lut
S1_01
beauty_template, beauty, beauty_image, beauty_shape, beauty_makeup, lut, motion_2d, motion_3d, makeup, light_makeup
S1_02
beauty_template, beauty, beauty_image, beauty_shape, beauty_makeup, lut, motion_2d, motion_3d, motion_gesture, makeup, light_makeup
S1_03
beauty_template, beauty, beauty_image, beauty_shape, beauty_makeup, lut, motion_2d, motion_3d, makeup, light_makeup, segmentation
S1_04
beauty_template, beauty, beauty_image, beauty_shape, beauty_makeup, lut, motion_2d, motion_3d, motion_gesture, makeup, light_makeup, segmentation
S1_05
beauty_template, beauty, beauty_image, beauty_shape, beauty_makeup, lut, beauty_body, motion_2d, motion_3d, makeup, light_makeup, segmentation
S1_06
beauty_template, beauty, beauty_image, beauty_shape, beauty_makeup, lut, beauty_body, motion_2d, motion_3d, motion_gesture, makeup, light_makeup, segmentation
S1_07
beauty_template, beauty, beauty_image, beauty_shape, beauty_makeup, lut, beauty_body, motion_2d, motion_3d, motion_gesture, makeup, light_makeup, segmentation

步骤 3：工程配置

1. 编辑工程根目录的 settings.gradle 文件，引入 tebeautykit 模块：
include ':tebeautykit'
project(':tebeautykit').projectDir = new File(settingsDir, './tebeautykit')
2. 确保根目录 settings.gradle 的 dependencyResolutionManagement 中包含腾讯 Maven 源（tebeautykit 模块依赖的腾讯特效 SDK 从该源拉取）：
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://mirrors.tencent.com/repository/maven/thirdparty' }
    }
}
3. 在主 App 的 build.gradle 中加入对 tebeautykit 的依赖：
dependencies {
    api project(':tuilivekit')
    api project(':tebeautykit')     // 关键
}
注意：
tebeautykit/build.gradle 中已经声明了所需的腾讯特效 SDK 依赖（com.tencent.mediacloud:TEBeautyKit 与 com.tencent.mediacloud:TencentEffect_<套餐编号>），主 App 无需重复添加。如需更换套餐，请在 tebeautykit/build.gradle 中把 TencentEffect_S1-07 替换为对应套餐编号。

步骤 4：鉴权和初始化

在 Application.onCreate()（或登录页 Activity.onCreate()）中调用一次 API 即可完成 License 鉴权 + 资源拷贝 + 套餐与面板装配：
//
// App.kt
//

import android.app.Application
import com.tencent.effect.beautykit.tuiextension.BeautyLevel
import com.tencent.effect.beautykit.tuiextension.TUIBeautyKit

class App : Application() {
    override fun onCreate() {
        super.onCreate()

        // 一行完成：资源拷贝 + setTELicense + 选择套餐（默认 BeautyLevel.S1_07）
        TUIBeautyKit.instance.init(
            this,
            "YOUR_LICENSE_URL",
            "YOUR_LICENSE_KEY",
            BeautyLevel.S1_07              // 替换为您购买的套餐: A1_00 ... S1_07
        )
    }
}
BeautyLevel 可选值（与购买的腾讯特效 SDK 套餐一一对应）：
A1_00  A1_01  A1_02  A1_03  A1_04  A1_05  A1_06
S1_00  S1_01  S1_02  S1_03  S1_04  S1_05  S1_06  S1_07

验证

完成以上步骤后，启动 App 进入开播页面或观众预览页，点击美颜按钮：
看到 V 脸、瘦鼻、眼距、滤镜、贴纸、美妆、分割等多 Tab 面板 → 高级美颜接入成功
仍是只有美白 / 磨皮 / 红润 的三项基础面板 → 高级美颜扩展未注册成功，请检查：
主 App 的 build.gradle 是否依赖了 :tebeautykit module。
Application 是否调用了 TUIBeautyKit.instance.init(...)。
License 校验是否通过（查看 logcat 中 TEBeautySettings Tag 下 setTELicense callback 与 License Verification Success / Failed 日志）。
注意：
面板能打开但某个 Tab（如贴纸 / 滤镜 / 美妆 / 分割）为空白或图标缺失 → 步骤 2 中对应的资源未完整合并到 tebeautykit/src/main/assets/ 下。

常见问题

Q1：美颜资源可以放到 App 的其它目录（如 assets/my_beauty/、res/raw/、SD 卡或在线下载）吗？

不可以直接放，需要遵守以下两条规则：
面板 JSON 必须位于 assets/beauty_panel/ 下。tebeautykit 内部加载面板时传给 SDK 的是固定相对路径：
TEPanelDataModel("beauty_panel/beauty_template.json", TEUIProperty.UICategory.BEAUTY_TEMPLATE)
腾讯特效 SDK 会按这个路径直接从主 App 的 AssetManager 读取。若把 JSON 改到 assets/my_beauty/beauty_template.json 或挪到 res/raw/，SDK 是找不到的。各 JSON 内部对图标、MotionRes 子目录的引用（如 "icon": "beauty_panel/panel_icon/beauty/none.png"、"resourceUri": "MotionRes/3dMotionRes/video_zhixingmeigui"）也是同样的相对路径规则。
MotionRes/、lut/ 必须位于 assets/ 根层级。TUIBeautyKit.init() 内部调用 TEBeautyKit.setResPath(filesDir/xmagic) + TEBeautyKit.copyRes(context)，由 SDK 把 assets/MotionRes/、assets/lut/ 等资源拷贝到 filesDir/xmagic/ 下。这里 assets/ 是写死在 SDK 内部的查找根。
如果确实需要做"按需下载"，可在用户实际使用某个 Tab 前，自行下载对应素材到 filesDir/xmagic/MotionRes/...（与 copyRes 拷贝出的目录结构一致）；但 panel JSON 本身（即 assets/beauty_panel/*.json）仍必须打包在 App 内。
Q2：License 鉴权失败怎么办？
请检查 LicenseUrl / LicenseKey 是否与套餐绑定、所选 BeautyLevel 是否与 License 匹配，并确认应用的 applicationId 与 License 申请时绑定的包名一致。可在 logcat 中过滤 Tag TEBeautySettings，查看 setTELicense callback 的 error 与 msg 字段定位失败原因。
Q3：如何动态切换套餐？
TUIBeautyKit.instance.init(...) 是进程内幂等的，单次启动后再次传入不同 BeautyLevel 不会生效。如需动态切换，请重新启动进程；或直接修改 tebeautykit/build.gradle 中 TencentEffect_<套餐编号> 依赖并重新编译。
Q4：首次启动很慢，需要优化吗？
首次启动时 TEBeautyKit.copyRes(...) 会把 assets/ 下数百 MB 的素材拷贝到 filesDir/xmagic/，耗时与素材量正相关。TUIBeautyKit.init() 内部已用子线程异步拷贝，且通过 SharedPreferences 记录版本号，相同版本下次启动会跳过。如对包体积敏感，可只保留所购套餐用得到的素材子目录，删除不需要的 MotionRes/* 子集。

恭喜您

完成以上步骤后，即可成功集成 TUILiveKit 高级美颜功能。
中国站