API 参考

本文档对应 SDK 2.0.0。包名：net.pixpark.facebetter。美妆、整形、美白、磨皮预设见参数枚举。鉴权见授权认证。

美颜相关 setter 均返回 int。0（ErrorCode.SUCCESS）表示成功，负数为错误码。

日志

务必在 构造引擎之前 调用 BeautyEffectEngine.setLogConfig，否则看不到初始化日志。

LogLevel

public enum LogLevel {
  TRACE(0, "TRACE"),
  DEBUG(1, "DEBUG"),
  INFO(2, "INFO"),
  WARN(3, "WARN"),
  ERROR(4, "ERROR"),
  CRITICAL(5, "CRITICAL");
}

方法	说明
`int getLevel()`	数值级别（`0`–`5`）
`String getName()`	级别名称
`boolean isEnabledFor(LogLevel other)`	当前级别不低于 `other` 时为 `true`
`static LogLevel fromLevel(int level)`	按数值查找，未找到返回 `null`
`static LogLevel fromName(String name)`	忽略大小写查找，未找到返回 `null`

LogConfig

嵌套类：BeautyEffectEngine.LogConfig。

字段	类型	默认值	说明
`consoleEnabled`	`boolean`	`false`	输出到 logcat / 标准输出
`fileEnabled`	`boolean`	`false`	写入文件
`level`	`LogLevel`	`INFO`	最低输出级别
`fileName`	`String`	`""`	日志文件路径；仅当 `fileEnabled` 为 `true` 时生效

public static class LogConfig {
  public boolean consoleEnabled = false;
  public boolean fileEnabled = false;
  public LogLevel level = LogLevel.INFO;
  public String fileName = "";

  public LogConfig();
  public LogConfig(boolean consoleEnabled, boolean fileEnabled, LogLevel level, String fileName);
}

public static void setLogConfig(LogConfig config);

config 或 config.level 为 null 时抛出 IllegalArgumentException。

引擎

EngineConfig

嵌套类：BeautyEffectEngine.EngineConfig。

字段	类型	默认值	说明
`appId`	`String`	—	控制台 App ID
`appKey`	`String`	—	控制台 App Key
`licenseToken`	`String`	—	许可证 token、`{token}` JSON，或离线 `.lic` 全文
`externalContext`	`boolean`	`false`	`true` = 使用调用方 OpenGL ES 上下文；`false` = SDK 自建上下文

鉴权优先级： licenseToken 非空时，SDK 在本地校验该 token。否则必须提供 appId + appKey，SDK 请求 /facebetter/v2/auth。详见授权认证。

public static class EngineConfig {
  public String appId;
  public String appKey;
  public String licenseToken;
  public boolean externalContext = false;

  public EngineConfig();
  public EngineConfig(String appId, String appKey);
  public boolean isValid();
}

isValid()：licenseToken 非空，或 appId 与 appKey 均非空时返回 true。

BeautyEffectEngine

主引擎。创建一次，在 Activity / Fragment 销毁时调用 release()。

public BeautyEffectEngine(Context context, EngineConfig config);
public void release();

context 或 config 为 null，或 config.isValid() 为 false 时，构造函数抛出 IllegalArgumentException。SDK 使用 context.getPackageName() 做授权绑定。

FrameType

在调用 processImage 之前设置 ImageFrame.type。没有单独的处理模式参数。

取值	说明
`IMAGE`	单张静图，画质优先
`VIDEO`	相机 / 直播，延迟更低。默认值

public enum FrameType {
  IMAGE(0),
  VIDEO(1);
}

public ImageFrame processImage(ImageFrame inputFrame);

读取 inputFrame.type。返回处理后的帧（像素格式与输入一致）；引擎已释放时返回 null。inputFrame 或 inputFrame.type 为 null 时抛出 IllegalArgumentException。

美颜

强度范围 [0.0, 1.0]（除非另行说明）。0 表示关闭。

public int setSmoothing(float value);
public int setSmoothingStyle(SmoothingStyle style);
public int setWhitening(float value);
public int setWhiteningStyle(WhiteningStyle style);
public int setSharpening(float value);
public int setRosiness(float value);
public int setBeautySkinOnly(boolean enabled);

