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 政策
隐私协议
数据处理和安全协议
联系我们

iOS

PDF
聚焦模式
字号
最后更新时间: 2026-02-02 14:47:03

功能说明

TEBeautyKit 是腾讯特效美颜模块的 UI 面板库,用于客户快速方便的使用和管理美颜功能,效果如下图:


集成步骤

1. 集成 TEBeautyKit,编辑 podfile 文件,添加下面的代码后执行pod install
# 将S1-07替换成您购买的套餐
pod 'TEBeautyKit/S1-07', :podspec => 'https://mediacloud-76607.gzc.vod.tencent-cloud.com/TencentEffect/iOS/TEBeautyKit/latest/TEBeautyKit.podspec'
2. 集成 面板资源,点击下载资源包后,引入主工程,内容说明见 附录
3. 集成 美颜素材

使用指引

步骤一:鉴权

使用 SDK 前,需要进行一次美颜鉴权,鉴权成功后才能正常使用美颜功能,详见 鉴权错误码 说明。
[TEBeautyKit setTELicense:@"your license" key:@"your key" completion:^(NSInteger authresult, NSString * _Nullable errorMsg) {
NSLog(@"----------result: %zd %@",authresult,errorMsg);
}];

步骤二:配置面板资源路径

美颜面板上面的美颜数据、icon 图标都在 面板资源 中,根据接口说明,传入对应的 json 文件路径,面板上显示的内容可以根据实际需求自行调整。
- (void)configPanel {
NSBundle *bundle = [NSBundle mainBundle];
NSString *beautyJsonPath = [bundle pathForResource:@"beauty" ofType:@"json"]; //美颜
NSString *lutJsonPath = [bundle pathForResource:@"lut" ofType:@"json"]; //滤镜
NSString *motion2dJsonPath = [bundle pathForResource:@"motion_2d" ofType:@"json"]; //2d贴纸
NSMutableArray *resArray = [[NSMutableArray alloc] init];
[resArray addObject:@{TEUI_BEAUTY : beautyJsonPath}];
[resArray addObject:@{TEUI_LUT : lutJsonPath}];
[resArray addObject:@{TEUI_MOTION_2D : motion2dJsonPath}];
/// 设置资源
[[TEUIConfig shareInstance] setTEPanelViewResources:resArray];
}

步骤三:添加面板

TEPanelView 是自定义的面板视图,用来展示步骤二中配置的数据。
- (void)addPanelView {
TEPanelView *tePanelView = [[TEPanelView alloc] init];
tePanelView.delegate = self;
[self.view addSubview:tePanelView];
[tePanelView mas_makeConstraints:^(MASConstraintMaker *make) {
make.width.bottom.mas_equalTo(self.view);
make.left.right.mas_equalTo(self.view);
make.height.mas_equalTo(230 + self.view.safeAreaInsets.bottom);
}];
}

步骤四:使用美颜

1. 初始化
- (void)initXMagic {
__weak __typeof(self)weakSelf = self;
[TEBeautyKit createXMagic:EFFECT_MODE_PRO onInitListener:^(TEBeautyKit * _Nullable beautyKit) {
__strong typeof(self)strongSelf = weakSelf;
strongSelf.teBeautyKit = beautyKit;
strongSelf.tePanelView.teBeautyKit = strongSelf.teBeautyKit;
[strongSelf.tePanelView setDefaultBeauty];
[strongSelf.teBeautyKit setLogLevel:YT_SDK_ERROR_LEVEL];
[strongSelf.teBeautyKit registerSDKEventListener:strongSelf];
}];
}
2. 处理视频数据
#pragma mark AVCaptureVideoDataOutputSampleBufferDelegate
- (void)captureOutput:(AVCaptureOutput *)captureOutput didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer fromConnection:(AVCaptureConnection *)connection {
if (captureOutput == self.videoDataOutput) {
[self mycaptureOutput:captureOutput didOutputSampleBuffer:sampleBuffer fromConnection:connection originImageProcess:YES];
}
}

- (void)mycaptureOutput:(AVCaptureOutput *)captureOutput didOutputSampleBuffer:(CMSampleBufferRef)inputSampleBuffer fromConnection:(AVCaptureConnection *)connection originImageProcess:(BOOL)originImageProcess {
CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(inputSampleBuffer);
YTProcessOutput *output = [self.teBeautyKit processPixelData:pixelBuffer
pixelDataWidth:(int)CVPixelBufferGetWidth(pixelBuffer)
pixelDataHeight:(int)CVPixelBufferGetHeight(pixelBuffer)
withOrigin:YtLightImageOriginTopLeft
withOrientation:YtLightCameraRotation0];
if (output.pixelData.data != nil) {
/// 输出视频数据,渲染或者其他处理
}
if (output != nil) {
output.pixelData = nil;
output = nil;
}
}
3. 销毁
- (void)destroyXMagic {
[self.teBeautyKit onDestroy];
self.teBeautyKit = nil;
}

附录

面板 JSON 文件说明

