Skip to content

Real-Time Interactive Effects for Streamers ​

Updated

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:

  1. Push a source video stream to your Tencent Cloud Live (CSS) account;
  2. Call this API to create / switch / stop editing;
  3. 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 ​

CapabilityDescription
Real-time style editingApply style transfer, virtual try-on, subject replacement or background replacement to the live picture in real time
Switch while runningChange the editing type or reference image at any time without interrupting the stream
Unchanged playback URLThe 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) ​

ValueEffectMeaning of the reference image (ImageUrl)
style_transferOverall style transfer (default)Target style reference
virtual_tryonVirtual try-onGarment to put on
subject_replacementSubject replacementReplacement subject
background_replacementBackground replacementNew background

APIs ​

API (Action)Purpose
CreateAvatarEditingLiveCreate a real-time editing session
SwitchAvatarEditingSceneSwitch editing type / reference image while running
StopAvatarEditingLiveStop the session (stops billing)
DescribeAvatarEditingLiveQuery 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).

text
            ① 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
StreamSourcePriorityPlayed by default
Source streamOriginal picture you pushLowNo (but still exists, not deleted)
Edited streamRe-pushed by the platform under the same nameHigh (txPRI=1)Yes

Stream flow:

  1. 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.
  2. Subscribe and edit: the platform subscribes to the source stream and processes every frame in real time according to the editing type + reference image.
  3. 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.
  4. 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.
  5. 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 ​

ItemDescription
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 URLThe push URL of your Tencent Cloud Live account, e.g. rtmp://<push-domain>/live/{ChannelId}; push the source video here
Default playback URLThe 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 sourceSame 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 ​

StepWhat to doCheck / output
① Push sourcePush the source video to the push URL (stream ID = ChannelId) and keep it pushingThe stream is visible in Tencent Cloud Live
② Create sessionCreateAvatarEditingLive (ChannelId + ImageUrl, optional EditingType)Returns LiveId; Status is usually waiting
③ Wait for livePoll DescribeAvatarEditingLive (every 2 s recommended, with a timeout)Status=on_live and StartTime>0
④ PlayPull from the stream ID's original playback URLThe picture is now edited
⑤ Switch (optional)SwitchAvatarEditingScene; pass at least one of EditingType and ImageUrlNo need to stop; can switch multiple times
⑥ End sessionStopAvatarEditingLiveAlways call it, otherwise billing continues as live

Handle each Status while polling:

StatusMeaningAction
waiting / preparedWaiting / preparingKeep polling
on_live (with StartTime>0)Live; edited output has startedStart playback
ending / endedEnding / endedStop the flow and notify
not_existNo 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 ​

ParameterRequiredTypeDescription
ChannelIdYesStringSource stream ID of the live stream to edit
ImageUrlYesStringReference image URL (subject to content moderation)
EditingTypeNoStringEditing type, see the enum in §1; default style_transfer

Returns: LiveId (session 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
<common request parameters>

{
  "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 — query status ​

The only input is ChannelId (required). Response fields:

FieldDescription
StatusSession status: waiting / prepared / on_live / ending / ended / not_exist
LiveIdReal-time editing session ID
StartTimeGo-live time (Unix seconds, string); >0 means output has started
EndTimeEnd time; 0 if not ended yet
CreatedAtCreation time (Unix seconds, string)
Phase / CallModeInternal module session state / output mode (e.g. active / video), informational only
TraceIdTrace ID — required when reporting issues
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 — switch while running ​

ParameterRequiredTypeDescription
ChannelIdYesStringSession to switch
EditingTypeNoStringNew editing type
ImageUrlNoStringNew reference image

Pass at least one of EditingType and ImageUrl. Returns 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 — stop the session ​

The only input is ChannelId (required); returns ChannelId, LiveId, RequestId. Billing stops after the call.

json
{ "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.

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"   # 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 ChannelId and 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. If PublishCdnUrl is passed, the edited stream goes to that address instead.
  • One session per ChannelId: switch / stop / query all locate the session by ChannelId; creating again with the same ChannelId is rejected.
  • Go-live takes a moment: there are usually a few seconds of preparation between Create returning and Status=on_live.
  • Billing starts at on_live: billing runs from go-live; always call Stop when 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: ImageUrl in both Create and Switch is reviewed; violations are rejected and do not take effect.
  • Always include TraceId when reporting issues: attach the TraceId (from Describe) and the RequestId to your ticket.

7. FAQ ​

SymptomLikely cause and fix
Describe returns Status=not_existNever created / already stopped / wrong ChannelId. A successful response, not an error
Switch returns ResourceNotFoundNo active session for this ChannelId; create one before switching
Create / Switch reports ImageUrl contains prohibited contentThe reference image failed moderation; retry with a compliant image
Status stuck at waiting / preparedThe source is not pushing, or the pushed stream ID does not match ChannelId
on_live but the picture hasn't changedMake 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 screenNot yet on_live; wrong playback stream ID; or the playback domain / authentication is not configured
EndTime=0 with Status=on_liveNormal — the session is still running

Built with VitePress · Deployed on Tencent EdgeOne Pages