API 参考

日志相关

日志级别

日志级别枚举，用于控制日志输出级别。

typedef NS_ENUM(NSInteger, FBLogLevel) {
  FBLogLevel_Trace = 0,
  FBLogLevel_Debug,
  FBLogLevel_Info,
  FBLogLevel_Warn,
  FBLogLevel_Error,
  FBLogLevel_Critical,
};

日志配置类

日志配置类，用于配置日志输出方式和级别。 字段说明：

consoleEnabled: 是否启用控制台输出
fileEnabled: 是否启用文件输出
level: 日志级别
fileName: 日志文件路径（仅在 fileEnabled 为 YES 时有效）

FB_OBJC_API @interface FBLogConfig : NSObject

@property(nonatomic, assign) BOOL consoleEnabled;
@property(nonatomic, assign) BOOL fileEnabled;
@property(nonatomic, assign) FBLogLevel level;
@property(nonatomic, copy, nullable) NSString* fileName;

- (instancetype)init;

@end

引擎相关

处理模式

图像处理模式枚举。

引擎配置

引擎配置类，用于初始化美颜引擎。 字段说明：

appId: 应用 ID（可选，如果提供了 licenseJson 则不需要）
appKey: 应用密钥（可选，如果提供了 licenseJson 则不需要）
licenseJson: 授权数据 JSON 字符串（可选，如果提供了则优先使用，不需要 appId 和 appKey）
externalContext: 是否使用外部 OpenGL 上下文（默认 NO）
- YES: 使用调用方提供的 GL 上下文，SDK 不再创建/管理内部上下文
- NO: 使用内部默认上下文

验证方式优先级：

如果 licenseJson 不为空，使用授权数据验证（支持在线响应和离线授权）
否则使用 appId 和 appKey 进行自动联网验证

FB_OBJC_API @interface FBEngineConfig : NSObject

@property(nonatomic, copy) NSString* appId;
@property(nonatomic, copy) NSString* appKey;
@property(nonatomic, copy, nullable) NSString* licenseJson;  // 授权数据JSON字符串（可选）
@property(nonatomic, assign) BOOL externalContext;  // 是否使用外部 OpenGL 上下文

- (instancetype)init;
@end

引擎接口

美颜效果引擎主类，提供美颜功能的入口。 静态方法：

setLogConfig:: 设置日志配置

实例方法：

参数设置

setBasicParam:floatValue:: 设置基础美颜参数（范围 0.0 - 1.0）
setReshapeParam:floatValue:: 设置面部重塑参数（范围 0.0 - 1.0）
setMakeupParam:floatValue:: 设置美妆参数（范围 0.0 - 1.0）
setLipstickStyle:: 设置口红样式（Rouge / Coral / Pink）
setBlushStyle:: 设置腮红样式（Classic / Peach / Rose）
setSkinOnlyBeauty:: 设置美颜是否仅作用于皮肤区域
- 参数：enabled 为 YES 时启用皮肤区域美颜，为 NO 时美颜作用于整张图像
setVirtualBackground:: 设置虚拟背景
- 参数：FBVirtualBackgroundOptions 对象，包含背景模式和背景图片

滤镜与贴纸管理

setFilter:: 设置滤镜
- 参数：filterId 滤镜唯一标识符
setFilterIntensity:: 设置滤镜强度
- 参数：intensity 强度值（范围 0.0 - 1.0）
setSticker:: 设置贴纸
- 参数：stickerId 贴纸唯一标识符，传入 @"" 可清除贴纸
registerFilter:fbdFilePath:: 从文件注册滤镜
registerFilter:fbdData:: 从内存注册滤镜
registerSticker:fbdFilePath:: 从文件注册贴纸
registerSticker:fbdData:: 从内存注册贴纸
unregisterFilter:: 卸载滤镜
unregisterAllFilters: 卸载所有滤镜
unregisterSticker:: 卸载贴纸
unregisterAllStickers: 卸载所有贴纸
getRegisteredFilters: 获取已注册滤镜列表
getRegisteredStickers: 获取已注册贴纸列表

图像处理

processImage:: 处理图像帧
- 帧类型通过 imageFrame.type 属性获取（FBFrameTypeImage 或 FBFrameTypeVideo）
- 处理后的图像帧会保持相同的帧类型

返回值说明：