方法	说明
`setSmoothing`	磨皮强度
`setSmoothingStyle`	磨皮风格（`NATURAL`、`TEXTURE`、`SMOOTH`）
`setWhitening`	美白强度
`setWhiteningStyle`	美白 LUT（`COLD_WHITE`、`PINK_WHITE`、`WARM_WHITE`、`WHEAT`、`TAN`）
`setSharpening`	锐化强度
`setRosiness`	红润强度
`setBeautySkinOnly`	`true` = 仅在检测到的皮肤区域生效；`false` = 整帧

风格枚举见参数枚举。

整形

public int setReshape(Reshape param, float value);

强度范围 [-1.0, 1.0]。0 为关闭。正负为相反方向。

public enum Reshape {
  FACE_THIN(0), FACE_V_SHAPE(1), FACE_NARROW(2), FACE_SHORT(3),
  CHEEKBONE(4), JAWBONE(5), CHIN(6), NOSE_SLIM(7),
  EYE_SIZE(8), EYE_DISTANCE(9), FACE_SMALL(10), FOREHEAD(11),
  NOSE_LONG(12), PHILTRUM(13), MOUTH_SIZE(14), MOUTH_POSITION(15),
  MOUTH_SMILE(16), LIP_THICKNESS(17), EYE_ROUND(18), EYE_POSITION(19),
  EYE_ANGLE(20), EYE_CORNER_OPEN(21), LOWER_EYELID(22),
  BROW_POSITION(23), BROW_DISTANCE(24), BROW_THICKNESS(25);
}

各参数正负含义见参数枚举。

美妆

强度 [0.0, 1.0]。先设强度，再设风格（遮罩）和/或颜色（染色）。瞳孔与修容的着色方式见参数枚举。

public int setLipstick(float value);
public int setLipstickColor(LipstickColor color);

public int setBlush(float value);
public int setBlushStyle(BlushStyle style);
public int setBlushColor(BlushColor color);

public int setContour(float value);
public int setContourStyle(ContourStyle style);

public int setEyeShadow(float value);
public int setEyeShadowStyle(EyeShadowStyle style);
public int setEyeShadowColor(EyeShadowColor color);

public int setEyeLiner(float value);
public int setEyeLinerStyle(EyeLinerStyle style);
public int setEyeLinerColor(EyeLinerColor color);

public int setEyebrow(float value);
public int setEyebrowStyle(EyebrowStyle style);
public int setEyebrowColor(EyebrowColor color);

public int setEyelash(float value);
public int setEyelashStyle(EyelashStyle style);
public int setEyelashColor(EyelashColor color);

public int setPupil(float value);
public int setPupilColor(PupilColor color);

预设名在 BeautyParams.*。完整表格见参数枚举。

虚拟背景与色度键

默认用肖像分割作为遮罩。色度键会替换遮罩来源；填充仍是模糊或静态图。

public int setChromaKey(ChromaKeyColor color);
public int clearChromaKey();
public int setChromaKeySimilarity(float value);
public int setChromaKeySmoothness(float value);
public int setChromaKeyDesaturation(float value);

public int setVirtualBackgroundBlur(float level);
public int setVirtualBackground(String imagePath);
public int setVirtualBackground(byte[] imageData);
public int clearVirtualBackground();

方法	说明
`setChromaKey`	使用色度键作为遮罩（`GREEN`、`BLUE`、`RED`）
`clearChromaKey`	恢复肖像分割遮罩；不会清除当前填充
`setChromaKeySimilarity`	像素与键色的接近程度。`[0.0, 1.0]`
`setChromaKeySmoothness`	边缘羽化。`[0.0, 1.0]`
`setChromaKeyDesaturation`	半透明边缘溢色抑制。`[0.0, 1.0]`
`setVirtualBackgroundBlur`	背景模糊。`[0.0, 1.0]`。`0` 会清除虚拟背景
`setVirtualBackground(String)`	用 PNG/JPG 文件替换背景，路径不能为空
`setVirtualBackground(byte[])`	同上，传入编码后的 PNG/JPG 字节
`clearVirtualBackground`	清除模糊或图片填充

public enum ChromaKeyColor {
  GREEN(0),
  BLUE(1),
  RED(2);
}

空路径或空 byte[] 返回 ErrorCode.INVALID_ARGUMENT。

滤镜与贴纸

传入 .fbd 文件路径或文件字节（例如从 assets 读取）。资源在下一帧处理后生效。没有注册 / 反注册接口。

public int setFilter(String fbdFilePath);
public int setFilter(byte[] fbdData);
public int clearFilter();
public int setFilterIntensity(float intensity);

