确认数字人是否支持动态背景切换

先登录百度智能云控制台，找到“百度一镜数字人”服务，然后点开你当前使用的数字人形象详情页。在“能力支持”那一栏，仔细看看有没有标注“动态场景切换”或“多机位多背景实时切镜”。如果没显示这个能力，那这个形象就不支持。注意，不支持的形象即使调用接口也会静默失败，没有报错提示。所以，一定要换成带“直播切镜”标签的3D数字人形象，这是硬性要求。

准备可切换的背景资源包

背景图不能随便用，得按规范来。首先，进入“组件商店”搜索“虚拟背景素材包”，下载解压后，确保里面至少有三张符合规范的PNG或WebP格式背景图。单张尺寸得和数字人输出分辨率一致，推荐1920×1080，而且透明通道不能有毛边。所有图片统一重命名为英文加数字的组合，比如bg_office_01.png、bg_lab_02.png、bg_shop_03.png，中文命名会导致SDK加载失败。然后，把这些图上传到你的自有服务器或CDN，获取每个图的可公开访问URL，必须是以https://开头，并且CORS配置了allow-origin: *，否则跨域问题会卡住。

通过推流指令触发背景切换

有两种方法可以触发切换。方法一：通过HTTP POST调用切镜API。向这个地址发送请求：https://open.xiling.baidu.com/api/digitalhuman/open/v1/live/scene/switch。Header里必须带上Content-Type: application/json和X-Bce-Access-Token: 【你的有效access_token】。Body是JSON格式，示例：{"task_id":"live_20260715_abc123","scene_url":"https://cdn.example.com/bg_lab_02.png","fade_duration":300}。其中fade_duration单位是毫秒，范围100到1000，低于100会卡顿，高于1000切换就太慢了。

方法二：在H5 iframe内注入JS指令，这仅限H5版SDK。首先确保iframe加载完成，监听window.addEventListener('message', ...)中收到type==='ready'事件后，执行：document.getElementById('myIframe').contentWindow.postMessage({type:'switchScene',url:'https://cdn.example.com/bg_shop_03.png',duration:500},'https://open.xiling.baidu.com')。注意，postMessage的target origin必须严格匹配iframe src域名，写成'*'会触发浏览器安全拦截，千万别写错。

验证切换是否生效

切换后需要验证一下。第一步，在推流端OBS或自研推流器里，打开预览窗口，观察数字人画面是否在300毫秒内开始淡出原背景、淡入新背景。第二步，如果使用RTMP推流，登录百度一镜控制台，进入“直播监控”页，找到对应流ID，点击“查看日志”，筛选关键词scene_switch_success，确认返回status=200且scene_url与请求一致。第三步，用手机扫码观看实际推流画面，不要只依赖本地预览，因为部分显卡驱动在本地渲染时会跳过背景合成步骤，导致本地看起来没问题，但实际推流画面没变化。