方法返回 int 类型：0 表示成功，其他值表示错误码
processImage: 返回 FBImageFrame：处理后的图像帧，失败时返回 nil

FB_OBJC_API @interface FBBeautyEffectEngine : NSObject

+ (int)setLogConfig:(FBLogConfig*)config;
+ (instancetype)createEngineWithConfig:(FBEngineConfig*)config;

- (int)setBasicParam:(FBBasicParam)param floatValue:(float)value;
- (int)setReshapeParam:(FBReshapeParam)param floatValue:(float)value;
- (int)setMakeupParam:(FBMakeupParam)param floatValue:(float)value;
- (int)setLipstickStyle:(FBLipstickStyle)style;
- (int)setBlushStyle:(FBBlushStyle)style;
- (int)setSkinOnlyBeauty:(BOOL)enabled;
- (int)setVirtualBackground:(FBVirtualBackgroundOptions*)options;

- (int)setFilter:(NSString*)filterId;
- (int)setFilterIntensity:(float)intensity;
- (int)setSticker:(NSString*)stickerId;
- (int)registerFilter:(NSString*)filterId fbdFilePath:(NSString*)fbdFilePath;
- (int)registerFilter:(NSString*)filterId fbdData:(NSData*)fbdData;
- (int)registerSticker:(NSString*)stickerId fbdFilePath:(NSString*)fbdFilePath;
- (int)registerSticker:(NSString*)stickerId fbdData:(NSData*)fbdData;
- (int)unregisterFilter:(NSString*)filterId;
- (int)unregisterAllFilters;
- (int)unregisterSticker:(NSString*)stickerId;
- (int)unregisterAllStickers;
- (NSArray<NSString*>*)getRegisteredFilters;
- (NSArray<NSString*>*)getRegisteredStickers;

- (FBImageFrame* _Nullable)processImage:(FBImageFrame*)imageFrame;

// Deprecated APIs
- (int)setBeautyTypeEnabled:(FBBeautyType)type enabled:(BOOL)enabled;
- (BOOL)isBeautyTypeEnabled:(FBBeautyType)type;
- (int)disableAllBeautyTypes;

@end

美颜参数

美颜参数枚举类，包含所有美颜相关的参数类型定义。

美颜类型

定义可用的美颜功能类型。

typedef NS_ENUM(NSInteger, FBBeautyType) {
  FBBeautyType_Basic = 0,     // 基础美颜
  FBBeautyType_Reshape,       // 面部重塑
  FBBeautyType_Makeup,        // 美妆效果
  FBBeautyType_VirtualBackground,  // 虚拟背景
};

基础美颜参数

基础美颜效果的参数类型，所有参数值范围均为 0.0 - 1.0。

typedef NS_ENUM(NSInteger, FBBasicParam) {
  FBBasicParam_Smoothing = 0,  // 磨皮
  FBBasicParam_Sharpening,     // 锐化
  FBBasicParam_Whitening,      // 美白
  FBBasicParam_Rosiness,       // 红润
};

面部重塑参数

面部重塑效果的参数类型，所有参数值范围均为 0.0 - 1.0。

typedef NS_ENUM(NSInteger, FBReshapeParam) {
  FBReshapeParam_FaceThin = 0,  // 瘦脸
  FBReshapeParam_FaceVShape,    // V脸
  FBReshapeParam_FaceNarrow,    // 窄脸
  FBReshapeParam_FaceShort,     // 短脸
  FBReshapeParam_Cheekbone,     // 颧骨
  FBReshapeParam_Jawbone,       // 下颌骨
  FBReshapeParam_Chin,          // 下巴
  FBReshapeParam_NoseSlim,      // 瘦鼻梁
  FBReshapeParam_EyeSize,       // 大眼
  FBReshapeParam_EyeDistance,   // 眼距
};

美妆参数

美妆效果的参数类型，所有参数值范围均为 0.0 - 1.0。

typedef NS_ENUM(NSInteger, FBMakeupParam) {
  FBMakeupParam_Lipstick = 0,  // 口红
  FBMakeupParam_Blush,         // 腮红
};

typedef NS_ENUM(NSInteger, FBLipstickStyle) {
  FBLipstickStyle_Rouge = 0,  // 玫瑰红
  FBLipstickStyle_Coral,      // 珊瑚橙
  FBLipstickStyle_Pink,       // 粉色（默认）
};

