API 参考

SDK 2.0.0。命名空间 facebetter。头文件：facebetter/beauty_effect_engine.h、beauty_params.h、image_frame.h、type_defines.h。风格 / 色号 / 美型枚举见参数枚举。鉴权见授权与许可。

日志

`LogLevel`

enum class LogLevel {
  Trace = 0,
  Debug,
  Info,
  Warn,
  Error,
  Critical
};

`LogConfig`

字段	默认	说明
`console_enabled`	`false`	输出到 stdout
`file_enabled`	`false`	写入文件
`level`	`Info`	最低级别
`file_name`	`""`	`file_enabled` 为 true 时的路径

struct LogConfig {
  bool console_enabled = false;
  bool file_enabled = false;
  LogLevel level = LogLevel::Info;
  std::string file_name = "";
};

引擎

`EngineConfig`

字段	说明
`app_id`	控制台应用 ID（与 `app_key` 一起做在线 v2 鉴权）
`app_key`	控制台应用密钥
`resource_path`	`resource.fbd` 文件路径（桌面端必需）
`license_token`	许可证 token、`{token}` JSON，或离线 `.lic` 内容
`external_context`	`false`：SDK 管理 OpenGL 上下文。`true`：使用调用方当前上下文

鉴权优先级： license_token 非空则本地校验该 token，不再用 app_id + app_key 联网。否则用 app_id + app_key 请求 /facebetter/v2/auth。

struct EngineConfig {
  std::string app_id;
  std::string app_key;
  std::string resource_path;
  std::string license_token;
  bool external_context = false;
};

`BeautyEffectEngine`

不可拷贝。通过 Create 创建，释放 shared_ptr 即销毁。

`SetLogConfig`（静态）

static int SetLogConfig(const LogConfig& config);

在 Create 之前调用。成功返回 0。

`Create`（静态）

static std::shared_ptr<BeautyEffectEngine> Create(const EngineConfig& config);

失败返回 nullptr。

EngineConfig cfg;
cfg.app_id = "your_app_id";
cfg.app_key = "your_app_key";
cfg.resource_path = "resource/resource.fbd";
auto engine = BeautyEffectEngine::Create(cfg);

皮肤

强度默认 [0.0, 1.0]，0 表示关闭。成功返回 0。

virtual int SetSmoothing(float intensity) = 0;
virtual int SetSmoothingStyle(beauty_params::SmoothingStyle style) = 0;
virtual int SetWhitening(float intensity) = 0;
virtual int SetWhiteningStyle(beauty_params::WhiteningStyle style) = 0;
virtual int SetSharpening(float intensity) = 0;
virtual int SetRosiness(float intensity) = 0;
virtual int SetBeautySkinOnly(bool enabled) = 0;

SetBeautySkinOnly(true) 时磨皮 / 美白等仅作用于检测到的皮肤。风格枚举见参数枚举。

美型

virtual int SetReshape(beauty_params::Reshape param, float intensity) = 0;

intensity 为 [-1.0, 1.0]。0 关闭。正负为相反方向。完整列表见参数枚举。

engine->SetReshape(Reshape::FaceThin, 0.4f);

美体

virtual int SetBodyReshape(beauty_params::BodyReshape param, float intensity) = 0;

intensity 为 [0.0, 1.0]。0 关闭。需要 resource_body.fbd（与 resource.fbd 同目录，或 AddResourcePack）。完整列表见参数枚举，资源包见可选资源包。

engine->SetBodyReshape(BodyReshape::WaistSlim, 0.4f);

美妆

每个效果有强度，以及 Style（蒙版）和/或 Color（染色）。口红只有 Color；美瞳只有 Color；修容只有 Style。

virtual int SetLipstick(float intensity) = 0;
virtual int SetLipstickColor(beauty_params::LipstickColor color) = 0;

virtual int SetBlush(float intensity) = 0;
virtual int SetBlushStyle(beauty_params::BlushStyle style) = 0;
virtual int SetBlushColor(beauty_params::BlushColor color) = 0;

virtual int SetContour(float intensity) = 0;
virtual int SetContourStyle(beauty_params::ContourStyle style) = 0;

virtual int SetEyeShadow(float intensity) = 0;
virtual int SetEyeShadowStyle(beauty_params::EyeShadowStyle style) = 0;
virtual int SetEyeShadowColor(beauty_params::EyeShadowColor color) = 0;

virtual int SetEyeLiner(float intensity) = 0;
virtual int SetEyeLinerStyle(beauty_params::EyeLinerStyle style) = 0;
virtual int SetEyeLinerColor(beauty_params::EyeLinerColor color) = 0;

