API 参考

本文档对应 SDK 2.0.0。美妆 / 美型 / 风格枚举：参数枚举。鉴权：授权与许可。

npm 包：facebetter。常用导入：

import {
  BeautyEffectEngine,
  EngineConfig,
  FrameType,
  MirrorMode,
  Reshape,
} from 'facebetter';

EngineConfig

new EngineConfig({
  licenseToken,      // string — 必填。许可证 token，或 `{token}` JSON
})

Web 不接受在该对象上设置 appId / appKey。Web 不支持离线 .lic。 licenseToken 为非空字符串时 isValid() 为 true。在 init() 之前由你的服务器换好 token。见授权与许可。

BeautyEffectEngine

const engine = new BeautyEffectEngine(config);
await engine.init({
  onProgress: ({ percent }) => {
    // 运行时文件下载时 0–100
  },
});

生命周期

方法	说明
`init(options?)`	初始化引擎（鉴权与资源）。`options.timeout`（默认 `120000`）为初始化超时（毫秒）。`options.onProgress({ loaded, total, percent })` 报告运行时文件的下载进度。
`setLogConfig({ consoleEnabled, fileEnabled, level, fileName })`	全局日志。请在 `init()` 前调用。`level`：`0` TRACE … `5` CRITICAL。浏览器不支持文件日志。返回 `Promise<void>`。
`destroy()`	释放引擎及其资源。

init() 成功后 engine.initialized 为 true。

皮肤

方法	范围
`setSmoothing(value)`	`[0, 1]`
`setSmoothingStyle(style)`	`SmoothingStyle`
`setWhitening(value)`	`[0, 1]`
`setWhiteningStyle(style)`	`WhiteningStyle`
`setSharpening(value)`	`[0, 1]`
`setRosiness(value)`	`[0, 1]`
`setBeautySkinOnly(enabled)`	`boolean`

美型

setReshape(param, value) — param 为 Reshape.*，value 范围 [-1.0, 1.0]。见参数枚举。

美体

setBodyReshape(param, value) — param 为 BodyReshape.*，value 范围 [0.0, 1.0]。需先 addResourcePack 加载 resource_body.fbd。见参数枚举与可选资源包。

美妆

强度 [0, 1]。风格 / 色号枚举：参数枚举。

强度	风格 / 色号
`setLipstick`	`setLipstickColor`
`setBlush`	`setBlushStyle`、`setBlushColor`
`setContour`	`setContourStyle`
`setEyeShadow`	`setEyeShadowStyle`、`setEyeShadowColor`
`setEyeLiner`	`setEyeLinerStyle`、`setEyeLinerColor`
`setEyebrow`	`setEyebrowStyle`、`setEyebrowColor`
`setEyelash`	`setEyelashStyle`、`setEyelashColor`
`setPupil`	`setPupilColor`

滤镜 / 贴纸

方法	说明
`setFilter(path \| Uint8Array)`	用 URL 或字节应用 LUT `.fbd`
`clearFilter()`	清除当前滤镜
`setFilterIntensity(intensity)`	`[0, 1]`
`setSticker(path \| Uint8Array)`	应用 2D 贴纸 `.fbd`
`clearSticker()`	清除贴纸
`addResourcePack(path \| Uint8Array)`	登记额外能力包（3D 贴纸前加载 `resource_3d.fbd`，美体前加载 `resource_body.fbd`）
`set3DSticker(path \| Uint8Array)`	应用 3D 贴纸 `.fbd`
`clear3DSticker()`	清除 3D 贴纸

虚拟背景 / 色度键

方法	说明
`setVirtualBackgroundBlur(level)`	连续虚化 `[0, 1]`。`0` 表示关闭
`setVirtualBackground(path \| Uint8Array)`	png/jpg 路径或编码字节
`clearVirtualBackground()`	关闭虚化 / 背景图
`setChromaKey(color)`	`ChromaKeyColor.Green` / `Blue` / `Red`
`clearChromaKey()`	恢复人像分割遮罩
`setChromaKeySimilarity(value)`	`[0, 1]`
`setChromaKeySmoothness(value)`	`[0, 1]`
`setChromaKeyDesaturation(value)`	`[0, 1]`

回调

engine.setCallbacks({
  onFaceLandmarks, // (faces) => void
  onEngineEvent,   // (code, message) => void
  maxFaces,        // 可选，默认 10
});

处理

processImage(input, width, height, frameType = FrameType.Video, mirrorMode = MirrorMode.None) → ImageData

input：ImageData | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | Uint8ClampedArray
仅 Uint8ClampedArray 时必须传 width / height

processTexture(textureHandle, width, height, stride, frameType, mirrorMode) → number

返回输出 GL_TEXTURE_2D 句柄。该路径不应用镜像。 请优先使用 processImage。

统计

engine.getStats() → { fps, avgProcessTimeMs, sessionTimeS }

枚举（JS）

取值与原生一致。美妆 / 美型完整表：参数枚举。

FrameType = { Image: 0, Video: 1 }

MirrorMode = { None: 0, Horizontal: 1, Vertical: 2, Both: 3 }

EngineEventCode = {
  LicenseValidationSuccess: 0,
  LicenseValidationFailed: 1,
  InitializationComplete: 100,
  InitializationFailed: 101,
}

ChromaKeyColor = { Green: 0, Blue: 1, Red: 2 }

Reshape = { FaceThin: 0, FaceVShape: 1, /* … BrowThickness: 25 */ }

同时导出：SmoothingStyle、WhiteningStyle、LipstickColor、BlushStyle、BlushColor、ContourStyle、EyeShadowStyle、EyeShadowColor、EyeLinerStyle、EyeLinerColor、EyebrowStyle、EyebrowColor、EyelashStyle、EyelashColor、PupilColor。

FacebetterError

class FacebetterError extends Error {
  constructor(message, code = -1)
  // name === 'FacebetterError'
  // code: number 或 string
}

数值码：0、-1 … -8。见错误处理。

产品介绍

Android

iOS

macOS

Windows

Linux

Web

EngineConfig

BeautyEffectEngine

生命周期

皮肤

美型

美体

美妆

滤镜 / 贴纸

虚拟背景 / 色度键

回调

处理

统计

枚举（JS）

FacebetterError

​EngineConfig

​BeautyEffectEngine

​生命周期

​皮肤

​美型

​美体

​美妆

​滤镜 / 贴纸

​虚拟背景 / 色度键

​回调

​处理

​统计

​枚举（JS）

​FacebetterError

EngineConfig

BeautyEffectEngine

生命周期

皮肤

美型

美体

美妆

滤镜 / 贴纸

虚拟背景 / 色度键

回调

处理

统计

枚举（JS）

FacebetterError