跳到内容

主播实时互动特效 ​

更新时间

内测中

该功能目前还在内测阶段,如需使用,请先联系商务及产品团队开通。

主播实时互动特效对一路正在直播的视频源流做实时 AI 编辑 —— 风格迁移 / 虚拟试穿 / 主体替换 / 背景替换,输出一路编辑后的直播流。直播过程中可以随时切换编辑效果,无需中断直播。

接入方只需要做三件事:

  1. 推一路源视频流到自己的腾讯云直播;
  2. 调用本 API 创建 / 切换 / 停止编辑;
  3. 用原播放地址拉流观看。

中间的实时编辑、流转码与分发由平台自动完成。编辑结果会以相同的流 id、更高的推流优先级推回你的腾讯云直播,播放地址不变。

请求端点

本文所有接口的请求域名均为 live.intl.tencentcloudapi.com(云直播国际站),接口版本 2018-08-01,签名方法 TC3-HMAC-SHA256(服务名 live)。Region 不需要传。

1. 能力概述 ​

能力说明
实时风格编辑对直播画面实时应用风格迁移、虚拟试穿、主体替换、背景替换
运行中切换直播不中断,随时更换编辑类型或参考图
播放地址不变编辑结果以相同流 id 回推到你的腾讯云直播,用源流原本的播放地址即可看到编辑后画面;无需换流、无需集成任何专用 SDK

编辑类型(EditingType) ​

取值效果参考图(ImageUrl)的含义
style_transfer整体风格迁移(默认值)目标画风参考
virtual_tryon虚拟试穿要换上的服装
subject_replacement主体替换替换后的主体形象
background_replacement背景替换新背景

接口清单 ​

接口(Action)作用
CreateAvatarEditingLive创建实时编辑会话
SwitchAvatarEditingScene运行中切换编辑类型 / 换参考图
StopAvatarEditingLive停止编辑会话(停止计费)
DescribeAvatarEditingLive查询会话状态

四个接口的默认频率限制均为 20 次/秒。

2. 架构与数据流 ​

关键点:腾讯云直播上同一个流 id(= ChannelId)并存两路流。

text
            ① 推源流(流 id = ChannelId)
 推流端 ───────────────────────────────▶ 腾讯云直播 ◀──── ③ 编辑结果同名回推(txPRI=1,高优先级)
                                          │   ▲                         │
                                          │   └── ② 订阅源流 ──▶ 实时编辑平台
                                          │                             ▲
                                          ▼                             │ 创建 / 切换 / 停止 / 查询
                                 播放器(默认播高优先级 → 编辑画面)    你的应用后端
流来源优先级默认是否被播放
源流你推上来的原始画面低否(但仍然存在、未被删除)
编辑结果流平台编辑后以同名回推高(txPRI=1)是

流走向:

  1. 推源流:把源视频推到你腾讯云直播账号的推流地址,流 id = 自定义的 ChannelId。此时云直播上只有这一路。
  2. 订阅编辑:平台订阅该源流,按设置的编辑类型 + 参考图实时处理每一帧。
  3. 同名高优先级回推:平台把编辑后的画面以相同流 id、更高推流优先级(txPRI=1)推回腾讯云直播。此时同时存在两路同名流。
  4. 默认播编辑流:CDN 播放同名流时默认取优先级最高的那路,所以用常规播放地址拉到的就是编辑后画面 —— 地址不变、无需拼新流名。
  5. 源流仍可取:原始源流没有被删除或覆盖。需要看原始画面时,可按腾讯云直播的推流优先级 / 指定流参数拉取低优先级那路(具体参数以腾讯云直播控制台与文档为准)。

从使用者视角看:同一路直播流被实时加了特效,且随时能回看原片 —— 推什么流 id,就用什么流 id 播(默认带特效)。

2.1 地址与流 id ​

项说明
流 id(ChannelId)自定义的会话标识(同一应用内唯一)。推源流用它,创建 / 切换 / 停止 / 查询也用它。源流与编辑结果流共用同一个流 id,靠推流优先级区分
推流地址你腾讯云直播账号的推流地址,形如 rtmp://<推流域名>/live/{ChannelId},源视频推到这里
默认播放地址该流 id 的常规播放地址(FLV / HLS / RTMP 皆可)。默认取高优先级那路 → on_live 后拉到的即编辑后画面,地址不变
回看源画面同一播放地址 + 腾讯云直播的指定优先级 / 指定流参数 → 拉到低优先级的原始源流。源流始终存在,不受编辑影响
推到其它地址(可选)若希望编辑结果推到另一个地址(而非同名回推),创建时传 PublishCdnUrl 指定你自己的 RTMP 地址。此时源流与编辑流分属两个流 id,不存在优先级并存关系

