Server APIs v2

Starts recording streams on CDN

Update Time:2021-10-25 17:43

1 Description

Starts recording specified live streams on CDN.

You can configure your CDN to record all live streams. But when you need to record specific live streams, you can use call this API to do so.

For the server callback triggered when a recorded file is generated, see Recording completed.

If you use Tencent Cloud as your CDN provider, please clarify the following recording parameters:

  • Recording file format: M3U8, FLV, MP4, AAC (mono), or MP3 (mono).
  • Duration of a single recording (in seconds): ranges from 300 s to 7,200s, and the default value is 7,200s. If you want a single recording longer than 7,200s, you will need to merge multiple recordings together using another API Merge recorded files.
  • Retention period: how long the recordings should be kept.
To use the CDN recording service, you will need to contact ZEGO Technical Support to enable it first. For pricing details, you can check with our sales.

2 Request method and endpoint

  • Request method: GET
  • Request endpoint: https://rtc-api.zego.im/?Action=StartCDNRecrod
  • Transmission protocol: HTTPS
  • Rate limit: 20 requests/second

3 Request parameters

Listed below are the parameters specific to this request and part of the public request parameters. For the complete list of public request parameters, see Server APIs public request parameters.

Parameter Type Required Description
StreamId[] Array of String Yes A list of Stream IDs.
Example: StreamId[]=cdn01&StreamId[]=cdn02
Vendor String Yes The CDN provider.
  • Tencent: Tencent Cloud
EndTime String Yes End time of the recording task, a Unix timestamp. Recording end time must be later than the current time and not later than [current time + 24 hours].

4 Request example

https://rtc-api.zego.im/?Action=StartCDNRecrod
&StreamId[]=cdn01&StreamId[]=cdn02
&Vendor=Tencent
&EndTime=1616415377
&<Public Request Parameters>

5 Response parameters

Parameter Type Description
Code Number Return code.
Message String Description of the request execution result.
RequestId String Request ID.
Data Object Returned data.
└ Tencent Array of Object Data returned by Tencent Cloud (when Tencent Cloud is the CDN provider).
  └ StreamName String Stream name.
  └ TaskId String A globally unique task ID.
  └ RequestId String A unique Request ID that is returned for every request. This request ID will be required for any troubleshooting on the request.
  └ Code String Error code related to the current stream.
  └ Message String Error message related to the current stream.

6 Response example

{
    "Code":0,
    "Message":"success",
    "Data":{
        "Tencent":[
            {
                "StreamName":"cdn01",
                "TaskId":"UUpTbkZUQV5WQVxrRFtDUQIUB29FWwMeAxwALBxMAggNHxw7WRUWGBVeEzoTDl0CDEoFNgIESVpXQV9rRVRCXlVKWGlFV0daVENeaFdURVNY",
                "RequestId":"70628bcd-5652-4d5c-aa04-97956a4e771a",
                "Code":"",
                "Message":""
            }
        ]
    },
    "RequestId":"4191282558729715911"
}

7 Return codes

Listed below are the return codes related to this API. For the complete list of return codes, see Return codes.

Return code Description
41001 Failed to save live stream.
41002 Failed to save channel.
41003 Live stream does not exist.
41004 Stream no longer exists.
42001 Failed to forbid live stream.
42002 Failed to resume live stream.
43001 Failed to create recording index file.