文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>直播与语聊 SDK>UI 组件库>美颜调节面板>美颜调节面板（Flutter）

美颜调节面板（Flutter）

最近更新时间：2026-06-04 16:34:59

我的收藏

本页目录：

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



高级美颜效果展示

V 脸
眼距
瘦鼻
3D 贴纸













前提条件

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

组件接入

TUILiveKit 默认支持基础美颜，无需单独接入。如果您需要使用高级美颜，请按照以下流程完成接入工作。
注意：
高级美颜功能需要单独付费购买套餐，详情请参见 腾讯特效 SDK。

步骤 1：集成 te_beauty_kit 适配模块

下载并拷贝文件：从 GitHub 下载 TUIKit_Flutter 源码，将 te_beauty_kit 文件夹拷贝到您的工程，使其与 app 文件夹同级。

然后，在您的 Flutter 工程的 pubspec.yaml 文件里添加 te_beauty_kit 依赖：
dependencies:  
    te_beauty_kit:
      path: ../te_beauty_kit # 请使用您的真实路径
注意：
后续接入流程，需要使用您购买的美颜套餐。为了简化流程，将以美颜套餐 S1-07 为例，帮助您快速接入完整流程。组件接入完成之后，请按照 更换套餐，完成您实际套餐的更换工作。

步骤 2：集成美颜面板资源（必做）

美颜面板资源

