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 政策
隐私协议
数据处理和安全协议
联系我们

常见问题

PDF
聚焦模式
字号
最后更新时间: 2025-08-19 10:54:27
在使用 Web 美颜特效的过程中,您可能会遇见以下问题,可以参考本文的解答。

设置美颜、贴纸等不生效,控制台一直提示“waiting for AI init”怎么处理?

SDK 为了包瘦身,进行了模块化加载处理,初始化 SDK 时候根据 module 参数配置需要加载的模块。
美颜、美妆、贴纸依赖 beautify 模块,需要设置为 true 开启,详情参考 API 文档

在 Chrome 中运行 Demo 发现画面颠倒且卡顿怎么处理?

SDK 使用 GPU 进行加速,您需要在浏览器设置中找到使用硬件加速模式并启用。

console 报错 “Failed to execute 'getContext' on 'OffscreenCanvas': The provided value 'experimental-webgl' is not a valid enum value of type OffscreenRenderingContextType”是什么原因?

通常是因为未开启浏览器硬件加速能力。

32 位浏览器使用 SDK 时页面崩溃怎么回事?

SDK 运行过程会占用一定的内存,通常不会超过 500M,推荐使用 64 位浏览器。
32 位浏览器单个标签页的内存上限通常不超过1GB​​,且会跟其他标签页共享该额度,特别是开多个 tab 页或者本身业务就比较占用内存的时候,容易出现内存不足的情况,导致浏览器页面崩溃。

现在有一个 Web 端推流直播应用,能否使用 Web 美颜特效 SDK 来美化推流画面?

可以,SDK 可以作为一个中间渲染处理器,支持多种输入和输出源,您可以参考 结合WebRTC的推流 以及 结合 TRTC 推流 轻松扩展您的线上应用,快速实现美颜特效功能。

我的签名服务会不会被频繁调用?

不会,SDK 内部针对签名有缓存机制,您也可以在自己的 getSignature 方法中自定义返回逻辑,只要符合方法签名即可。

控制台 - 制作工具中预览的效果和实际调用 SDK 时是否会有出入?

不会,SDK 使用时的渲染结果和您在制作工具中预览的效果一致,即制作时期望的预览效果即您实际生产环境中的效果。

如何使用 localhost 本地开发?

Web License 使用时会校验域名信息,所以务必确保实际运行的域名与申请 license 时填写的域名一致,否则会出现域名校验失败的错误。
但 localhost 地址除外,因为 localhost 地址默认是校验通过的,所以本地开发时可以使用 localhost,且不限制端口。

无法访问摄像头是什么原因?

用户未授权​​:首次访问时浏览器会弹出授权请求,用户拒绝后需手动开启权限。​​解决办法​​:引导用户在浏览器设置中重新授权(Chrome:设置 > 隐私和安全 > 摄像头 > 允许指定网站)。
​​非安全环境访问​​:浏览器要求 HTTPS 或本地环境(localhost/127.0.0.1),HTTP 下默认禁止访问。​​解决办法​​:部署 HTTPS 或开发时使用 localhost;调试时可通过 chrome://flags/#unsafely-treat-insecure-origin-as-secure临时允许 HTTP 地址。

快直播推流失败,打开浏览器 console 看到提示“streamurl authentication failed”?

一般是因为签名已过期,请重新计算直播推流签名,推流 URL 拼装方法请参见 自主拼装直播 URL

getEffectList 拉取素材资源时报错是什么原因?

一般是调用时机错误导致的报错,注意在 SDK created 回调或之后调用 getEffectList,此时就可以根据素材数据完成业务交互逻辑,具体使用案例请参见 最佳实践文档

Web 接入 SDK 的内置相机后,预览视频效果时出现回音?

当本地预览开启了声音并且外放时,播放的声音会被麦克风采集作为内置相机的声音源,则会造成回音问题,解决方案将预览的 video 静音。
const output = await sdk.getOutput()
const video = document.createElement('video')
document.body.appendChild(video)

video.setAttribute('muted', '')
video.volume = 0
video.srcObject = output

SDK 提示鉴权失败,接口返回401?

SDK 内部会通过参数透传的 getSignature 方法请求签名并向后台进行鉴权,当签名的时间戳过期会自动重试一次,重试失败则抛错并拦截后续的所有流程。开发者可以检查 getSignature 的逻辑,查看是否时间戳过期(5分钟有效)或者签名生成逻辑不正确。

SDK 提示“此项目不存在”怎么回事?

初始化 SDK 时提供的 license 无效导致的,排查 license 是否填写正确及是否在有效期内。另外 token 与 license 参数填写颠倒位置也会提示该错误。

帮助和支持

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

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

文档反馈