tencent cloud

腾讯特效 SDK

动态与公告
产品动态
关于腾讯特效 SDK V3.5 版本更新公告
关于腾讯特效 SDK V3.0 版本相关接口及素材变更公告
产品简介
产品概述
产品功能
基本概念
产品优势
应用场景
购买指南
价格总览
购买流程
欠费退费说明
新手指引
Demo 体验
免费测试
License 指引
移动端 License 新增与续期
PC 端 License 新增与续期
Web端 License 新增与续期
常见问题
SDK 下载
功能说明
SDK 下载
版本历史
SDK 集成指引(无 UI)
通用集成腾讯特效
原子能力集成指引
SDK 集成指引(含 UI)
通用集成腾讯特效
直播 SDK 集成腾讯特效
TRTC SDK 集成腾讯特效
短视频 SDK 集成腾讯特效
Avatar 虚拟人集成指引
API 文档
iOS
Android
Flutter
Web
功能实践
SDK 包瘦身
SDK 集成问题排查
性能调优
效果调优
素材使用
美颜参数说明
美颜场景推荐参数
短视频企业版迁移指引
第三方推流接入美颜(Flutter)
小程序美颜特效实践
素材制作工具使用
Web 美颜特效
产品概述
快速上手
SDK 接入
API 文档
控制台指南
Demo 体验
内置素材总览
实践教程
常见问题
常见问题
通用类相关
技术类相关
License 相关
旧版文档
美颜场景推荐参数
美颜参数表
一分钟集成 TRTC
一分钟集成直播
TE SDK 政策
隐私协议
数据处理和安全协议
联系我们

Web

PDF
聚焦模式
字号
最后更新时间: 2025-12-05 10:46:13
本文档将介绍 Web 美颜特效 SDK 核心参数及方法。
说明:
Web 美颜特效 SDK 需要浏览器支持并开启硬件加速才能够流畅渲染,因此 SDK 提供了检测方法供业务提前判断,如不支持则进行屏蔽处理。
import {ArSdk, isWebGLSupported} from 'tencentcloud-webar'

if(isWebGLSupported()) {
const sdk = new ArSdk({
...
})
} else {
// 屏蔽逻辑
}

初始化参数

import { ArSdk } from 'tencentcloud-webar'
// 初始化SDK
const sdk = new ArSdk({
... // 参考下述 Config 定义
})
初始化 SDK 的 Config 支持以下参数:
参数
说明
类型
是否必传
module
模块配置
type SegmentationLevel = 0 | 1 | 2 // 1.0.19 之后的版本支持传参选择分割模型,数值越高,分割效果越好,资源占用越大,fps 越低
type ModuleConfig = {
beautify: boolean // 是否开启美颜,默认为true
segmentation: boolean // 是否开启背景分割,默认为false
segmentationLevel: SegmentationLevel // 背景分割精确度等级,默认为 0
handGesture: boolean // 是否开启手势识别,默认为 false, 1.0.23 之后版本支持
handLandmark: boolean // 是否开启手部追踪,默认为 false,1.0.23 之后版本支持, 不推荐和 beautify 同时启用
}
否,默认为 {beautify: true, segmentation: false, segmentationLevel: 0,
handLandmark: false}
auth
鉴权参数
type AuthConfig = {
licenseKey: string // 控制台 Web License 管理 获取
appId: string // 控制台 账号信息 > 基本信息 查看 APPID
authFunc:() => Promise<{
signature:string,
timestamp:string
}> // 请参见 License 配置使用
}
input
媒体输入源,支持处理 mediaStream,图片,及视频
MediaStream | HTMLImageElement | String | HTMLVideoElement
camera
内置相机
type CameraConfig = {
width: number, // 拍摄画面宽度
height: number, // 拍摄画面高度
mirror: boolean, // 是否开启左右镜像
frameRate: number // 画面采集帧率
}
mirror
是否镜像,支持输入流的镜像(1.0.19 新增)
Boolean
beautify
美颜参数
type BeautifyOptions = {
whiten?: number; // 美白 0-1
dermabrasion?: number; // 磨皮0-1
lift?: number; // 窄脸0-1
shave?: number; // 削脸0-1
eye?: number; // 大眼0-1
chin?: number; // 下巴0-1
// 注意:以下参数仅在1.0.11及以上版本可用
darkCircle?: number; // 黑眼圈0-1
nasolabialFolds?: number; // 法令纹0-1
cheekbone?: number; // 颧骨0-1
head?: number; // 小头0-1
eyeBrightness?: number; // 亮眼0-1
lip?: number; //嘴唇 -1 - 1
forehead?: number; //发际线 0-1
nose?: number; // 鼻子 -1 - 1
usm?: number; // 清晰 0-1
}
background
背景参数
type BackgroundOptions = {
type: 'image' | 'blur' | 'transparent' | 'video', // 1.0.23 版本开始支持 video 类型动态背景
src?: string, // image 或 video 类型指定的图片地址
}
loading
内置 loading icon 配置
type loadingConfig = {
enable: boolean,
size?: number
lineWidth?: number
strokeColor?: number
}

