API 레퍼런스

이 페이지는 SDK 2.0.0에 해당합니다. 프리셋 의미: 파라미터 열거형. 인증: 인증 및 라이선스.

iOS와 macOS는 이 Objective-C API를 공유합니다. macOS 전용: +[FBImageFrame createWithNSImage:]. 최소 OS: 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 *`	Dashboard App ID(온라인 인증)
`appKey`	`NSString *`	Dashboard App Key(온라인 인증)
`licenseToken`	`NSString *`	라이선스 토큰 문자열, `{token}` JSON, 또는 네이티브 `.lic` 내용
`externalContext`	`BOOL`	기본 `NO`. `YES`: 호출 측 OpenGL 컨텍스트를 사용

인증 우선순위: licenseToken이 비어 있지 않으면 해당 토큰을 로컬에서 검증하고 /facebetter/v2/auth를 건너뜁니다. 그렇지 않으면 appId + appKey로 온라인 인증합니다. Dashboard에서 앱 Bundle ID를 바인딩하세요. 번들이 없는 커맨드라인 도구는 프로세스 이름을 바인딩하세요.

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,  // stills / NSImage
  FBFrameTypeVideo = 1   // live / camera
};

`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)setBodyReshape:(FBBodyReshape)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;
- (int)addResourcePack:(NSString *)fbdFilePath;
- (int)addResourcePackWithData:(NSData *)fbdData;
- (int)set3DSticker:(NSString *)resource;
- (int)set3DStickerWithData:(NSData *)fbdData;
- (int)clear3DSticker;

- (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,
};

바디 리셰이프

setBodyReshape:intensity: — 강도 [0.0, 1.0], 0은 꺼짐. 먼저 addResourcePack:으로 resource_body.fbd를 등록하세요. FBBodyReshape 값 0–8. 파라미터 열거형과 선택 리소스 팩을 참고하세요.

typedef NS_ENUM(NSInteger, FBBodyReshape) {
  FBBodyReshape_BodySlim = 0,
  FBBodyReshape_WaistSlim = 1,
  FBBodyReshape_LegSlim = 2,
  FBBodyReshape_ShoulderSlim = 3,
  FBBodyReshape_ArmSlim = 4,
  FBBodyReshape_LegLong = 5,
  FBBodyReshape_BustEnhance = 6,
  FBBodyReshape_LegStretch = 7,
  FBBodyReshape_TorsoLong = 8,
};

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로 등록하는 API는 없습니다. 경로 또는 바이트; GPU 리소스는 다음 processImage:(GL 스레드 / 외부 컨텍스트)에서 만들어집니다.

메서드	설명
`setFilter:`	`.fbd` 경로에서 LUT
`setFilterWithData:`	`.fbd` 바이트에서 LUT
`clearFilter`	LUT 제거
`setFilterIntensity:`	`[0, 1]`
`setSticker:`	2D 스티커 `.fbd` 경로
`setStickerWithData:`	스티커 바이트
`addResourcePack:`	추가 기능 팩 경로(예: `set3DSticker:` 전 `resource_3d.fbd`, `setBodyReshape:` 전 `resource_body.fbd`)
`addResourcePackWithData:`	추가 팩 바이트
`set3DSticker:`	3D 스티커 `.fbd` 경로
`set3DStickerWithData:`	3D 스티커 바이트
`clear3DSticker`	3D 스티커 제거
`clearSticker`	스티커 제거

빈 경로 / nil 또는 빈 NSData → FBErrorCode_InvalidArgument.

처리

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

imageFrame.type(FBFrameTypeImage 또는 FBFrameTypeVideo)을 읽습니다. 출력 형식은 입력과 일치합니다. 실패 시 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:` 시간(ms)
`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 points
@property(nonatomic, copy, nullable) NSArray<NSNumber *> *visibility;  // [0, 1]
@property(nonatomic, assign) int faceId;
@property(nonatomic, assign) float score;
@property(nonatomic, assign) float pitch;  // up -, down +; [-π, π]
@property(nonatomic, assign) float roll;   // left -, right +
@property(nonatomic, assign) float yaw;    // left -, right +
@end

`FBImageFrame`

생성

메서드	참고
`createWithData:width:height:format:`	원시 버퍼 + `FBImageFormat`
`createWithRGBA:width:height:stride:`
`createWithBGRA:width:height:stride:`
`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`; `stride`는 보통 `width * 4`
`createWithNSImage:`	macOS 전용

작업

메서드	설명
`rotate:`	`FBImageRotation`; `FBErrorCode` 반환
`mirror:`	`"horizontal"` / `"vertical"` / `"both"`(대소문자 무시); 픽셀을 변경
`setMirror:`	`processImage:`용 플래그(추가 변환을 피함). `nil` / `@""`는 지움
`convert:`	대상 `FBImageFormat`의 새 프레임을 반환
`toFile:quality:`	quality `0`–`100`
`toFile:`	quality `90`

속성과 접근자

width, height, stride, size, type. 메서드: data, format, texture(텍스처가 아니면 0). YUV: dataY / dataU / dataV / dataUV, strideY / strideU / strideV / strideUV(YUV가 아니면 NULL / 0).

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

typedef NS_ENUM(NSInteger, FBImageRotation) {
  FBImageRotation0,
  FBImageRotation90,   // clockwise
  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`

생성

작업

속성과 접근자

메이크업 / 스타일 열거형