Real-Time Interactive Effects for Streamers
Closed beta
This feature is currently in closed beta. To use it, please contact the business and product teams first to have it enabled.
Real-Time Interactive Effects for Streamers applies AI edits in real time to a video stream that is already live — style transfer / virtual try-on / subject replacement / background replacement — and outputs an edited live stream. You can switch the effect at any point during the broadcast without interrupting the stream.
You only need to do three things:
- Push a source video stream to your Tencent Cloud Live (CSS) account;
- Call this API to create / switch / stop editing;
- Pull from the original playback URL to watch.
Real-time editing, transcoding and distribution in between are handled by the platform. The edited result is pushed back to your Tencent Cloud Live under the same stream ID with a higher push priority, so the playback URL does not change.
Endpoint
All APIs in this guide use the request domain live.intl.tencentcloudapi.com (Tencent Cloud Live, international site), API version 2018-08-01, signature method TC3-HMAC-SHA256 (service name live). Region is not required.
1. Capabilities
| Capability | Description |
|---|---|
| Real-time style editing | Apply style transfer, virtual try-on, subject replacement or background replacement to the live picture in real time |
| Switch while running | Change the editing type or reference image at any time without interrupting the stream |
| Unchanged playback URL | The result is re-pushed to your Tencent Cloud Live under the same stream ID, so the source stream's original playback URL shows the edited picture — no stream switching, no dedicated SDK |
Editing types (EditingType)
| Value | Effect | Meaning of the reference image (ImageUrl) |
|---|---|---|
style_transfer | Overall style transfer (default) | Target style reference |
virtual_tryon | Virtual try-on | Garment to put on |
subject_replacement | Subject replacement | Replacement subject |
background_replacement | Background replacement | New background |
APIs
| API (Action) | Purpose |
|---|---|
CreateAvatarEditingLive | Create a real-time editing session |
SwitchAvatarEditingScene | Switch editing type / reference image while running |
StopAvatarEditingLive | Stop the session (stops billing) |
DescribeAvatarEditingLive | Query session status |
All four APIs have a default rate limit of 20 requests/second.
2. Architecture and Data Flow
Key point: on Tencent Cloud Live, two streams coexist under the same stream ID (= ChannelId).
① Push source (stream ID = ChannelId)
Encoder ──────────────────────────────▶ Tencent Cloud Live ◀── ③ Edited result re-pushed, same name (txPRI=1, high priority)
│ ▲ │
│ └── ② Subscribe source ─▶ Real-time editing platform
│ ▲
▼ │ create / switch / stop / query
Player (high priority by default → edited picture) Your backend| Stream | Source | Priority | Played by default |
|---|---|---|---|
| Source stream | Original picture you push | Low | No (but still exists, not deleted) |
| Edited stream | Re-pushed by the platform under the same name | High (txPRI=1) | Yes |
Stream flow:
- Push the source: push the source video to the push URL of your Tencent Cloud Live account, with stream ID = your custom
ChannelId. At this point only this one stream exists. - Subscribe and edit: the platform subscribes to the source stream and processes every frame in real time according to the editing type + reference image.
- Same-name, high-priority re-push: the platform pushes the edited picture back under the same stream ID with a higher push priority (
txPRI=1). Two same-name streams now coexist. - Edited stream plays by default: when playing a same-name stream, the CDN picks the highest-priority one, so the regular playback URL returns the edited picture — URL unchanged, no new stream name.
- Source is still available: the original source stream is neither deleted nor overwritten. To watch the unedited picture, pull the low-priority stream using Tencent Cloud Live's push-priority / specific-stream parameters (see the Tencent Cloud Live console and docs for the exact parameters).
From the user's point of view: the same live stream gets effects added in real time, and the original is always available — play with the stream ID you push (effects on by default).
2.1 URLs and stream ID
| Item | Description |
|---|---|
Stream ID (ChannelId) | Your custom session identifier (unique within an app). Used for pushing the source and for create / switch / stop / query. The source and edited streams share this ID and are distinguished by push priority |
| Push URL | The push URL of your Tencent Cloud Live account, e.g. rtmp://<push-domain>/live/{ChannelId}; push the source video here |
| Default playback URL | The regular playback URL for this stream ID (FLV / HLS / RTMP). Defaults to the high-priority stream → after on_live you get the edited picture, URL unchanged |
| Watch the source | Same playback URL + Tencent Cloud Live's priority / specific-stream parameters → pulls the low-priority original source. The source always exists and is unaffected by editing |
| Push elsewhere (optional) | To push the result to a different address instead of same-name re-push, pass PublishCdnUrl at creation with your own RTMP URL. The source and edited streams then have different stream IDs and no priority coexistence |
About PublishCdnUrl
PublishCdnUrl comes from the customer user manual and is not yet formally listed among the API input parameters. Confirm with your solutions architect that it is enabled for your account before using it.
3. Call Flow
| Step | What to do | Check / output |
|---|---|---|
| ① Push source | Push the source video to the push URL (stream ID = ChannelId) and keep it pushing | The stream is visible in Tencent Cloud Live |
| ② Create session | CreateAvatarEditingLive (ChannelId + ImageUrl, optional EditingType) | Returns LiveId; Status is usually waiting |
| ③ Wait for live | Poll DescribeAvatarEditingLive (every 2 s recommended, with a timeout) | Status=on_live and StartTime>0 |
| ④ Play | Pull from the stream ID's original playback URL | The picture is now edited |
| ⑤ Switch (optional) | SwitchAvatarEditingScene; pass at least one of EditingType and ImageUrl | No need to stop; can switch multiple times |
| ⑥ End session | StopAvatarEditingLive | Always call it, otherwise billing continues as live |
Handle each Status while polling:
Status | Meaning | Action |
|---|---|---|
waiting / prepared | Waiting / preparing | Keep polling |
on_live (with StartTime>0) | Live; edited output has started | Start playback |
ending / ended | Ending / ended | Stop the flow and notify |
not_exist | No session for this ChannelId (never created or already stopped) | A normal successful response, not an error |
After stopping, the edited stream disconnects; playback failures at that point are expected.
4. API Reference
Common parameters: Action = the API name, Version = 2018-08-01, Region omitted; the rest are the standard Tencent Cloud API 3.0 common parameters (signature, timestamp, etc.).
4.1 CreateAvatarEditingLive — create a session
| Parameter | Required | Type | Description |
|---|---|---|---|
ChannelId | Yes | String | Source stream ID of the live stream to edit |
ImageUrl | Yes | String | Reference image URL (subject to content moderation) |
EditingType | No | String | Editing type, see the enum in §1; default style_transfer |
Returns: LiveId (session 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
<common request parameters>
{
"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 — query status
The only input is ChannelId (required). Response fields:
| Field | Description |
|---|---|
Status | Session status: waiting / prepared / on_live / ending / ended / not_exist |
LiveId | Real-time editing session ID |
StartTime | Go-live time (Unix seconds, string); >0 means output has started |
EndTime | End time; 0 if not ended yet |
CreatedAt | Creation time (Unix seconds, string) |
Phase / CallMode | Internal module session state / output mode (e.g. active / video), informational only |
TraceId | Trace ID — required when reporting issues |
{
"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 — switch while running
| Parameter | Required | Type | Description |
|---|---|---|---|
ChannelId | Yes | String | Session to switch |
EditingType | No | String | New editing type |
ImageUrl | No | String | New reference image |
Pass at least one of EditingType and ImageUrl. Returns 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 — stop the session
The only input is ChannelId (required); returns ChannelId, LiveId, RequestId. Billing stops after the call.
{ "ChannelId": "editing_demo_01" }5. End-to-End Example (Python SDK)
Requires a recent tencentcloud-sdk-python (which includes the four APIs above). Inject credentials through environment variables; never hard-code them.
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" # must match the stream ID used when pushing the source
# ② Create (prerequisite: the source stream is pushing continuously)
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"])
# ③ Poll until live (every 2 s, up to 60 s)
deadline = time.time() + 60
while time.time() < deadline:
d = call("DescribeAvatarEditingLive", {"ChannelId": CHANNEL})
if d["Status"] == "on_live" and int(d["StartTime"]) > 0:
print("Live, TraceId:", d["TraceId"]); break
if d["Status"] in ("ending", "ended", "not_exist"):
raise RuntimeError(f"Session unavailable: {d['Status']}")
time.sleep(2)
else:
raise TimeoutError("Timed out waiting for live: check the source is pushing and the stream ID matches ChannelId")
# ④ The original playback URL now shows the edited picture
# ⑤ Switch while running (optional)
call("SwitchAvatarEditingScene", {"ChannelId": CHANNEL,
"EditingType": "background_replacement",
"ImageUrl": "https://example-1250000000.cos.ap-singapore.myqcloud.com/ref/studio-bg.png"})
# ⑥ End (always call it to stop billing)
call("StopAvatarEditingLive", {"ChannelId": CHANNEL})The
ChannelIdand COS URLs in the examples are sample values — replace them with your own stream ID and reference image URLs.
6. Key Caveats
- Push the source before creating: make sure the source stream is pushing continuously (stream ID =
ChannelId) before creating a session; otherwise there is nothing to edit. - Playback URL unchanged, two streams coexist: the result is re-pushed under the same stream ID with a higher priority (
txPRI=1) alongside the original; playback picks the high-priority stream by default. IfPublishCdnUrlis passed, the edited stream goes to that address instead. - One session per
ChannelId: switch / stop / query all locate the session byChannelId; creating again with the sameChannelIdis rejected. - Go-live takes a moment: there are usually a few seconds of preparation between
Createreturning andStatus=on_live. - Billing starts at
on_live: billing runs from go-live; always callStopwhen done to avoid idle charges. - Switching is asynchronous — don't switch rapidly: judge success by the picture; each switch takes a few seconds, and rapid consecutive switches override one another.
- Reference images are moderated:
ImageUrlin bothCreateandSwitchis reviewed; violations are rejected and do not take effect. - Always include
TraceIdwhen reporting issues: attach theTraceId(fromDescribe) and theRequestIdto your ticket.
7. FAQ
| Symptom | Likely cause and fix |
|---|---|
Describe returns Status=not_exist | Never created / already stopped / wrong ChannelId. A successful response, not an error |
Switch returns ResourceNotFound | No active session for this ChannelId; create one before switching |
Create / Switch reports ImageUrl contains prohibited content | The reference image failed moderation; retry with a compliant image |
Status stuck at waiting / prepared | The source is not pushing, or the pushed stream ID does not match ChannelId |
on_live but the picture hasn't changed | Make sure you are pulling the playback URL of the correct stream ID; wait a few seconds for the high-priority stream to take over; or reconnect the player to clear its cache |
| No picture / black screen | Not yet on_live; wrong playback stream ID; or the playback domain / authentication is not configured |
EndTime=0 with Status=on_live | Normal — the session is still running |