language
国际化对应(1.0.6版本开始支持),中文(zh)和英文(en)
1.0.26 版本支持日语(jp)
String: zh | en|jp
否,默认 zh
logLevel
打印控制台日志等级
'OFF' | 'ERROR' | 'WARN' | 'DEBUG' | 'TRACE' | 'INFO'
否,默认 INFO,全部打印
initReport
是否初始化日志上报模块
Boolean
否,默认为 true
worker
是否禁用浏览器 worker,以优化特定场景的性能
String: auto | disable
否,默认 auto,SDK 根据当前浏览器环境决定是否使用 worker
proxyServer
内网代理模式用
type proxyServeConfig = {
webarProxy: string; // 接口代理的内网地址
staticProxy: string; // 资源代理的内网地址
}

回调事件

let effectList = [];
let filterList = [];
// sdk 的回调用法
sdk.on('created', () => {
// 在 created 回调中拉取特效和滤镜列表供页面展示
sdk.getEffectList({
Type: 'Preset',
Label: '美妆',
}).then(res => {
effectList = res
});
sdk.getCommonFilter().then(res => {
filterList = res
})
})
sdk.on('cameraReady', async () => {
// 在 cameraReady 回调中可以更早地获取输出画面,此时初始化传入的美颜参数还未生效
// 适用于需要尽早地展示画面,但不要求画面一展示就有美颜的场景
// 后续美颜生效后无需更新stream,SDK内部已处理
const arStream = await ar.getOutput();
// 本地播放
// localVideo.srcObject = arStream

})
sdk.on('ready', () => {
// 在 ready 回调中获取输出画面,此时初始化传入的美颜参数已生效
// 区别上述cameraReady中获取output,适用于画面一展示就要有美颜的场景,但不要求尽早地展示画面
// 根据自身业务需求选择一种处理方式即可
const arStream = await ar.getOutput();
// 本地播放
// localVideo.srcObject = arStream

// 在 ready 回调中调用 setBeautify/setEffect/setFilter 等渲染方法
sdk.setBeautify({
whiten: 0.3
});
sdk.setEffect({
id: effectList[0].EffectId,
intensity: 0.7
});
sdk.setEffect({
id: effectList[0].EffectId,
intensity: 0.7,
filterIntensity: 0.5 // 0.1.18及以上版本支持单独设置effect中滤镜的强度,不传则默认与特效的intensity保持一致
});
sdk.setFilter(filterList[0].EffectId, 0.5)
})
// 开启手势识别后,监听到手势变化时触发
sdk.on('handGesture',(hands)=>{
// 对应 hand 取值 none, thumb_up, thumb_down, victory, pointing_up, open_palm, iloveyou
})
// error 回调,影响 sdk 使用的 error 发生
sdk.on('error', (data)=>{
console.log('error', data.code, data.message)
})
// warning 回调,常见于 sdk 检测到耗时占用增加时抛出警告
sdk.on('warning', (data)=>{
console.log('warning', data.code, data.message)
})
事件
说明
回调参数
created
SDK 鉴权完成并成功创建实例时触发
-
cameraReady
SDK 的画面生成时触发,此时 output 已有画面但美颜仍无法生效
-
ready
SDK 内部检测初始化完成时触发,此时 output 画面已有美颜,也可以设置新的特效
-
error
SDK 发生错误时触发
error 对象
warning
SDK 发生警告时触发
warning 对象
handGesture
开启手势识别后,监听到手势变化时触发
识别到的手势
detectStatusChange
人脸检测状态发生变化时触发
Boolean, 是否识别到人脸