typedef NS_ENUM(NSInteger, FBBlushStyle) {
  FBBlushStyle_Classic = 0,  // 经典（默认）
  FBBlushStyle_Peach,        // 蜜桃
  FBBlushStyle_Rose,         // 玫瑰
};

虚拟背景选项

虚拟背景效果的配置选项。

FB_OBJC_API @interface FBVirtualBackgroundOptions : NSObject
@property(nonatomic, assign) FBBackgroundMode mode;
@property(nonatomic, strong, nullable) FBImageFrame *backgroundImage;

- (instancetype)init;
- (instancetype)initWithMode:(FBBackgroundMode)mode;
@end;

图像相关

FBImageFrame

图像帧类，用于封装图像数据和处理。 创建方法：

createWithFile:: 从文件创建（支持 PNG、JPG）
createWithRGBA:width:height:stride:: 从 RGBA 数据创建
createWithBGRA:width:height:stride:: 从 BGRA 数据创建
createWithRGB:width:height:stride:: 从 RGB 数据创建
createWithBGR:width:height:stride:: 从 BGR 数据创建
createWithI420:...: 从 I420 YUV 数据创建
createWithNV12:...: 从 NV12 YUV 数据创建
createWithNV21:...: 从 NV21 YUV 数据创建
createWithTexture:width:height:stride:: 从 GPU 纹理创建（外部纹理输入）
createWithUIImage:: 从 UIImage 创建（iOS 专用）

图像操作：

rotate:: 旋转图像（返回 0 表示成功）
mirror:: 镜像图像（返回 0 表示成功）
- 参数：mode 镜像模式，可以是 “horizontal”（水平）、“vertical”（垂直）或 “both”（两者）（不区分大小写）
setMirror:: 设置引擎处理时的镜像模式（避免额外的格式转换）
- 参数：mode 镜像模式，可以是 “horizontal”（水平）、“vertical”（垂直）或 “both”（两者）（不区分大小写）
- 注意：这仅设置镜像标志，实际的镜像发生在引擎处理期间

属性访问：

width, height, stride, size: 获取图像尺寸和步长
format: 获取图像格式
texture: 获取纹理句柄（如果是纹理格式）
type: 帧类型属性（FBFrameTypeImage 或 FBFrameTypeVideo），默认值为 FBFrameTypeVideo

格式转换与访问：

convert:: 格式转换方法，返回转换后的 FBImageFrame
toFile:quality:: 保存图像到文件（指定质量 0-100）
toFile:: 保存图像到文件（使用默认质量 90）

FB_OBJC_API @interface FBImageFrame : NSObject

+ (FBImageFrame *_Nullable)createWithFile:(NSString *)filePath;
+ (FBImageFrame *_Nullable)createWithRGBA:(const uint8_t *)data
                                    width:(int)width
                                   height:(int)height
                                   stride:(int)stride;
+ (FBImageFrame *_Nullable)createWithBGRA:(const uint8_t *)data
                                    width:(int)width
                                   height:(int)height
                                   stride:(int)stride;
+ (FBImageFrame *_Nullable)createWithRGB:(const uint8_t *)data
                                  width:(int)width
                                 height:(int)height
                                 stride:(int)stride;
+ (FBImageFrame *_Nullable)createWithBGR:(const uint8_t *)data
                                  width:(int)width
                                 height:(int)height
                                 stride:(int)stride;
+ (FBImageFrame *_Nullable)createWithI420:(int)width
                                   height:(int)height
                                    dataY:(const uint8_t *)dataY
                                  strideY:(int)strideY
                                    dataU:(const uint8_t *)dataU
                                  strideU:(int)strideU
                                    dataV:(const uint8_t *)dataV
                                  strideV:(int)strideV;
+ (FBImageFrame *_Nullable)createWithNV12:(int)width
                                   height:(int)height
                                    dataY:(const uint8_t *)dataY
                                  strideY:(int)strideY
                                   dataUV:(const uint8_t *)dataUV
                                 strideUV:(int)strideUV;
+ (FBImageFrame *_Nullable)createWithNV21:(int)width
                                   height:(int)height
                                    dataY:(const uint8_t *)dataY
                                  strideY:(int)strideY
                                   dataUV:(const uint8_t *)dataUV
                                 strideUV:(int)strideUV;