public int setSticker(String fbdFilePath);
public int setSticker(byte[] fbdData);
public int clearSticker();

方法	说明
`setFilter`	从 `.fbd` 路径或内存字节应用 LUT 滤镜
`clearFilter`	移除当前 LUT
`setFilterIntensity`	混合强度 `[0.0, 1.0]`
`setSticker`	从 `.fbd` 路径或字节应用 2D 贴纸
`clearSticker`	移除当前贴纸

空路径或空 byte[] 返回 ErrorCode.INVALID_ARGUMENT。

统计与回调

public EngineStats getStats();
public int setCallbacks(EngineCallbacks callbacks);

getStats() 返回快照。引擎未初始化时字段为 0。callbacks 为 null 时 setCallbacks 返回 ErrorCode.INVALID_ARGUMENT。

EngineStats

public class EngineStats {
  public double fps;
  public double avgProcessTimeMs;
  public double sessionTimeS;

  public EngineStats();
  public EngineStats(double fps, double avgProcessTimeMs, double sessionTimeS);
}

字段	说明
`fps`	近期处理帧率
`avgProcessTimeMs`	`processImage` 平均耗时（毫秒）
`sessionTimeS`	引擎创建后的秒数

EngineCallbacks

public class EngineCallbacks {
  public OnFaceLandmarksCallback onFaceLandmarks;
  public OnEngineEventCallback onEngineEvent;

  public interface OnFaceLandmarksCallback {
    void onFaceLandmarks(List<FaceDetectionResult> results);
  }

  public interface OnEngineEventCallback {
    void onEngineEvent(int code, String message);
  }
}

某个字段为 null 表示不订阅该回调。

EngineEventCode

public final class EngineEventCode {
  public static final int LICENSE_VALIDATION_SUCCESS = 0;
  public static final int LICENSE_VALIDATION_FAILED = 1;
  public static final int INITIALIZATION_COMPLETE = 100;
  public static final int INITIALIZATION_FAILED = 101;
}

码	含义
`0`	授权通过
`1`	授权失败，`message` 含详情
`100`	引擎可处理帧
`101`	引擎初始化失败，`message` 含详情

FaceDetectionResult

归一化坐标相对处理后的画面，范围 [0, 1]。

字段	类型	说明
`rect`	`Rect`	人脸框
`keyPoints`	`List<Point2d>`	111 个关键点
`visibility`	`List<Float>`	各点可见度 `[0, 1]`
`faceId`	`int`	跟踪 ID
`score`	`float`	检测置信度 `[0, 1]`
`pitch` / `roll` / `yaw`	`float`	头部姿态（弧度），范围 `[-π, π]`

Point2d 含 float x, y。Rect 含 float x, y, width, height（左上角原点）。

ErrorCode

数值与其他平台一致。

public final class ErrorCode {
  public static final int SUCCESS = 0;
  public static final int INVALID_ARGUMENT = -1;
  public static final int NOT_INITIALIZED = -2;
  public static final int LICENSE = -3;
  public static final int UNSUPPORTED = -4;
  public static final int IO = -5;
  public static final int NO_SLOT = -6;
  public static final int PROCESS = -7;
  public static final int OUT_OF_MEMORY = -8;
}

值	常量	含义
`0`	`SUCCESS`	成功
`-1`	`INVALID_ARGUMENT`	参数为空、空字符串或越界
`-2`	`NOT_INITIALIZED`	引擎未初始化，或已 `release()`
`-3`	`LICENSE`	授权 / 鉴权失败
`-4`	`UNSUPPORTED`	功能或格式不支持
`-5`	`IO`	文件或资源读写失败
`-6`	`NO_SLOT`	资源槽已满
`-7`	`PROCESS`	帧处理失败
`-8`	`OUT_OF_MEMORY`	内存分配失败

-1 表示参数无效。-2 表示引擎未初始化。

ImageFrame

封装原生像素缓冲。用完必须调用 release()。

创建

public static ImageFrame createWithFile(String filePath);
public static ImageFrame createWithRGBA(ByteBuffer data, int width, int height, int stride);
public static ImageFrame createWithBGRA(ByteBuffer data, int width, int height, int stride);
public static ImageFrame createWithRGB(ByteBuffer data, int width, int height, int stride);
public static ImageFrame createWithBGR(ByteBuffer data, int width, int height, int stride);
public static ImageFrame createWithI420(int width, int height,
    ByteBuffer yBuffer, int strideY, ByteBuffer uBuffer, int strideU,
    ByteBuffer vBuffer, int strideV);