对象方法

接口
参数
返回
说明
setBeautify(options)
type BeautifyOptions = {
whiten?: number; // 美白 0-1
dermabrasion?: number; // 磨皮0-1
lift?: number; // 窄脸0-1
shave?: number; // 削脸0-1
eye?: number; // 大眼0-1
chin?: number; // 下巴0-1
// 注意:以下参数仅在1.0.11及以上版本可用
darkCircle?: number; // 黑眼圈0-1
nasolabialFolds?: number; // 法令纹0-1
cheekbone?: number; // 颧骨0-1
head?: number; // 小头0-1
eyeBrightness?: number; // 亮眼0-1
lip?: number; //嘴唇 -1 - 1
forehead?: number; //发际线 0-1
nose?: number; // 鼻子 -1 - 1
usm?: number; // 清晰 0-1
}
-
设置美颜参数,需开启beautify模块

setEffect(effects, callback, errCallback)
effects:特效 ID | Effect 对象 | (特效 ID | Effect对象) 数组
// effect对象
type Effect = {
id: string; // 特效 id
intensity: number; // 特效整体强度,取值范围 0-1,默认为 1
filterIntensity: number; // 特效中的滤镜强度啊,取值范围 0-1,默认为 1
};
callback:设置成功的回调
errCallback: 失败回调
-
设置美妆、贴纸特效,需开启beautify模块
3D 类特效仅高级版License 支持
setAvatar(params)
{
mode: 'AR' | 'VR',
effectId?: string, // 透传effectId使用内置模型
url?: string, // 透传url使用自定义模型
backgroundUrl?: string, // 背景图片链接,仅在VR模式下生效
}
-
设置 Animoji 表情或虚拟形象,需开启beautify模块
仅高级版 License 支持
setBackground(options)
{
type: 'image|video|blur|transparent', // 1.0.23 版本开始支持 video 类型动态背景
src: string, // image|video类型需要
}
-

设置背景,Web 端需开启segmentation模块
setForeground(options)(1.0.23 版本开始支持)
{
type: 'image|video',
src: string // 资源路径,base64或者在线地址
}
-
设置固定于屏幕的全屏前景效果
setSegmentationLevel(level)
level: 0 | 1 | 2
-
切换背景分割模型的等级
setFilter(id, intensity, callback, errCallback)
id:滤镜 ID
intensity:滤镜强度,取值范围0-1,默认为 1
callback:设置成功回调
errCallback: 失败回调
-
设置滤镜
getEffectList(params)
{
PageNumber: number, // 分页,默认 0
PageSize: number, // 分页大小,默认 1000
Name: '', // 特效名称
Label: string | Array<string>, // 特效标签、特效标签列表
Type: 'Custom' | 'Preset' // 特效类型, Custom-用户自定义特效,Preset-内置特效
}

特效列表
拉取特效列表
getAvatarList(type)
type = 'AR' | 'VR' // AR-Animoji,VR-虚拟形象
Animoji/虚拟形象列表

拉取Animoji/虚拟形象列表
getEffect(effectId)
effectId:特效 ID
单个特效信息
拉取指定特效的信息
getCommonFilter()
-
内置滤镜列表
获取内置滤镜列表
async initCore()

