主播实时互动特效
内测中
该功能目前还在内测阶段,如需使用,请先联系商务及产品团队开通。
主播实时互动特效对一路正在直播的视频源流做实时 AI 编辑 —— 风格迁移 / 虚拟试穿 / 主体替换 / 背景替换,输出一路编辑后的直播流。直播过程中可以随时切换编辑效果,无需中断直播。
接入方只需要做三件事:
- 推一路源视频流到自己的腾讯云直播;
- 调用本 API 创建 / 切换 / 停止编辑;
- 用原播放地址拉流观看。
中间的实时编辑、流转码与分发由平台自动完成。编辑结果会以相同的流 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)并存两路流。
① 推源流(流 id = ChannelId)
推流端 ───────────────────────────────▶ 腾讯云直播 ◀──── ③ 编辑结果同名回推(txPRI=1,高优先级)
│ ▲ │
│ └── ② 订阅源流 ──▶ 实时编辑平台
│ ▲
▼ │ 创建 / 切换 / 停止 / 查询
播放器(默认播高优先级 → 编辑画面) 你的应用后端| 流 | 来源 | 优先级 | 默认是否被播放 |
|---|---|---|---|
| 源流 | 你推上来的原始画面 | 低 | 否(但仍然存在、未被删除) |
| 编辑结果流 | 平台编辑后以同名回推 | 高(txPRI=1) | 是 |
流走向:
- 推源流:把源视频推到你腾讯云直播账号的推流地址,流 id = 自定义的
ChannelId。此时云直播上只有这一路。 - 订阅编辑:平台订阅该源流,按设置的编辑类型 + 参考图实时处理每一帧。
- 同名高优先级回推:平台把编辑后的画面以相同流 id、更高推流优先级(
txPRI=1)推回腾讯云直播。此时同时存在两路同名流。 - 默认播编辑流:CDN 播放同名流时默认取优先级最高的那路,所以用常规播放地址拉到的就是编辑后画面 —— 地址不变、无需拼新流名。
- 源流仍可取:原始源流没有被删除或覆盖。需要看原始画面时,可按腾讯云直播的推流优先级 / 指定流参数拉取低优先级那路(具体参数以腾讯云直播控制台与文档为准)。
从使用者视角看:同一路直播流被实时加了特效,且随时能回看原片 —— 推什么流 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。
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"
}{
"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,报障必带 |
{
"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。
{
"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。调用后停止计费。
{ "ChannelId": "editing_demo_01" }5. 完整调用示例(Python SDK)
需要 tencentcloud-sdk-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 | 正常,会话进行中、尚未结束 |