各个json文件说明
文件
说明
beauty.json
美颜配置文件
beauty_body..json
美体配置文件
beauty_image.json
画质调整配置文件
beauty_makeup.json
单点美妆配置文件
beauty_shape.json
高级美型配置文件
beauty_template_ios.json
美颜模板配置文件
light_makeup.json
轻美妆配置文件
lut.json
滤镜配置文件。注意:由于不同客户使用的滤镜素材不一样,所以客户在下载之后,可以按照 json 结构进行自行配置。
makeup.json
风格整妆配置文件。 注意:由于不同客户使用的风格整妆素材不一样,所以客户在下载之后,可以按照 json 结构进行自行配置。
motion_2d.json
2d动效贴纸配置文件。注意:由于不同客户使用的动效贴纸素材不一样,所以客户在下载之后,可以按照 json 结构进行自行配置。
motion_3d.json
3d动效贴纸配置文件。注意:由于不同客户使用的动效贴纸素材不一样,所以客户在下载之后,可以按照 json 结构进行自行配置。
motion_gesture.json
手势动效贴纸配置文件。注意:由于不同客户使用的动效贴纸素材不一样,所以客户在下载之后,可以按照 json 结构进行自行配置。
segmentation.json
背景分割(虚拟背景)配置文件。注意:由于不同客户使用的分割素材不一样,所以客户在下载之后,可以按照 json 结构进行自行配置。
panel_icon
此文件夹中用于存放 json 文件中配置的图片,必须添加
美颜、美体



字段
说明
displayName
中文名称
displayNameEn
英文名称
icon
图片地址,支持设置本地图片和网络图片,本地图片支持 assets 资源和 SD 资源,assets 图片如上图所示,SD 卡图片设置图片全路径,网络图片设置对应的 http 链接
sdkParam
美颜 SDK 需要用到的属性,共包含四个属性,可参考美颜参数表
effectName
美颜属性 key,参考 属性参数表
effectValue
设置属性强度,参考 属性参数表
resourcePath
设置资源路径,参考 属性参数表
extraInfo
设置其他信息,参考 属性参数表
滤镜、动效贴纸、分割



由于滤镜和动效贴纸、分割的配置基本一致,所以此处用滤镜的JSON进行说明,这里新增了downloadPath和resourceUri字段。
字段
说明
downloadPath
如果您的滤镜素材是网络下载,那么这里配置的是您素材下载后在本地的存放位置,这里是相对路径,全路径是
TEDownloader.h中设置的basicPath+此处设置的路径
resourceUri
如果您的素材是需要通过网络下载的,那么这里配置网络地址,如上图第三个红框,如果您的滤镜素材在本地,则按照上图配置对应的本地地址。
风格整妆



在风格整妆中增加了 extraInfo下的 makeupLutStrength字段,此字段用于调节风格整妆素材中滤镜的强度(如果此风格整妆素材支持调节滤镜强度就进行配置),此字段可参考美颜参数表。

TEBeautyKit 方法说明

/// 创建TEBeautyKit对象
/// - Parameters:
/// - effectMode: EFFECT_MODE_NORMAL(高性能模式) EFFECT_MODE_PRO(默认模式)
/// 高性能模式开启后,美颜占用的系统 CPU/GPU 资源更少,可减少手机的发热和卡顿现象,更适合低端机长时间用。
/// 注意:开启高性能模式后,以下美颜项将不可用:
/// 1. 眼部:眼宽、眼高、祛眼袋
/// 2. 眉毛:角度、距离、高度、长度、粗细、眉峰
/// 3. 嘴部:微笑唇
/// 4. 面部:瘦脸(自然,女神,英俊),收下颌,祛皱、祛法令纹。建议用“脸型”实现综合大眼瘦脸效果
/// - onInitListener: 回调
+ (void)createXMagic:(EffectMode)effectMode onInitListener:(OnInitListener _Nullable)onInitListener;

/// 美颜鉴权
+ (void)setTELicense:(NSString *)url key:(NSString *)key completion:(callback _Nullable )completion;

/// 设置美颜对象
- (void)setXMagicApi:(XMagic *_Nullable)xmagicApi;

/// 美颜静音
- (void)setMute:(BOOL)isMute;

/// 设置某个特性的开或关
/// @param featureName 取值见 XmagicConstant.FeatureName
/// @param enable true表示开启,false表示关闭
- (void)setFeatureEnableDisable:(NSString *_Nullable)featureName enable:(BOOL)enable;

/// 设置帧同步模式
/// @isSync 是否是同步
/// @syncFrameCount同步的帧数。-1表示无限制。如果isSync为false,则此参数无意义
- (void)setSyncMode:(BOOL)isSync syncFrameCount:(int)syncFrameCount;

/// 处理图片美颜
- (UIImage *_Nullable)processUIImage:(UIImage *_Nullable)inputImage
imageWidth:(int)imageWidth
imageHeight:(int)imageHeight
needReset:(bool)needReset;