public static ImageFrame createWithNV12(int width, int height,
    ByteBuffer yBuffer, int strideY, ByteBuffer uvBuffer, int strideUV);
public static ImageFrame createWithNV21(int width, int height,
    ByteBuffer yBuffer, int strideY, ByteBuffer vuBuffer, int strideVU);
public static ImageFrame createWithAndroid420(int width, int height,
    ByteBuffer yBuffer, int strideY, ByteBuffer uBuffer, int strideU,
    ByteBuffer vBuffer, int strideV, int pixelStrideUV);
public static ImageFrame createWithTexture(int texture, int width, int height, int stride);
public static ImageFrame createWithBitmap(Bitmap bitmap);

工厂方法	说明
`createWithFile`	PNG / JPG 路径
`createWithAndroid420`	Camera2 `YUV_420_888`
`createWithTexture`	当前 GL 上下文中的 `GL_TEXTURE_2D`；`stride` 通常为 `width * 4`
`createWithBitmap`	将 `ARGB_8888` 像素拷入 RGBA 帧

失败返回 null（无效 Bitmap、原生分配失败等）。打包 / 平面格式建议使用 ByteBuffer.allocateDirect。

字段与操作

public FrameType type = FrameType.VIDEO;

public int rotate(Rotation rotation);
public int mirror(String mode);
public void setMirror(String mode);
public ImageFrame convert(Format format);
public int toFile(String path, int quality);
public int toFile(String path);
public Bitmap toBitmap();
public boolean isValid();
public void release();

方法	说明
`rotate`	原地旋转，成功返回 `0`
`mirror`	立即镜像。`mode`：`"horizontal"`、`"vertical"`、`"both"`（忽略大小写）
`setMirror`	在 `processImage` 内部应用镜像（避免额外格式转换）。`""` / `null` 清除
`convert`	返回新帧；调用方必须 `release()`
`toFile`	写出 PNG/JPG。质量 `1`–`100`；重载默认 `90`
`toBitmap`	`ARGB_8888` `Bitmap`（必要时先转 RGBA）

访问器

public int getWidth();
public int getHeight();
public int getStride();
public int getSize();
public ByteBuffer getData();
public Format getFormat();
public int getTexture();

public ByteBuffer getDataY();
public ByteBuffer getDataU();
public ByteBuffer getDataV();
public ByteBuffer getDataUV();
public int getStrideY();
public int getStrideU();
public int getStrideV();
public int getStrideUV();

未绑定 GPU 纹理时 getTexture() 返回 0。

Format

public enum Format {
  I420(0),     // YUV 4:2:0 平面 Y, U, V
  NV12(1),     // YUV 4:2:0 Y + UV
  NV21(2),     // YUV 4:2:0 Y + VU（Android 相机常用）
  BGRA(3),
  RGBA(4),
  BGR(5),
  RGB(6),
  Texture(7);
}

Rotation

顺时针。

public enum Rotation {
  ROTATION_0(0),
  ROTATION_90(1),
  ROTATION_180(2),
  ROTATION_270(3);
}

产品介绍

Android

iOS

macOS

Windows

Linux

Web

Flutter

日志

LogLevel

LogConfig

引擎

EngineConfig

BeautyEffectEngine

FrameType

美颜

整形

美妆

虚拟背景与色度键

滤镜与贴纸

统计与回调

EngineStats

EngineCallbacks

EngineEventCode

FaceDetectionResult

ErrorCode

ImageFrame

创建

字段与操作

访问器

Format

Rotation

​日志

​LogLevel

​LogConfig

​引擎

​EngineConfig

​BeautyEffectEngine

​FrameType

​美颜

​整形

​美妆

​虚拟背景与色度键

​滤镜与贴纸

​统计与回调

​EngineStats

​EngineCallbacks

​EngineEventCode

​FaceDetectionResult

​ErrorCode

​ImageFrame

​创建

​字段与操作

​访问器

​Format

​Rotation

日志

LogLevel

LogConfig

引擎

EngineConfig

BeautyEffectEngine

FrameType

美颜

整形

美妆

虚拟背景与色度键

滤镜与贴纸

统计与回调

EngineStats

EngineCallbacks

EngineEventCode

FaceDetectionResult

ErrorCode

ImageFrame

创建

字段与操作

访问器

Format

Rotation