美颜面板资源主要包括 2 部分：
面板配置素材：面板配置 JSON，相关图片等，用于展示美颜特效功能项。
资源
用途
assets/beauty_panel/*.json
面板 UI 配置（分组、按钮、滑杆）。
assets/beauty_panel/panel_icon/
面板按钮图标 PNG。
美颜特效素材：滤镜 LUT、2D/3D 动效贴纸等具体特效的素材。
资源
用途
对应面板能力
lut/
滤镜调色查找表。
滤镜 Tab
MotionRes/2dMotionRes/
2D 动态贴纸 / 大头特效。
贴纸 Tab
MotionRes/3dMotionRes/
3D 模型贴纸。
贴纸 Tab
MotionRes/handMotionRes/
手势触发贴纸。
手势 Tab
MotionRes/makeupRes/
整妆套装（口红 + 眼影 + 腮红 等）。
美妆 Tab
MotionRes/light_makeup/
轻美妆素材。
轻美妆 Tab
MotionRes/segmentMotionRes/
人像分割（绿幕 / 抠图 / 背景虚化）。
分割 Tab

集成美颜面板资源

1. 为便于快速集成，请从 GitHub 下载 TUIKit_Flutter ，从这里获取默认套餐 S1-07 的资源。
2. 集成面板配置素材：复制 TUIKit_Flutter/application/assets/beauty_panel 到您的 flutter 工程的 assets 目录。
application/assets/
├── beauty_panel/                  # 面板 JSON 配置 + 图标
│   ├── beauty.json
│   ├── beauty_template.json
│   ├── beauty_template_ios.json
│   ├── beauty_image.json
│   ├── beauty_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 图标
在您的 Flutter 工程的 pubspec.yaml 文件里，添加 assets 资源配置：
flutter:
  assets:
    - assets/beauty_panel/
    - assets/beauty_panel/panel_icon/beauty/
    - assets/beauty_panel/panel_icon/beauty/beauty_smooth/
    - assets/beauty_panel/panel_icon/beauty/eyes_makeup/
    - assets/beauty_panel/panel_icon/beauty/kouhong/
    - assets/beauty_panel/panel_icon/beauty/liti/
    - assets/beauty_panel/panel_icon/beauty/saihong/
    - assets/beauty_panel/panel_icon/beauty_body/
    - assets/beauty_panel/panel_icon/beauty_template/
    - assets/beauty_panel/panel_icon/light_makeup_icon/
    - assets/beauty_panel/panel_icon/lut_icon/
    - assets/beauty_panel/panel_icon/motions_icon/
3. 集成美颜特效素材，Android 和 iOS 需要分别集成：
Android
iOS
复制 TUIKit_Flutter/application/android/app/src/main/assets 下的 lut 和 MotionRes 2 个目录，到 Android app 的 assets 里。目录如下：
android/app/src/main/assets/
├── 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/          # 人像分割 / 绿幕
复制 TUIKit_Flutter/application/ios/xmagic 目录，到 iOS app 的根目录里。目录如下：
ios/                                   # 你的 ios 工程根目录
└── xmagic/
    ├── lut.bundle/                    # 滤镜 LUT 调色图
    ├── 2dMotionRes.bundle/            # 2D 动效贴纸素材
    ├── 3dMotionRes.bundle/            # 3D 动效贴纸素材
    ├── makeupMotionRes.bundle/        # 美妆素材
    ├── ganMotionRes.bundle/           # 一镜到底动效
    ├── handMotionRes.bundle/          # 手势贴纸
    ├── lightMakeupRes.bundle/         # 轻美妆素材       
    └── segmentMotionRes.bundle/       # 人像分割 / 绿幕素材
然后，把整个 xmagic/ 目录拖入 Xcode 工程，选择 Create folder references（蓝色文件夹），不要使用 group，并确保 Target Membership 勾选了主 App。
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. 在您的 Flutter 工程的 pubspec.yaml 文件里添加相关配置：
# pubspec.yaml

# 根级配置
EffectPlayer:
  sub_spec: 'NoXMagic'
TencentEffect:
  te_sub_spec: 'S1-07'
说明：
1. EffectPlayer.sub_spec ：可选值是 Default、NoXMagic。腾讯特效播放器和腾讯特效美颜这 2 个库如果一起使用，会出现 xmagic 库编译冲突问题。为了解决该问题，你可以设置 NoXMagic 方式，只编译一份 xmagic 库即可。TUILiveKit 默认接入了礼物组件 live_uikit_gift，而 live_uikit_gift 接入腾讯特效播放器。
2. TencentEffect.te_sub_spec ：设置您的套餐类型，更多类型请查看 步骤 2 第 4 步。
iOS 平台：如果 EffectPlayer.sub_spec 设置为 NoXMagic，iOS app 的 Podfile 文件中禁用 YTCommonXMagic。因为腾讯特效美颜默认会导入该库。
# 注释 YTCommonXMagic 库
# pod 'YTCommonXMagic', :podspec => 'https://mediacloud-76607.gzc.vod.tencent-cloud.com/MediaX/iOS/podspec/release/YTCommonXMagic_1.3.1/YTCommonXMagic.podspec'
Android 平台：确保根目录 settings.gradle 的 dependencyResolutionManagement 中包含腾讯 Maven 源（tebeautykit 模块依赖的腾讯特效 SDK 从该源拉取）：
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // 新增腾讯 Maven 源
        maven { url 'https://mirrors.tencent.com/repository/maven/thirdparty' }
    }
}
2. Android 和 iOS 原生层注册美颜处理器：
Android
iOS
package com.tencent.application

import android.os.Bundle
import android.os.PersistableBundle
import io.flutter.embedding.android.FlutterActivity
// 导入相关文件
import com.tencent.trtcplugin.TRTCPlugin
import com.tencent.effect.tencent_effect_flutter.XmagicProcesserFactory

class MainActivity: FlutterActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 注册美颜处理器
        TRTCPlugin.setBeautyProcesserFactory(XmagicProcesserFactory())
    }
}

import Flutter
import UIKit
// 导入相关文件
import tencent_effect_flutter
import tencent_rtc_sdk

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    
    // 注册美颜处理器
    let instance = XmagicProcesserFactory()
    TencentRTCCloud.setBeautyProcesserFactory(factory: instance)
    
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

步骤 4：鉴权和初始化

1. 在 main.dart 配置 te_beauty_kit 模块的国际化：
//
// main.dart
//

// 导入文件
import 'package:te_beauty_kit/te_beauty_kit.dart';

// 您自己的APP主类
class XXX extends StatelessWidget {
  const XXX({super.key});

 @override
  Widget build(BuildContext context) {
    return MaterialApp(
      ......
      localizationsDelegates: [
      ...LiveKitLocalizations.localizationsDelegates,
      // 新增 tebeautykit 模块的国际化
      ...TEBeautyKitLocalizations.localizationsDelegates,
      ],
      ......
    );
  }
}

2. 在 App 启动或登录时，设置 License 鉴权 和 美颜套餐类型：
// 导入文件
import 'package:te_beauty_kit/te_beauty_kit.dart';

// 初始化腾讯美颜
TUIBeautyKit.instance.init("YOUR_LICENSE_URL", "YOUR_LICENSE_KEY", BeautyLevel.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

更新套餐

1. 请确认您购买的套餐类型，并联系腾讯特效 SDK 商务支持，获取对应的美颜面板资源（包括面板配置素材和美颜特效素材）。
2. 参考 集成美颜面板资源，更换面板配置素材和美颜特效素材。
3. 参考 工程配置，修改 TencentEffect/te_sub_spec 配置的套餐类型。
4. 参考 鉴权和初始化 第 2 步，修改鉴权时传入的套餐类型。

验证

完成以上步骤后，启动 App 进入开播预览页，点击美颜按钮，查看弹出的美颜面板。

常见问题

License 鉴权失败怎么办？

请检查 LicenseUrl / LicenseKey 是否与套餐绑定、所选 BeautyLevel 是否与 License 匹配，并确认应用的 applicationId 与 License 申请时绑定的包名一致。

是否支持动态切换套餐？

不支持。需要编译阶段确定套餐版本，以便下载相关依赖库。
中国站