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:
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.
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.
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.
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. 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 |
| ExtInfo | No | String | System reserved field. Do not fill in. |
| 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. |
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.
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"
}
{
"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"
}
}
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.
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"
}
{
"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"
}
}
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
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. |
文档反馈