tencent cloud

APIs

DocumentationAPIsVideo on DemandOther APIsLiveRealTimeClip

LiveRealTimeClip

Download
Focus Mode
Font Size
Last updated: 2026-09-18 15:59:36

1. API Description

Domain name for API request: vod.intl.tencentcloudapi.com.

Live stream clipping refers to the ability for customers to select a segment from past live stream content during live streaming (when the live stream has not yet ended), generate a new video in real time (HLS format), and developers can share it instantly or store it for long-term preservation.

Tencent Cloud VOD supports two real-time clipping modes:

  • Clip solidification: Save the edited video as an independent video with its own FileId. This is suitable for long-term preservation of highlights.
  • Editing is not solidified: The edited video is attached to the live streaming recording file and has no standalone FileId. This is suitable for scenarios where highlights are shared temporarily.

Note:

  • The premise for using the live stream clipping feature is that the target live stream has the time shifting and playback (https://www.tencentcloud.com/document/product/267/32742?from_cn_redirect=1) feature enabled.
    -Live streaming Instant Editing is based on the m3u8 file generated by live recording, so its minimum editing precision is one ts slice. Second-level or more precise editing precision cannot be achieved.
    -Since stream disconnection may occur during live streaming, the actual video duration generated by editing might differ from the expected duration. For example, if you edit a live stream from 2018-09-20T10:30:00Z to 2018-09-20T10:40:00Z, and a stream disconnection occurred during this time interval, the returned media asset file duration will be less than 10 minutes. In such cases, you can perceive it through the output parameter SegmentSet.

Edit solidification

Editing solidification means saving the edited video as an independent video (with an independent FileId). Its lifecycle is not subject to any impact from the original live recorded video (even if the original recorded video is deleted, the clipping result will not be affected). It can also be transcoded, published on WeChat, or undergo other secondary processing.

For example, a complete football match may last for more than 2 hours. The customer can store the original video for 2 months for cost savings, but can specify a longer storage period for the highlight reel from live stream clipping. You can also perform additional on-demand operations on the highlight reel, such as transcoding and publishing on WeChat. In this case, you can choose the live stream clipping and persistence solution.

The advantage of solidified editing is that its lifecycle is independent of the original recorded video, allowing for separate management and long-term preservation.

Note: If solidification is specified when editing, enable reception of editing solidification event notifications through the ModifyEventConfig API. After successful solidification, you will receive a PersistenceComplete event notification. Before receiving this event notification, you should not delete or transition the live video recording to colder storage. Otherwise, playback of the video generated by editing may be abnormal.

Editing is not solidified

Editing is not solidified, meaning the result of editing (m3u8 file) shares the same TS segments with the live video recording. The newly generated video is not an independent and complete video (no standalone FileId, only a playback URL), and its valid period is consistent with that of the full live recording video. Once the live recording video is deleted, the clip will also become unplayable.

Editing is not solidified. Since the clipping result is not an independent video, it is not included in video management of on-demand media assets. For example, the total number of videos in the console does not count this clip. You also cannot separately transcode, publish on WeChat, or perform any other video processing operation on this clip.

The advantage of editing not being solidified is that the editing operation is relatively "lightweight" and will not generate additional storage overhead. However, its shortcoming is that the lifecycle is identical to the original recorded video, and it is unable to further transcode or perform other video processing.

A maximum of 100 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: LiveRealTimeClip.
Version Yes String Common Params. The value used for this API: 2018-07-17.
Region No String Common Params. This parameter is not required.
StreamId Yes String

Push stream live code.
StartTime Yes String

Start time of stream clipping. For format reference, see ISO date format description.
EndTime Yes String

End time of stream clipping. For the format, see ISO date format description.
SubAppId No Integer

On-demand application ID. For customers who activate on-demand services after December 25, 2023, this field must be filled in with the app ID when accessing resources in on-demand applications, whether it is the default application or a newly created application.
IsPersistence No Integer

Whether solidified. 0: non-permanent, 1: solidified. Default: non-permanent.
ExpireTime No String

Video storage expiry time after editing solidification. Format reference: ISO date format. Enter "9999-12-31T23:59:59Z" to indicate the video never expires. After expiry, the media file and its related resources (transcoding result, sprites, etc.) will be permanently deleted. Valid only when IsPersistence is 1. By default, videos solidified through editing never expire.
Procedure No String

Post-editing Solidified Video On-demand Task Flow Processing. For details, see upload specified task flow. Valid only when IsPersistence is 1.
ClassId No Integer

Category ID, used to categorize and manage media. You can create a category and obtain the category ID through the Create Category API.

  • Default value: 0, indicating other categories.
    • Valid only when IsPersistence is 1.
    SourceContext No String

    Source context. This is used to pass user request information. The upload completion callback returns the value of this field. The maximum length is 250 characters. Valid only when IsPersistence is 1.
    SessionContext No String

    Session context. This is used to pass user request information. When the Procedure parameter is specified, the task flow status change callback returns the value of this field. The maximum length is 1000 characters. Valid only when IsPersistence is 1.
    MetaDataRequired No Integer

    Whether to return edited video metadata. 0: not required, 1: required. By default, it is not required.
    Host No String

    The domain name added in VOD for time shift playback must be associated with a recording template and enabled for time-shift service in Cloud Streaming Services. If the first call of this interface is after 2021-01-01T00:00:00Z, this field is required.
    StreamInfo No LiveRealTimeClipStreamInfo

    Live stream information for editing:

  • Edit the original stream by default.
  • If the Type specified in StreamInfo is Transcoding, edit the live streaming transcoding stream corresponding to TemplateId.
    		•
    ExtInfo No String

    System reserved field. Do not fill in.

    3. Output Parameters

    Parameter Name Type Description
    Url String

    Edited Video Playback URL.
    FileId String

    Unique identifier of media file for post-editing solidified video.
    VodTaskId String

    Edited video task flow ID after solidification.
    MetaData MediaMetaData

    Edited video metadata.
    SegmentSet Array of LiveRealTimeClipMediaSegmentInfo

    Edited video clip information.
    RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

    4. Example

    Example1 Instant editing is not solidified

    This example shows you how to initiate instant clipping for a live stream with the live stream code record-stream and domain name example.com, with a start time of 2018-09-20T10:00:00Z and an end time of 2018-09-20T11:00:00Z, without solidification. If the live stream had a stream disconnection from 2018-09-20T10:30:00Z to 2018-09-20T10:40:00Z, lasting 10 minutes, then the output parameter SegmentSet will contain two segment information entries, and the actual duration of the trimmed video will be 50 minutes.

    Input Example

    POST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: LiveRealTimeClip
<Common request parameters>

{
    "Host": "example.com",
    "EndTime": "2018-09-20T11:00:00Z",
    "StartTime": "2018-09-20T10:00:00Z",
    "StreamId": "record-stream"
}

    Output Example

    {
    "Response": {
        "Url": "http://example.com/playlist.m3u8",
        "FileId": "",
        "VodTaskId": "",
        "MetaData": null,
        "SegmentSet": [
            {
                "StartTime": "2018-09-20T10:00:00Z",
                "EndTime": "2018-09-20T10:30:00Z"
            },
            {
                "StartTime": "2018-09-20T10:40:00Z",
                "EndTime": "2018-09-20T11:00:00Z"
            }
        ],
        "RequestId": "6ca31e3a-6b8e-xxxx-9256-fdc700064ef3"
    }
}

    Example2 Real-time clipping and solidification

    This example shows you how to initiate instant clipping for a live stream with the live stream code record-stream and domain name example.com, with a start time of 2018-09-20T12:00:00Z and an end time of 2018-09-20T13:00:00Z, and then solidify and trigger task flow processing.

    Input Example

    POST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: LiveRealTimeClip
<Common request parameters>

{
    "IsPersistence": 1,
    "Host": "example.com",
    "StartTime": "2018-09-20T12:00:00Z",
    "StreamId": "record-stream",
    "EndTime": "2018-09-20T13:00:00Z",
    "Procedure": "SomeProcedure"
}

    Output Example

    {
    "Response": {
        "Url": "http://example.com/playlist.m3u8",
        "FileId": "5285890xxxxxx199336",
        "VodTaskId": "125xxxx65-procedurev2-bffb15f07530b57bc1aabb01fac74bca",
        "MetaData": null,
        "SegmentSet": [
            {
                "StartTime": "2018-09-20T12:00:00Z",
                "EndTime": "2018-09-20T13:00:00Z"
            }
        ],
        "RequestId": "6ca31e3a-6b8e-xxxx-9256-fdc700064ef3"
    }
}

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    FailedOperation Operation failed.
    InternalError Internal error.
    InvalidParameterValue Parameter value error.
    InvalidParameterValue.ClipDuration Parameter value error: The cropping time period is too long.
    InvalidParameterValue.EndTime Parameter value error: EndTime is invalid.
    InvalidParameterValue.ExpireTime Parameter value error: Incorrect ExpireTime format.
    InvalidParameterValue.StartTime Parameter value error: StartTime is invalid.
    InvalidParameterValue.StreamIdInvalid Parameter value error: StreamId is invalid.
    UnauthorizedOperation Unauthorized operation.
    UnsupportedOperation The operation is not supported.
    Previous Topic: ExecuteFunctionNext Topic: ModifySubAppIdInfo

    Help and Support

    Was this page helpful?

    Help us improve! Rate your documentation experience in 5 mins.

    Feedback

    Search
      Enter keywords to search documentation