关于 PublishCdnUrl

PublishCdnUrl 来自客户版使用手册,当前接口入参中尚未正式列出。如需使用,请先与商务架构师确认是否已对你的账号开放。

3. 调用流程 ​

步骤做什么判据 / 产出
① 推源流把源视频推到推流地址(流 id = ChannelId),保持持续推送云直播上能看到该流
② 创建会话CreateAvatarEditingLive(ChannelId + ImageUrl,可选 EditingType)返回 LiveId,Status 通常为 waiting
③ 等待开播轮询 DescribeAvatarEditingLive(建议每 2 秒一次,设超时上限)Status=on_live 且 StartTime>0
④ 拉流播放用该流 id 原本的播放地址拉流画面已是编辑后效果
⑤ 运行中切换(可选)SwitchAvatarEditingScene,EditingType 与 ImageUrl 至少传一个无需停播,可多次切换
⑥ 结束会话StopAvatarEditingLive务必调用,否则持续按开播状态计费

轮询时按 Status 分支处理:

Status含义处理
waiting / prepared等待中 / 准备中继续轮询
on_live(且 StartTime>0)直播中,编辑已开始输出进入拉流播放
ending / ended结束中 / 已结束停止流程并提示
not_exist该 ChannelId 当前没有会话(未创建或已停止)正常的成功返回,不是错误

停止后结果流断开,播放器拉流失败属正常现象。

4. 接口说明 ​

公共参数:Action 取对应接口名,Version = 2018-08-01,Region 不传;其余为腾讯云 API 3.0 标准公共参数(签名、时间戳等)。

4.1 CreateAvatarEditingLive — 创建会话 ​

参数必选类型说明
ChannelId是String待编辑直播流的源流 id
ImageUrl是String编辑参考图 URL(会送合规审核)
EditingType否String编辑类型,见 §1 枚举;默认 style_transfer

返回:LiveId(会话 ID)、Status、ChannelId、RequestId。

http
POST / HTTP/1.1
Host: live.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateAvatarEditingLive
X-TC-Version: 2018-08-01
<公共请求参数>

{
  "ChannelId": "editing_demo_01",
  "ImageUrl": "https://example-1250000000.cos.ap-singapore.myqcloud.com/ref/outfit.png",
  "EditingType": "virtual_tryon"
}
json
{
  "Response": {
    "ChannelId": "editing_demo_01",
    "LiveId": "1008224608114978816",
    "Status": "waiting",
    "RequestId": "0c104bce-d2f4-4363-b463-cf46fab5519e"
  }
}

4.2 DescribeAvatarEditingLive — 查询状态 ​

入参只有 ChannelId(必选)。返回字段:

字段说明
Status会话状态:waiting / prepared / on_live / ending / ended / not_exist
LiveId实时编辑会话 ID
StartTime开播时刻(Unix 秒,字符串);>0 表示已开始输出
EndTime结束时间;未结束时为 0
CreatedAt创建时间(Unix 秒,字符串)
Phase / CallMode内部模块会话状态 / 输出模式(如 active / video),仅供参考
TraceId跟踪 ID,报障必带
json
{
  "Response": {
    "CallMode": "video",
    "ChannelId": "editing_demo_01",
    "CreatedAt": "1792050995",
    "EndTime": "0",
    "LiveId": "1008224608114978816",
    "Phase": "active",
    "StartTime": "1792050998",
    "Status": "on_live",
    "TraceId": "82e7b0074f492b41ca0152ae7e608ef3",
    "RequestId": "e568960c-4894-4670-9e30-e3242f0ee5da"
  }
}

4.3 SwitchAvatarEditingScene — 运行中切换 ​

参数必选类型说明
ChannelId是String要切换的会话
EditingType否String新的编辑类型
ImageUrl否String新的参考图

EditingType 与 ImageUrl 至少传一个。返回 ChannelId、LiveId、RequestId。

json
{
  "ChannelId": "editing_demo_01",
  "EditingType": "background_replacement",
  "ImageUrl": "https://example-1250000000.cos.ap-singapore.myqcloud.com/ref/studio-bg.png"
}

4.4 StopAvatarEditingLive — 停止会话 ​