virtual int SetEyebrow(float intensity) = 0;
virtual int SetEyebrowStyle(beauty_params::EyebrowStyle style) = 0;
virtual int SetEyebrowColor(beauty_params::EyebrowColor color) = 0;

virtual int SetEyelash(float intensity) = 0;
virtual int SetEyelashStyle(beauty_params::EyelashStyle style) = 0;
virtual int SetEyelashColor(beauty_params::EyelashColor color) = 0;

virtual int SetPupil(float intensity) = 0;
virtual int SetPupilColor(beauty_params::PupilColor color) = 0;

取值见参数枚举。

色度键

用作虚拟背景蒙版。填充仍由 SetVirtualBackgroundBlur / SetVirtualBackground 控制。无填充时抠除区域透明。ClearChromaKey() 恢复人像分割。

virtual int SetChromaKey(beauty_params::ChromaKeyColor color) = 0;
virtual int ClearChromaKey() = 0;
virtual int SetChromaKeySimilarity(float value) = 0;   // [0, 1]
virtual int SetChromaKeySmoothness(float value) = 0;   // [0, 1]
virtual int SetChromaKeyDesaturation(float value) = 0; // [0, 1]

ChromaKeyColor：Green = 0、Blue、Red。

虚拟背景

virtual int SetVirtualBackgroundBlur(float level) = 0;  // [0, 1]；0 清除填充
virtual int SetVirtualBackground(const std::string& image_path) = 0;
virtual int SetVirtualBackground(const std::vector<uint8_t>& image_data) = 0;
virtual int ClearVirtualBackground() = 0;

PNG / JPEG。路径不可为空。字节重载为编码后的图片数据。

滤镜（LUT `.fbd`）

GPU LUT 在下一次 ProcessImage 时创建。没有注册 / ID 接口。

virtual int SetFilter(const std::string& fbd_file_path) = 0;
virtual int SetFilter(const std::vector<uint8_t>& fbd_data) = 0;
virtual int ClearFilter() = 0;
virtual int SetFilterIntensity(float intensity) = 0;  // [0, 1]

贴纸（`.fbd`）

virtual int SetSticker(const std::string& fbd_file_path) = 0;
virtual int SetSticker(const std::vector<uint8_t>& fbd_data) = 0;
virtual int ClearSticker() = 0;
virtual int AddResourcePack(const std::string& fbd_file_path) = 0;
virtual int AddResourcePack(const std::vector<uint8_t>& fbd_data) = 0;
virtual int Set3DSticker(const std::string& resource) = 0;
virtual int Set3DSticker(const std::vector<uint8_t>& fbd_data) = 0;
virtual int Clear3DSticker() = 0;

3D 贴纸或美体前请先加载对应可选包，见可选资源包。

统计、回调、处理

virtual EngineStats GetStats() const = 0;
virtual int SetCallbacks(const EngineCallbacks& callbacks) = 0;
virtual const std::shared_ptr<ImageFrame> ProcessImage(
    const std::shared_ptr<ImageFrame> image_frame) = 0;

将 image_frame->type 设为 FrameType::Image 或 FrameType::Video（默认）。输出格式尽量与输入一致。失败返回 nullptr。

input->type = FrameType::Video;
auto output = engine->ProcessImage(input);

`EngineStats`

struct EngineStats {
  double fps = 0.0;
  double avg_process_time_ms = 0.0;
  double session_time_s = 0.0;
};

回调与事件

enum class EngineEventCode {
  LicenseValidationSuccess = 0,
  LicenseValidationFailed = 1,
  EngineInitializationComplete = 100,
  EngineInitializationFailed = 101,
};

码	含义
`0`	授权成功
`1`	授权失败
`100`	初始化完成
`101`	初始化失败

struct EngineCallbacks {
  std::function<void(const std::vector<FaceDetectionResult>& results)>
      on_face_landmarks = nullptr;
  std::function<void(int code, const std::string& message)>
      on_engine_event = nullptr;
};

on_face_landmarks 可能每帧触发（无人脸时为空）。

图像

`Format`

enum class Format {
  I420, NV12, NV21, BGRA, RGBA, BGR, RGB, Texture
};

`Rotation`

enum class Rotation {
  Rotation_0, Rotation_90, Rotation_180, Rotation_270  // 顺时针
};

`FrameType`

enum class FrameType {
  Image = 0,  // 静图 / 照片
  Video = 1   // 视频流（默认）
};

设置在 ImageFrame::type 上。

`ImageFrame`

不可拷贝，非线程安全。 工厂方法