{
input?: MediaStream|HTMLImageElement|String; // 输入源
camera?: CameraConfig; // 摄像头模式
mirror?: boolean; // 是否镜像
}
-
仅供预初始化方案使用,为 SDK 提供输入信息,详情参考 加载优化
async updateInputStream(src, stopOldTracks) (0.1.19版本后支持)
src:新的输入流 MediaStream
stopOldTracks: 是否停掉旧的 MediaTrack
-
更新输入媒体流
updateInputImage(options)(1.0.24版本后支持)
{
width: number;// 图片渲染高度
height: number; // 图片渲染宽度
input: string;// 图片地址
}
-
更新输入图片
async getOutput(fps:number,type:OUTPUT_TYPES, )
enum OUTPUT_TYPES {
IMAGE = 3,
MEDIA_STREAM = 4,
}
fps:设置输出的媒体流帧率,默认与输入媒体的 fps 一致
type: 3 | 4 // 3-image, 4-mediastream, 输入为图片时,输出默认为 3, 输入为非图片时,输出默认为 4
MediaStream | String
仅 Web 端提供
disable()
-
-
停用面部检测,返回未处理的原始画面,可以降低 CPU 使用率
enable()
-
-
恢复面部检测,返回美颜等特效生效的画面
stop()
-
-
暂停画面,画面静止
resume()
-
-
恢复画面,画面播放
async takePhoto()
-
{
data: Uint8Array | Uint8ClampedArray,
width: number,
height: number
}
拍照接口,返回一个包含 buffer 数据的对象,
data为 ImageData 类型
async initLocalPlayer(id)
id: string // 本地预览用 dom id
-
提供一个便捷的,预览 SDK 输出效果的接口,将 SDK 输出的媒体流以 video 的方式,在指定的 dom 容器中播放
async resetCore(input)
input: MediaStream|HTMLImageElement|String; // 输入源
-
contextlost 错误发生时调用此接口恢复
destroy()
-
-
销毁当前 SDK 实例以及相关的纹理资源

错误处理

在 error 回调返回的对象中包含错误码与错误信息以方便进行错误处理。
sdk.on('error', (error) => {
// 在 error 回调中处理错误
const {code, message} = error
...
})
错误码
含义
备注
10000001
当前浏览器环境不兼容
建议用户使用 Chrome、Firefox、Safari、微信浏览器访问
10000002
当前渲染上下文丢失
-
10000003
渲染耗时长
考虑降低视频分辨率或屏蔽功能
10000005
输入源解析错误
-
10000006
浏览器特性支持不足,可能会出现卡顿情况
建议用户使用 Chrome、Firefox、Safari、微信浏览器访问
10001101
设置特效出错
-
10001102
设置滤镜出错
-
10001103
特效强度参数不正确
-
10001104
sdk disabled 状态,无法设置特效
-
10001105
无效的特效 ID
-
10001201
调起用户摄像头失败
-
10001202
摄像头中断
-
10001203
没有获取到摄像头权限
需要开启摄像头权限,设置-隐私-相机开启
10001204
无法访问媒体设备(已授权)
找不到满足请求参数的媒体类型 或 系统错误导致设备无法被访问。
10001205
没有获取到麦克风权限
需要开启麦克风权限,设置-隐私中开启
10001206
部分浏览器可能存在 getUserMedia 接口返回的宽高与用户设置的不同
-
10004001
摄像头、麦克风权限问题需要刷新页面才能继续使用
-
20002001
缺少鉴权参数
-
20001001
鉴权失败
请确认是否创建 License,请确认签名是否正确
20001002
接口请求失败
回调会回传接口返回的数据,具体信息请参见 接口错误码
20001003
设置特效接口鉴权失败
无权访问的接口,基础版 License 无法使用高级版License 功能
20001004
signature 超时
签名超时,且重试后还是发生了错误
20001005
authorize 超时
鉴权超时,且重试后还是发生了错误
40000000
未捕获的异常
-
40000001
当前使用 SDK 版本过低,部分特效无法正确展示,请升级 SDK 版本
-
50000002
分辨率改变导致特效丢失
需要重新设置特效

警告处理

在 warning 回调返回的对象中包含警告码与警告信息。
sdk.on('warning', (warning) => {
// 在 warning 回调中处理警告
const {code, message} = warning
...
})
警告码
含义
备注
50005
检测耗时过长
动态监测,单帧耗时超过 150ms 时抛出警告,意味着此时渲染帧率达不到 10fps,有卡顿现象发生。

处理当前渲染上下文丢失

部分 PC 在长期切后台的场景可能触发处理 contextlost 错误,可以调用 ArSdk.prototype.resetCore(input: MediaStream) 恢复渲染上下文。
sdk.on('error', async (error) => {
if (error.code === 10000002) {
const newInput = await navigator.mediaDevices.getUserMedia({...})
await sdk.resetCore(newInput)
}
})

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