入参只有 ChannelId(必选),返回 ChannelId、LiveId、RequestId。调用后停止计费。

json
{ "ChannelId": "editing_demo_01" }

5. 完整调用示例(Python SDK) ​

需要 tencentcloud-sdk-python 的较新版本(已包含上述四个接口)。密钥通过环境变量注入,不要写进代码。

python
import json, os, time
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.live.v20180801 import live_client, models

cred = credential.Credential(os.environ["TENCENTCLOUD_SECRET_ID"],
                             os.environ["TENCENTCLOUD_SECRET_KEY"])
http = HttpProfile(endpoint="live.intl.tencentcloudapi.com")
client = live_client.LiveClient(cred, "", ClientProfile(httpProfile=http))

def call(action, params):
    req = getattr(models, f"{action}Request")()
    req.from_json_string(json.dumps(params))
    resp = getattr(client, action)(req)
    return json.loads(resp.to_json_string())

CHANNEL = "editing_demo_01"   # 与推源流时的流 id 一致

# ② 创建(前提:源流已在持续推送)
r = call("CreateAvatarEditingLive", {
    "ChannelId": CHANNEL,
    "ImageUrl": "https://example-1250000000.cos.ap-singapore.myqcloud.com/ref/outfit.png",
    "EditingType": "virtual_tryon",
})
print("LiveId:", r["LiveId"], "Status:", r["Status"])

# ③ 轮询直到开播(每 2 秒,最多 60 秒)
deadline = time.time() + 60
while time.time() < deadline:
    d = call("DescribeAvatarEditingLive", {"ChannelId": CHANNEL})
    if d["Status"] == "on_live" and int(d["StartTime"]) > 0:
        print("已开播,TraceId:", d["TraceId"]); break
    if d["Status"] in ("ending", "ended", "not_exist"):
        raise RuntimeError(f"会话不可用:{d['Status']}")
    time.sleep(2)
else:
    raise TimeoutError("等待开播超时:检查源流是否在推、流 id 是否与 ChannelId 一致")

# ④ 此时用原播放地址拉流即可看到编辑后画面

# ⑤ 运行中切换(可选)
call("SwitchAvatarEditingScene", {"ChannelId": CHANNEL,
                                  "EditingType": "background_replacement",
                                  "ImageUrl": "https://example-1250000000.cos.ap-singapore.myqcloud.com/ref/studio-bg.png"})

# ⑥ 结束(务必调用,停止计费)
call("StopAvatarEditingLive", {"ChannelId": CHANNEL})

示例中的 ChannelId、COS 地址均为示例值,请替换为你自己的流 id 与参考图地址。

6. 关键注意事项 ​

  • 先推源流再创建:创建前确保源视频流已在持续推送(流 id = ChannelId),否则没有可编辑的画面。
  • 播放地址不变,两路流并存:编辑结果以相同流 id、更高优先级(txPRI=1)回推,与原始源流并存;默认播放取高优先级。传了 PublishCdnUrl 则编辑流改推到指定地址。
  • 一个 ChannelId 一路会话:切换 / 停止 / 查询都以 ChannelId 定位会话;同一 ChannelId 重复创建会被拒绝。
  • 开播有延迟:Create 返回后到 Status=on_live 通常有数秒准备耗时。
  • on_live 才计费:从开播开始计费,用完务必调 Stop,避免空跑扣费。
  • 切换异步、勿高频:切换是否生效以画面为准,单次生效需数秒,频繁连切会相互覆盖。
  • 参考图合规审核:Create / Switch 的 ImageUrl 都会送审,命中违规直接拒绝、不生效。
  • 报障必带 TraceId:工单中请附上 TraceId(来自 Describe)与 RequestId。

7. 常见问题 ​

现象可能原因与处理
Describe 返回 Status=not_exist未创建 / 已停止 / ChannelId 写错。属成功返回,非报错
Switch 返回 ResourceNotFound该 ChannelId 没有进行中的会话,切换前需先创建
Create / Switch 提示 ImageUrl contains prohibited content参考图命中合规审核,换一张合规图重试
Status 长期停在 waiting / prepared源流未推送,或推流的流 id 与 ChannelId 不一致
已 on_live 但画面没变确认拉的是正确流 id 的播放地址;或等数秒让高优先级流接管;或播放器有缓存需重连
拉不到画面 / 播放黑屏尚未 on_live;或播放流 id 写错;或播放域名 / 鉴权未配置
EndTime=0 且 Status=on_live正常,会话进行中、尚未结束

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages