tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

CreateLiveRecord

Last updated: 2023-09-06 15:06:23

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. For more information, please see the corresponding document.

  • 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, according to which the recording task will start and end automatically. Before the set end time expires (provided that StopLiveRecord is not called to terminate the task prematurely), the recording task is valid and will be started even after the push is interrupted and restarted multiple times.
    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 calls by different start/end time values may result in repeated recording tasks and thus incur additional recording fees.
    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 unintended 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.
    4. This calling method does not support recording streams outside Mainland China for the time being.

A maximum of 500 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: CreateLiveRecord.
Version Yes String Common Params. The value used for this API: 2018-08-01.
Region No String Common Params. 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 set end time 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 empty, 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 Flag 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: 1800-7200.
storage_time: recording file storage duration in seconds.
Example: record_interval=3600&storage_time=2592000.
Note: the parameter needs to be URL-encoded.
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 a 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 scheduled recording task

This example shows you how to use this API for scenarios with fixed start time and end time of recording, 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 real-time recording task

This example shows you how to immediately start to record any frame of a stream in real time. You can specify the EndTime of the recording. The recording period is 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

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 Invalid 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.
ResourceNotFound.ForbidService You are blocked.
ResourceNotFound.FreezeService Service suspended.
ResourceNotFound.StopService The service has been suspended due to account arrears. Please top up it to a positive balance to activate the service first.
ResourceNotFound.UserDisableService You disabled the service.
ResourceUnavailable.InvalidVodStatus The VOD service has not been activated.
ResourceUnavailable.StreamNotExist The stream does not exist.
Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
Privacy PolicyLegalCookie Policy