API 参考

本文档对应 SDK 2.0.0。预设含义见参数枚举。授权见授权认证。

iOS 与 macOS 共用同一套 Objective-C API。macOS 独有：+[FBImageFrame createWithNSImage:]。最低系统：macOS 10.15，架构 x86_64 与 arm64。静图使用 AppKit（NSImage）。

日志

`FBLogLevel`

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

`FBLogConfig`

属性	类型	说明
`consoleEnabled`	`BOOL`	控制台输出
`fileEnabled`	`BOOL`	文件输出
`level`	`FBLogLevel`	最低级别
`fileName`	`NSString *`	日志路径（`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

在 createEngineWithConfig: 之前调用 +[FBBeautyEffectEngine setLogConfig:]。返回 FBErrorCode（0 成功，config 为 nil 时 -1）。

引擎配置

`FBEngineConfig`

属性	类型	说明
`appId`	`NSString *`	控制台 App ID（在线授权）
`appKey`	`NSString *`	控制台 App Key（在线授权）
`licenseToken`	`NSString *`	许可证 token、`{token}` JSON，或原生 `.lic` 内容
`externalContext`	`BOOL`	默认 `NO`。`YES`：使用调用方的 OpenGL 上下文

授权优先级： licenseToken 非空则本地校验，跳过 /facebetter/v2/auth；否则用 appId + appKey 在线授权。请在控制台绑定应用 Bundle ID。没有 bundle 的命令行工具请绑定进程名。

FB_OBJC_API @interface FBEngineConfig : NSObject
@property(nonatomic, copy) NSString *appId;
@property(nonatomic, copy) NSString *appKey;
@property(nonatomic, copy, nullable) NSString *licenseToken;
@property(nonatomic, assign) BOOL externalContext;
- (instancetype)init;
@end

`FBFrameType`

在 processImage: 前设置 FBImageFrame.type。不是方法参数。

typedef NS_ENUM(NSInteger, FBFrameType) {
  FBFrameTypeImage = 0,  // 静图 / NSImage
  FBFrameTypeVideo = 1   // 实时 / 相机
};

`FBBeautyEffectEngine`

FB_OBJC_API @interface FBBeautyEffectEngine : NSObject

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

- (int)setSmoothing:(float)intensity;
- (int)setSmoothingStyle:(FBSmoothingStyle)style;
- (int)setWhitening:(float)intensity;
- (int)setWhiteningStyle:(FBWhiteningStyle)style;
- (int)setSharpening:(float)intensity;
- (int)setRosiness:(float)intensity;
- (int)setReshape:(FBReshape)param intensity:(float)value;
- (int)setBeautySkinOnly:(BOOL)enabled;

- (int)setLipstick:(float)intensity;
- (int)setLipstickColor:(FBLipstickColor)color;
- (int)setBlush:(float)intensity;
- (int)setBlushStyle:(FBBlushStyle)style;
- (int)setBlushColor:(FBBlushColor)color;
- (int)setContour:(float)intensity;
- (int)setContourStyle:(FBContourStyle)style;
- (int)setEyeShadow:(float)intensity;
- (int)setEyeShadowStyle:(FBEyeShadowStyle)style;
- (int)setEyeShadowColor:(FBEyeShadowColor)color;
- (int)setEyeLiner:(float)intensity;
- (int)setEyeLinerStyle:(FBEyeLinerStyle)style;
- (int)setEyeLinerColor:(FBEyeLinerColor)color;
- (int)setEyebrow:(float)intensity;
- (int)setEyebrowStyle:(FBEyebrowStyle)style;
- (int)setEyebrowColor:(FBEyebrowColor)color;
- (int)setEyelash:(float)intensity;
- (int)setEyelashStyle:(FBEyelashStyle)style;
- (int)setEyelashColor:(FBEyelashColor)color;
- (int)setPupil:(float)intensity;
- (int)setPupilColor:(FBPupilColor)color;

- (int)setChromaKey:(FBChromaKeyColor)color;
- (int)clearChromaKey;
- (int)setChromaKeySimilarity:(float)value;
- (int)setChromaKeySmoothness:(float)value;
- (int)setChromaKeyDesaturation:(float)value;
- (int)setVirtualBackgroundBlur:(float)level;
- (int)setVirtualBackground:(NSString *)imagePath;
- (int)setVirtualBackgroundWithData:(NSData *)imageData;
- (int)clearVirtualBackground;

- (int)setFilter:(NSString *)fbdFilePath;
- (int)setFilterWithData:(NSData *)fbdData;
- (int)clearFilter;
- (int)setFilterIntensity:(float)intensity;
- (int)setSticker:(NSString *)fbdFilePath;
- (int)setStickerWithData:(NSData *)fbdData;
- (int)clearSticker;

- (FBEngineStats *)getStats;
- (int)setCallbacks:(FBEngineCallbacks *)callbacks;
- (FBImageFrame * _Nullable)processImage:(FBImageFrame *)imageFrame;

@end

createEngineWithConfig: 失败返回 nil。整型方法返回 FBErrorCode（0 = 成功）。

美肤

方法	范围 / 说明
`setSmoothing:`	强度 `[0, 1]`
`setSmoothingStyle:`	风格；强度仍由 `setSmoothing:` 控制
`setWhitening:`	`[0, 1]`
`setWhiteningStyle:`	切换美白 LUT
`setSharpening:`	`[0, 1]`
`setRosiness:`	`[0, 1]`
`setBeautySkinOnly:`	`YES` = 仅皮肤区域

美型

setReshape:intensity: — 强度 [-1.0, 1.0]，0 关闭。FBReshape 取值 0–25：FBReshape_FaceThin … FBReshape_BrowThickness。方向说明见参数枚举。

typedef NS_ENUM(NSInteger, FBReshape) {
  FBReshape_FaceThin = 0,
  FBReshape_FaceVShape = 1,
  FBReshape_FaceNarrow = 2,
  FBReshape_FaceShort = 3,
  FBReshape_Cheekbone = 4,
  FBReshape_Jawbone = 5,
  FBReshape_Chin = 6,
  FBReshape_NoseSlim = 7,
  FBReshape_EyeSize = 8,
  FBReshape_EyeDistance = 9,
  FBReshape_FaceSmall = 10,
  FBReshape_Forehead = 11,
  FBReshape_NoseLong = 12,
  FBReshape_Philtrum = 13,
  FBReshape_MouthSize = 14,
  FBReshape_MouthPosition = 15,
  FBReshape_MouthSmile = 16,
  FBReshape_LipThickness = 17,
  FBReshape_EyeRound = 18,
  FBReshape_EyePosition = 19,
  FBReshape_EyeAngle = 20,
  FBReshape_EyeCornerOpen = 21,
  FBReshape_LowerEyelid = 22,
  FBReshape_BrowPosition = 23,
  FBReshape_BrowDistance = 24,
  FBReshape_BrowThickness = 25,
};

FBSmoothingStyle：Natural、Texture、Smooth。FBWhiteningStyle：ColdWhite、PinkWhite、WarmWhite、Wheat、Tan。

美妆

强度方法范围为 [0, 1]。形状 / 色号类型见参数枚举。

强度	形状	色号
`setLipstick:`	—	`setLipstickColor:`
`setBlush:`	`setBlushStyle:`	`setBlushColor:`
`setContour:`	`setContourStyle:`	—
`setEyeShadow:`	`setEyeShadowStyle:`	`setEyeShadowColor:`
`setEyeLiner:`	`setEyeLinerStyle:`	`setEyeLinerColor:`
`setEyebrow:`	`setEyebrowStyle:`	`setEyebrowColor:`
`setEyelash:`	`setEyelashStyle:`	`setEyelashColor:`
`setPupil:`	—	`setPupilColor:`

虚拟背景与色键

方法	说明
`setChromaKey:`	绿 / 蓝 / 红遮罩。填充仍是模糊或图片
`clearChromaKey`	恢复人像分割遮罩；不清除填充
`setChromaKeySimilarity:`	抠像阈值 `[0, 1]`
`setChromaKeySmoothness:`	边缘羽化 `[0, 1]`
`setChromaKeyDesaturation:`	溢色抑制 `[0, 1]`
`setVirtualBackgroundBlur:`	模糊填充 `[0, 1]`；`0` 清除虚拟背景
`setVirtualBackground:`	png/jpg 文件路径（不可为空）
`setVirtualBackgroundWithData:`	编码后的 png/jpg `NSData`
`clearVirtualBackground`	清除模糊和图片填充

typedef NS_ENUM(NSInteger, FBChromaKeyColor) {
  FBChromaKeyColor_Green = 0,
  FBChromaKeyColor_Blue,
  FBChromaKeyColor_Red,
};

滤镜与贴纸

没有按 ID 注册。传路径或字节；GPU 资源在下一次 processImage: 创建。

方法	说明
`setFilter:`	从 `.fbd` 路径加载 LUT
`setFilterWithData:`	从 `.fbd` 字节加载 LUT
`clearFilter`	移除 LUT
`setFilterIntensity:`	`[0, 1]`
`setSticker:`	2D 贴纸 `.fbd` 路径
`setStickerWithData:`	贴纸字节
`clearSticker`	移除贴纸

空路径 / nil 或空 NSData → FBErrorCode_InvalidArgument。

处理

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

读取 imageFrame.type。输出格式与输入一致。失败返回 nil。

错误码

typedef NS_ENUM(NSInteger, FBErrorCode) {
  FBErrorCode_Success = 0,
  FBErrorCode_InvalidArgument = -1,
  FBErrorCode_NotInitialized = -2,
  FBErrorCode_License = -3,
  FBErrorCode_Unsupported = -4,
  FBErrorCode_IO = -5,
  FBErrorCode_NoSlot = -6,
  FBErrorCode_Process = -7,
  FBErrorCode_OutOfMemory = -8,
};

-1 为参数无效。-2 为未初始化。

统计与回调

`FBEngineStats`

属性	类型	说明
`fps`	`double`	每秒帧数
`avgProcessTimeMs`	`double`	`processImage:` 平均耗时（毫秒）
`sessionTimeS`	`double`	会话时长（秒）

- (FBEngineStats *)getStats;

`FBEngineEventCode`

值	符号
`0`	`FBEngineEventCodeLicenseValidationSuccess`
`1`	`FBEngineEventCodeLicenseValidationFailed`
`100`	`FBEngineEventCodeInitializationComplete`
`101`	`FBEngineEventCodeInitializationFailed`

`FBEngineCallbacks`

FB_OBJC_API @interface FBEngineCallbacks : NSObject
@property(nonatomic, copy, nullable) void (^onFaceLandmarks)
    (NSArray<FBFaceDetectionResult *> * _Nullable results);
@property(nonatomic, copy, nullable) void (^onEngineEvent)
    (FBEngineEventCode code, NSString * _Nullable message);
@end

人脸结果类型

FB_OBJC_API @interface FBPoint2d : NSObject
@property(nonatomic, assign) float x;
@property(nonatomic, assign) float y;
- (instancetype)initWithX:(float)x y:(float)y;
@end

FB_OBJC_API @interface FBRect : NSObject
@property(nonatomic, assign) float x;
@property(nonatomic, assign) float y;
@property(nonatomic, assign) float width;
@property(nonatomic, assign) float height;
- (instancetype)initWithX:(float)x y:(float)y width:(float)width height:(float)height;
@end

FB_OBJC_API @interface FBFaceDetectionResult : NSObject
@property(nonatomic, strong) FBRect *rect;
@property(nonatomic, copy, nullable) NSArray<FBPoint2d *> *keyPoints;  // 111 点
@property(nonatomic, copy, nullable) NSArray<NSNumber *> *visibility;  // [0, 1]
@property(nonatomic, assign) int faceId;
@property(nonatomic, assign) float score;
@property(nonatomic, assign) float pitch;  // 上 -, 下 +；[-π, π]
@property(nonatomic, assign) float roll;
@property(nonatomic, assign) float yaw;
@end

`FBImageFrame`

创建

方法	说明
`createWithData:width:height:format:`	原始缓冲 + `FBImageFormat`
`createWithRGBA:width:height:stride:`
`createWithBGRA:width:height:stride:`	AppKit 位图常用
`createWithRGB:width:height:stride:`
`createWithBGR:width:height:stride:`
`createWithI420:...`	Y / U / V 平面
`createWithNV12:...`	Y + UV
`createWithNV21:...`	Y + VU
`createWithFile:`	png / jpg 路径
`createWithTexture:width:height:stride:`	当前上下文中的 `GL_TEXTURE_2D`
`createWithNSImage:`	仅 macOS

操作

方法	说明
`rotate:`	`FBImageRotation`；返回 `FBErrorCode`
`mirror:`	`"horizontal"` / `"vertical"` / `"both"`；直接改像素
`setMirror:`	供 `processImage:` 使用的标记。`nil` / `@""` 清除
`convert:`	返回目标 `FBImageFormat` 的新帧
`toFile:quality:`	质量 `0`–`100`
`toFile:`	质量 `90`

访问器：width、height、stride、size、type、data、format、texture。YUV：dataY / dataU / dataV / dataUV 及对应 stride。

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

typedef NS_ENUM(NSInteger, FBImageRotation) {
  FBImageRotation0,
  FBImageRotation90,
  FBImageRotation180,
  FBImageRotation270,
};

FBImageFrame *frame = [FBImageFrame createWithNSImage:image];
frame.type = FBFrameTypeImage;
FBImageFrame *out = [engine processImage:frame];

美妆 / 风格枚举

Objective-C 符号在 FBBeautyParams.h。不要在此重复含义表 — 见参数枚举。

FBSmoothingStyle、FBWhiteningStyle
FBLipstickColor
FBBlushStyle、FBBlushColor
FBContourStyle
FBEyeShadowStyle、FBEyeShadowColor
FBEyeLinerStyle、FBEyeLinerColor
FBEyebrowStyle、FBEyebrowColor
FBEyelashStyle、FBEyelashColor
FBPupilColor

产品介绍

Android

iOS

macOS

Windows

Linux

Web

Flutter

日志

`FBLogLevel`

`FBLogConfig`

引擎配置

`FBEngineConfig`

`FBFrameType`

`FBBeautyEffectEngine`

美肤

美型

美妆

虚拟背景与色键

滤镜与贴纸

处理

错误码

统计与回调

`FBEngineStats`

`FBEngineEventCode`

`FBEngineCallbacks`

人脸结果类型

`FBImageFrame`

创建

操作

美妆 / 风格枚举

​日志

​FBLogLevel

​FBLogConfig

​引擎配置

​FBEngineConfig

​FBFrameType

​FBBeautyEffectEngine

​美肤

​美型

​美妆

​虚拟背景与色键

​滤镜与贴纸

​处理

​错误码

​统计与回调

​FBEngineStats

​FBEngineEventCode

​FBEngineCallbacks

​人脸结果类型

​FBImageFrame

​创建

​操作

​美妆 / 风格枚举

日志

`FBLogLevel`

`FBLogConfig`

引擎配置

`FBEngineConfig`

`FBFrameType`

`FBBeautyEffectEngine`

美肤

美型

美妆

虚拟背景与色键

滤镜与贴纸

处理

错误码

统计与回调

`FBEngineStats`

`FBEngineEventCode`

`FBEngineCallbacks`

人脸结果类型

`FBImageFrame`

创建

操作

美妆 / 风格枚举