tencent cloud

APIs

DocumentaçãoAPIsVideo on DemandOther APIsLiveRealTimeClip

LiveRealTimeClip

Download
Modo Foco
Tamanho da Fonte
Última atualização: 2026-05-11 20:13:53

1. API Description

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

Live stream clipping refers to the process where, during a live stream (not yet ended), customers can select a segment from past live stream content to generate a new video (HLS format) in real time. Developers can instantly share it or preserve it for long-term storage.

Tencent Cloud Video on Demand (VOD) supports two instant editing modes:

  • Clip Curing: Save the edited video as an independent video with an independent FileId; applicable to scenes where highlights are ** saved for a long time **;
  • Clip not cured: The resulting video clip is attached to the live recording file and has no separate FileId; applicable to scenes where highlights are ** temporarily shared **.

Note:
-Using the live stream clipping functionality is the premise for the target live stream to enable the time-shifted playback feature.
-Live stream clipping is performed based on the m3u8 file generated by live recording generation, so its minimum editing precision is a ts slice, and second-level or more precise editing precision cannot be achieved.
-Since there may be stream interruptions during live streaming, the actual video duration generated by editing might differ from the expected duration. For example, if a live stream is edited for the time interval from 2018-09-20T10:30:00Z to 2018-09-20T10:40:00Z and stream interruption occurred during this interval, the duration of the returned media asset files will be less than 10 minutes. In such cases, you can perceive this through the output parameter SegmentSet.

Edit solidification

Clipping persistence means saving the edited video as an independent video (with an independent FileId). Its lifecycle is not subject to the original live recorded video (even if the original recorded video is deleted, the clipping result will not be impacted). It can also be post-processed, such as transcoding or publishing on WeChat.

For example: A complete football match may last for over 2 hr, and the customer can store the original video for 2 months to save costs. However, for the highlight reel from live stream clipping, you can specify longer storage. You can also perform additional on-demand operations like transcoding and publishing on WeChat separately for the highlight reel. In this case, choose the live stream clipping and solidification solution.

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

Note: If you specify solidification when editing, enable reception of editing solidification event notifications through the ModifyEventConfig API. After successful solidification, you will receive a PersistenceComplete event notification. Upon receiving this event notification, you should not perform operations like deletion or cooling on the live video recording, otherwise exceptions may occur during playback of the generated video.

Editing is not solidified

Non-solidified editing means the resulting m3u8 file shares the same TS segments with the live video recording. The generated video is not an independent and complete video (it has no standalone FileId, only a playback URL), and its valid period is consistent with the full video of the live recording. Once the live recording is deleted, it will lead to the video clip being unplayable.

Editing is not solidified. Since the clipping result is not an independent video, it will not be included in video management of on-demand media assets (for example, the total number of videos in the console will not count this video clip). It is also unable to perform any video processing operations such as transcoding or publishing on WeChat targeting this video clip separately.

The advantage of not curing clips is that they are "lightweight" and do not incur additional storage overhead. However, its shortcomings are that its life cycle is the same as that of the original recorded video, and it is impossible to further transcode and other Media Processing Service.

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. Format reference ISO date format description.
EndTime Yes String End time of stream clipping. Format reference ISO date format description.
SubAppId No Integer VOD app ID. For customers who have enabled VOD since December 25, 2023, to access resources in an VOD application (whether it is a default application or a newly created application), this field must be filled in as the application ID.
IsPersistence No Integer Whether solidified. 0 not solidified, 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) will be permanently deleted. Valid at that time only when IsPersistence is 1. The default video editing never expires.
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 via the Create Category API.
  • Default value: 0, indicating other categories.

    • Valid when IsPersistence is 1.
    SourceContext No String Source context, used for passing through user request information. The callback on upload completion will return the value of this field, up to 250 characters. Valid only when IsPersistence is 1.
    SessionContext No String Session context, used to pass through user request information. When specifying the Procedure parameter, the task flow status change callback will return the value of this field, up to 1000 characters. Valid at that time only when IsPersistence is 1.
    MetaDataRequired No Integer Whether to return edited video metadata. 0: not required, 1: required. By default, does not need.
    Host No String The domain name added in VOD for time shift playback must be associated with a recording template and have the time-shift service enabled in Cloud Streaming Services (https://www.tencentcloud.com/document/product/266/52220?from_cn_redirect=1#.E6.AD.A5.E9.AA.A43.EF.BC.9A.E5.85.B3.E8.81.94.E5.BD.95.E5.88.B6.E6.A8.A1.E6.9D.BF.3Ca-id.3D.22step3.22.3E.3C.2Fa.3E). If the first call time of this interface is after 2021-01-01T00:00:00Z, this field is a required field.
    StreamInfo No LiveRealTimeClipStreamInfo Edited live stream information
  • Default video editing for the original stream.
  • When 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
    Note: This field may return null, indicating that no valid values can be obtained.
    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 Real-time editing is not solidified

    Initiate instant clipping for the live stream with the live stream code record-stream and domain name example.com, with the start time 2018-09-20T10:00:00Z and end time 2018-09-20T11:00:00Z, and no solidification. Assume the live stream had a stream interruption from 2018-09-20T10:30:00Z to 2018-09-20T10:40:00Z, with a duration of 10 minutes, so the output parameter SegmentSet will contain two segment information, and the actual duration of the trimmed video can be obtained as 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

    Initiate instant clipping for the live stream named record-stream and domain example.com, with start time 2018-09-20T12:00:00Z and end time 2018-09-20T13:00:00Z, then perform solidification 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 Incorrect parameter value.
    InvalidParameterValue.ClipDuration Incorrect parameter value: the clipping duration is too long.
    InvalidParameterValue.EndTime Incorrect parameter value: invalid EndTime.
    InvalidParameterValue.ExpireTime Incorrect parameter value: incorrect ExpireTime format.
    InvalidParameterValue.StartTime Incorrect parameter value: invalid StartTime.
    InvalidParameterValue.StreamIdInvalid Incorrect parameter value: invalid StreamId.
    UnauthorizedOperation Unauthorized operation.
    UnsupportedOperation Unsupported operation.
    Anterior: ExecuteFunctionPróximo: ModifySubAppIdInfo

    Ajuda e Suporte

    Esta página foi útil?

    comentários