CreateLiveRecord

Last updated: 2020-03-20 17:23:24

1. API Description

Domain name for API request: live.tencentcloudapi.com.

  • Prerequisites

    1. Recording files are stored on the VOD platform, so if you need to use the recording feature, you must first activate the VOD service.
    2. After the recording files are stored, applicable fees (including storage fees and downstream playback traffic fees) will be charged according to the VOD billing mode.
  • Mode description
    This API supports two recording modes:

    1. Scheduled recording mode (default mode).
      The start time and end time need to be passed in, and the recording task will automatically start and end based on the time parameters.
    2. Real-time video recording mode.
      The start time passed in will be ignored, and recording will be started immediately after the recording task is created. The recording duration can be up to 30 minutes. If the end time passed in is more than 30 minutes after the current time, it will be counted as 30 minutes. Real-time video recording is mainly used for recording highlight scenes, and you are recommended to keep the duration within 5 minutes.
  • Precautions

    1. The API call timeout period should be set to more than 3 seconds; otherwise, retries and frequent calls may result in repeated recording tasks.
    2. Subject to the audio and video file formats (FLV/MP4/HLS), the video codec of H.264 and audio codec of AAC are supported.
    3. In order to avoid malicious or non-subjective frequent API requests, the maximum number of tasks that can be created in scheduled recording mode is limited: up to 4,000 tasks can be created per day (excluding deleted ones), and up to 400 ones can run concurrently. If you need a higher upper limit, please submit a ticket for application.

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

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 parameter. The value used for this API: CreateLiveRecord.
Version Yes String Common parameter. The value used for this API: 2018-08-01.
Region No String Common parameter. This parameter is not required for this API.
StreamName Yes String Stream name.
AppName No String Push path, which is the same as the AppName in push and playback addresses and is "live" by default.
DomainName No String Push domain name. This parameter must be set for multi-domain name push.
StartTime No String Recording start time, which is China standard time and should be URL-encoded (RFC3986). For example, the encoding of 2017-01-01 10:10:01 is 2017-01-01+10%3a10%3a01.
In scheduled recording mode, this field must be set; in real-time video recording mode, this field is ignored.
EndTime No String Recording end time, which is China standard time and should be URL-encoded (RFC3986). For example, the encoding of 2017-01-01 10:30:01 is 2017-01-01+10%3a30%3a01.
In scheduled recording mode, this field must be set; in real-time video recording mode, this field is optional. If the recording is set to real-time video recording mode through the Highlight parameter, the end time set should not be more than 30 minutes after the current time. If the set end time is more than 30 minutes after the current time, earlier than the current time or left blank, the actual end time will be 30 minutes after the current time.
RecordType No String Recording type.
"video": Audio-video recording (default).
"audio": audio recording.
In both scheduled and real-time video recording modes, this parameter is valid and is not case sensitive.
FileFormat No String Recording file format. Valid values:
"flv" (default), "hls", "mp4", "aac", "mp3".
In both scheduled and real-time video recording modes, this parameter is valid and is not case sensitive.
Highlight No Integer Mark for enabling real-time video recording mode.
0: Real-time video recording mode is not enabled, i.e., the scheduled recording mode is used (default). See Sample 1.
1: Real-time video recording mode is enabled. See Sample 2.
MixStream No Integer Mark for enabling A+B=C mixed stream recording.
0: A+B=C mixed stream recording is not enabled (default).
1: A+B=C mixed stream recording is enabled.
In both scheduled and real-time video recording modes, this parameter is valid.
StreamParam No String Recording stream parameter. The following parameters are supported currently:
record_interval: Recording interval in seconds. Value range: 1,800–7,200
storage_time: Recording file duration in seconds
eg. record_interval=3600&storage_time=2592000
Note: The parameter needs url encode.
In both scheduled and real-time video recording modes, this parameter is valid.

3. Output Parameters

Parameter Name Type Description
TaskId Integer Task ID, which uniquely identifies the recording task globally.
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Creating a scheduled recording task

This example shows you how to create a scheduled recording task suitable for scenarios where the start time and end time of recording are fixed, such as training courses, business events, shows, and performances.

Input Example

https://live.tencentcloudapi.com/?Action=CreateLiveRecord
&AppName=live
&DomainName=5000.live.push.com
&StreamName=livetest
&StartTime=2018-09-11+12%3a04%3a01
&EndTime=2018-09-11+12%3a08%3a01
&<common request parameters>

Output Example

{
  "Response": {
    "RequestId": "eac6b301-a322-493a-8e36-83b295459397",
    "TaskId": 1234567
  }
}

Example2 Creating a real-time recording task

This example shows you how to create a real-time recording task suitable for scenarios where recording needs to start immediately to record certain video content or meet temporary needs during live streaming. (EndTime is used to specify the recording end time, and the recording can last for up to 30 minutes.)

Input Example

https://live.tencentcloudapi.com/?Action=CreateLiveRecord
&AppName=live
&DomainName=5000.live.push.com
&StreamName=livetest
&Highlight=1
&EndTime=2018-09-11+12%3a08%3a01
&<common request parameters>

Output Example

{
  "Response": {
    "RequestId": "eac6b301-a322-493a-8e36-83b295459397",
    "TaskId": 1234567
  }
}

5. Developer Resources

API Explorer

This tool allows online call, signature authentication, SDK code generation and quick search of APIs to greatly improve the efficiency of using TencentCloud APIs.

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
InternalError Internal error.
InternalError.GetConfigError Error getting the configuration.
InternalError.NetworkError Internal network error.
InvalidParameter Invalid parameter.
InvalidParameterValue Wrong parameter value.
LimitExceeded.MaximumRunningTask The current number of concurrent tasks exceeds the limit.
LimitExceeded.MaximumTask The number of tasks created on the day exceeds the limit.
ResourceNotFound.ChannelNotExist The channel does not exist.
ResourceUnavailable.InvalidVodStatus The VOD service has not been activated.
ResourceUnavailable.StreamNotExist The stream does not exist.