static std::shared_ptr<ImageFrame> CreateWithFile(const std::string& file_path);
static std::shared_ptr<ImageFrame> Create(
    const uint8_t* data, int width, int height, Format format);
static std::shared_ptr<ImageFrame> CreateWithRGBA(
    const uint8_t* data, int width, int height, int stride);
static std::shared_ptr<ImageFrame> CreateWithBGRA(
    const uint8_t* data, int width, int height, int stride,
    bool copy_data = false);
static std::shared_ptr<ImageFrame> CreateWithRGB(
    const uint8_t* data, int width, int height, int stride);
static std::shared_ptr<ImageFrame> CreateWithBGR(
    const uint8_t* data, int width, int height, int stride);
static std::shared_ptr<ImageFrame> CreateWithI420(
    int width, int height,
    const uint8_t* dataY, int strideY,
    const uint8_t* dataU, int strideU,
    const uint8_t* dataV, int strideV);
static std::shared_ptr<ImageFrame> CreateWithNV12(
    int width, int height,
    const uint8_t* dataY, int strideY,
    const uint8_t* dataUV, int strideUV);
static std::shared_ptr<ImageFrame> CreateWithNV21(
    int width, int height,
    const uint8_t* dataY, int strideY,
    const uint8_t* dataUV, int strideUV);
static std::shared_ptr<ImageFrame> CreateWithTexture(
    uint32_t texture, int width, int height, int stride);

多平面 YUV 请用专用工厂，不要用通用 Create。操作

int Rotate(Rotation rotation);
int Mirror(const std::string& mode);       // "horizontal" | "vertical" | "both"
void SetMirror(const std::string& mode);   // 在 ProcessImage 内应用；"" 清除
std::shared_ptr<ImageFrame> Convert(Format format) const;
int ToFile(const std::string& path, int quality = 90) const;

访问器： Width()、Height()、Stride()、Size()、GetFormat()、Data()、DataY/U/V()、StrideY/U/V()、DataUV()、StrideUV()、Texture()、Buffer()、MirrorHorizontal()、MirrorVertical()。公开字段：FrameType type = FrameType::Video。

检测类型

struct Point2d { float x; float y; };  // 归一化 [0, 1]
struct Rect { float x, y, width, height; };  // 归一化

struct FaceDetectionResult {
  Rect rect;
  std::vector<Point2d> key_points;  // 111 点
  std::vector<float> visibility;
  int face_id = -1;
  float score = 0.0f;
  float pitch = 0.0f;  // 上负下正
  float roll = 0.0f;
  float yaw = 0.0f;
};

错误码

典型 int 返回值：

码	含义
`0`	成功
`-1`	参数非法
`-2`	未初始化
`-3`	授权
`-4`	不支持
`-5`	I/O
`-6`	无槽位
`-7`	处理失败
`-8`	内存不足

说明

线程安全： 将 ProcessImage 与会改状态的调用串行化到同一线程（external_context 时则在 GL 线程）。
生命周期： 工厂方法返回 std::shared_ptr。
Data() 指针只读，不要写入。
SetRenderView 仅 iOS / macOS。
Windows 二进制： 链接 facebetter.lib，运行时加载 facebetter.dll。

产品介绍

Android

iOS

macOS

Windows

Linux

Web

日志

`LogLevel`

`LogConfig`

引擎

`EngineConfig`

`BeautyEffectEngine`

`SetLogConfig`（静态）

`Create`（静态）

皮肤

美型

美体

美妆

色度键

虚拟背景

滤镜（LUT `.fbd`）

贴纸（`.fbd`）

统计、回调、处理

`EngineStats`

回调与事件

图像

`Format`

`Rotation`

`FrameType`

`ImageFrame`

检测类型

错误码

说明

​日志

​LogLevel

​LogConfig

​引擎

​EngineConfig

​BeautyEffectEngine

​SetLogConfig（静态）

​Create（静态）

​皮肤

​美型

​美体

​美妆

​色度键

​虚拟背景

​滤镜（LUT .fbd）

​贴纸（.fbd）

​统计、回调、处理

​EngineStats

​回调与事件

​图像

​Format

​Rotation

​FrameType

​ImageFrame

​检测类型

​错误码

​说明

日志

`LogLevel`

`LogConfig`

引擎

`EngineConfig`

`BeautyEffectEngine`

`SetLogConfig`（静态）

`Create`（静态）

皮肤

美型

美体

美妆

色度键

虚拟背景

滤镜（LUT `.fbd`）

贴纸（`.fbd`）

统计、回调、处理

`EngineStats`

回调与事件

图像

`Format`

`Rotation`

`FrameType`

`ImageFrame`

检测类型

错误码

说明