+ (FBImageFrame *_Nullable)createWithTexture:(uint32_t)texture
                                      width:(int)width
                                     height:(int)height
                                     stride:(int)stride;
+ (FBImageFrame *_Nullable)createWithUIImage:(UIImage *)image;

- (int)rotate:(FBImageRotation)rotation;
- (int)mirror:(NSString *)mode;
- (void)setMirror:(NSString *)mode;

- (FBImageFrame *_Nullable)convert:(FBImageFormat)format;
- (int)toFile:(NSString *)filePath quality:(int)quality;
- (int)toFile:(NSString *)filePath;

// 属性访问方法
- (int32_t)width;
- (int32_t)height;
- (int32_t)stride;
- (int32_t)size;
- (const uint8_t *_Nullable)data;
- (FBImageFormat)format;
- (uint32_t)texture;

@property(nonatomic, assign) FBFrameType type;

// YUV 相关方法
- (const uint8_t *_Nullable)dataY;
- (const uint8_t *_Nullable)dataU;
- (const uint8_t *_Nullable)dataV;
- (const uint8_t *_Nullable)dataUV;
- (int32_t)strideY;
- (int32_t)strideU;
- (int32_t)strideV;
- (int32_t)strideUV;

@end

FBImageFormat

图像格式枚举。

typedef NS_ENUM(NSInteger, FBImageFormat) {
  FBImageFormatI420,
  FBImageFormatNV12,
  FBImageFormatNV21,
  FBImageFormatBGRA,
  FBImageFormatRGBA,
  FBImageFormatBGR,
  FBImageFormatRGB,
  FBImageFormatTexture,
};

FBImageRotation

图像旋转角度枚举。

typedef NS_ENUM(NSInteger, FBImageRotation) {
  FBImageRotation0,    // 0度
  FBImageRotation90,   // 顺时针旋转90度
  FBImageRotation180,  // 顺时针旋转180度
  FBImageRotation270,  // 顺时针旋转270度
};

FBFrameType

图像帧类型枚举，用于标识图像帧的处理模式。

FBFrameTypeImage: 图像模式，适合单张图片处理
FBFrameTypeVideo: 视频模式，适合视频流和直播场景，性能更优

typedef NS_ENUM(NSInteger, FBFrameType) {
  FBFrameTypeImage = 0,  // 图像模式
  FBFrameTypeVideo = 1   // 视频模式
};

已废弃接口 (Deprecated APIs)

已弃用以下接口已弃用。

美颜类型控制

setBeautyTypeEnabled:enabled:
- 说明: [已弃用] 启用或禁用美颜类型（参数驱动模式下无效果）
- 返回值: 0 表示成功
isBeautyTypeEnabled:
- 说明: [已弃用] 检查美颜类型是否已启用（始终返回 NO）
- 返回值: NO
disableAllBeautyTypes
- 说明: [已弃用] 禁用所有美颜类型（请通过置零参数重置效果）
- 返回值: 0 表示成功

产品介绍

Android

iOS

macOS

Windows

Linux

Web

Flutter

日志相关

日志级别

日志配置类

引擎相关

处理模式

引擎配置

引擎接口

参数设置

滤镜与贴纸管理

图像处理

美颜参数

美颜类型

基础美颜参数

面部重塑参数

美妆参数

虚拟背景选项

图像相关

FBImageFrame

FBImageFormat

FBImageRotation

FBFrameType

已废弃接口 (Deprecated APIs)

美颜类型控制

​日志相关

​日志级别

​日志配置类

​引擎相关

​处理模式

​引擎配置

​引擎接口

​参数设置

​滤镜与贴纸管理

​图像处理

​美颜参数

​美颜类型

​基础美颜参数

​面部重塑参数

​美妆参数

​虚拟背景选项

​图像相关

​FBImageFrame

​FBImageFormat

​FBImageRotation

​FBFrameType

​已废弃接口 (Deprecated APIs)

​美颜类型控制

日志相关

日志级别

日志配置类

引擎相关

处理模式

引擎配置

引擎接口

参数设置

滤镜与贴纸管理

图像处理

美颜参数

美颜类型

基础美颜参数

面部重塑参数

美妆参数

虚拟背景选项

图像相关

FBImageFrame

FBImageFormat

FBImageRotation

FBFrameType

已废弃接口 (Deprecated APIs)

美颜类型控制