/// 处理texture
/// - Parameters:
/// - textureId: 纹理id
/// - textureWidth: 纹理宽度
/// - textureHeight: 纹理高度
/// - origin: 枚举值,设置成YtLightImageOriginBottomLeft 时,图像上下镜像翻转
/// - orientation: 枚举值:图像旋转角度
- (YTProcessOutput *_Nullable)processTexture:(int)textureId
textureWidth:(int)textureWidth
textureHeight:(int)textureHeight
withOrigin:(YtLightImageOrigin)origin
withOrientation:(YtLightDeviceCameraOrientation)orientation;

/// 处理CVPixelBufferRef
/// - Parameters:
/// - pixelData: 图像数据
/// - pixelDataWidth: 图像宽度
/// - pixelDataHeight: 图像高度
/// - origin: 枚举值,设置成YtLightImageOriginBottomLeft 时,图像上下镜像翻转
/// - orientation: 枚举值:图像旋转角度
- (YTProcessOutput * _Nullable)processPixelData:(CVPixelBufferRef _Nullable )pixelData
pixelDataWidth:(int)pixelDataWidth
pixelDataHeight:(int)pixelDataHeight
withOrigin:(YtLightImageOrigin)origin
withOrientation:(YtLightDeviceCameraOrientation)orientation;

/// 设置美颜
- (void)setEffect:(TESDKParam *_Nullable)sdkParam;

/// 设置美颜
- (void)setEffectList:(NSArray<TESDKParam *>*_Nullable)sdkParamList;

/// 是否开启了美颜增强模式
- (BOOL)isEnableEnhancedMode;

/// 是否开启美颜增强模式
- (void)enableEnhancedMode:(BOOL)enable;

/// 恢复
- (void)onResume;

/// 暂停
- (void)onPause;

/// 销毁
- (void)onDestroy;

//获取当前texture的图片
- (void)exportCurrentTexture:(void (^_Nullable)(UIImage * _Nullable image))callback;

/// 设置log
- (void)setLogLevel:(YtSDKLoggerLevel)level;

/// 设置AIDataListener
- (void)setAIDataListener:(id<TEBeautyKitAIDataListener> _Nullable)listener;

/// 设置TipsListener
- (void)setTipsListener:(id<TEBeautyKitTipsListener> _Nullable)listener;

/// 保存设置的美颜数据
- (void)saveEffectParam:(TESDKParam *_Nonnull)sdkParam;

/// 删除某个保存的美颜数据
- (void)deleteEffectParam:(TESDKParam *_Nonnull)sdkParam;

/// 清空保存的美颜数据
- (void)clearEffectParam;

/// 获取保存的美颜数据
- (NSMutableArray<TESDKParam *> *_Nonnull)getInUseSDKParamList;

/// 导出正在使用的美颜数据
/// return json字符串
- (NSString *_Nullable)exportInUseSDKParam;

/// 设置美颜数据
/// - Parameter params: json字符串
/// 如果要同时设置面板UI,则只需要调用 TEPanelView 的 setExportParamList 即可
- (void)setExportedSDKParam:(NSString *_Nonnull)params;

/// 是否开启美颜
- (void)enableBeauty:(BOOL)enable;

/// SDK事件监听接口 SDK event monitoring interface
/// @param listener 事件监听器回调,主要分为AI事件,Tips提示事件,Asset事件
/// Event listener callback, mainly divided into AI events, Tips reminder events, Asset events
- (void)registerSDKEventListener:(id<YTSDKEventListener> _Nullable)listener;

/// 注册回调清理接口 Register callback cleanup interface
- (void)clearListeners;

TEUIConfig 说明

///可在外部修改下列属性的颜色
/// 美颜面板背景色
@property (nonatomic, strong) UIColor *panelBackgroundColor;
/// 分割线颜色
@property (nonatomic, strong) UIColor *panelDividerColor;
/// 选中项颜色
@property (nonatomic, strong) UIColor *panelItemCheckedColor;
/// 文本颜色
@property (nonatomic, strong) UIColor *textColor;
/// 文本选中颜色
@property (nonatomic, strong) UIColor *textCheckedColor;
/// 进度条颜色
@property (nonatomic, strong) UIColor *seekBarProgressColor;
/// 单例
+ (instancetype)shareInstance;
/// 设置面板资源路径
/// - Parameter resources: 资源路径列表
/// e.g. @[@{TEUI_BEAUTY : @"json file path"}]
- (void)setTEPanelViewResources:(NSArray<NSDictionary *> *)resources;
/// 获取面板资源路径
- (NSArray<NSDictionary *> *)getTEPanelViewResources;

TEPanelView 说明

/// 美颜SDK对象
@property (nonatomic, weak) XMagic *beautyKitApi;
/// beautyKit对象
@property (nonatomic, strong) TEBeautyKit *teBeautyKit;
/// 代理
@property (nonatomic, weak) id<TEPanelViewDelegate> delegate;
/// 设置导出的美颜数据
- (void)setExportParamList:(NSString *)lastParamList;
/// 默认美颜
- (void)setDefaultBeauty;
/// 重置所有效果
- (void)performFullReset;
/// 增强模式
- (void)setEnhancedMode:(BOOL)enhancedMode;
/// 显示对比按钮
- (void)isShowCompareBtn:(BOOL)isShow;

帮助和支持

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

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

文档反馈