tencent cloud

Feedback

CreateCloudRecording

Last updated: 2022-05-11 15:59:09

1. API Description

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

API description

This API is used to start an on-cloud recording task. It records the audio and video streams in a room and saves them to the specified cloud storage. You can use this API to record the streams in a room separately, or you can mix the streams first and then record the mixed stream.

You can use this API to perform the following operations:

  • Specify the anchors whose streams you want or do not want to record by using the RecordParams parameter
  • Specify the storage service you want to save recording files to by using the StorageParams parameter
  • Specify transcoding settings for mixed-stream recording, including video resolution, video bitrate, frame rate, and audio quality, by using MixTranscodeParams
  • Specify the layout of different videos in mixed-stream recording mode or select an auto-arranged layout template

Key concepts

  • Single-stream recording: Record the audio and video of each subscribed user (UserId) in a room and save the recording files (M3U8/TS) to the cloud
  • Mixed-stream recording: Mix the audios and videos of subscribed users (UserId) in a room, record the mixed stream, and save the recording files (M3U8/TS) to the cloud

A maximum of 20 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: CreateCloudRecording.
Version Yes String Common Params. The value used for this API: 2019-07-22.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
SdkAppId Yes Integer The SDKAppID of the TRTC room whose streams are recorded.
RoomId Yes String The room ID of the TRTC room whose streams are recorded.
UserId Yes String The user ID of the recording robot in the TRTC room, which cannot be the same as a user ID already in use. We recommend you include this user ID in the room ID.
UserSig Yes String The signature (similar to login password) required for the recording robot to enter the room. For information on how to calculate the signature, see What is UserSig?. |
RecordParams Yes RecordParams The on-cloud recording parameters.
StorageParams Yes StorageParams The cloud storage parameters.
RoomIdType No Integer The type of the TRTC room ID, which must be the same as the ID type of the room whose streams are recorded.
0: String
1: 32-bit integer (default)
MixTranscodeParams No MixTranscodeParams The stream mixing parameters, which are valid if the mixed-stream recording mode is used.
MixLayoutParams No MixLayoutParams The layout parameters, which are valid if the mixed-stream recording mode is used.
ResourceExpiredHour No Integer The amount of time (in hours) during which API requests can be made after recording starts. Calculation starts when a recording task is started (when the recording task ID is returned). Once the period elapses, the query, modification, and stop recording APIs can no longer be called, but the recording task will continue. The default value is 72 (three days), and the maximum and minimum values allowed are 720 (30 days) and 6 respectively. If you do not set this parameter, the query, modification, and stop recording APIs can be called within 72 hours after recording starts.
PrivateMapKey No String The permission ticket for a TRTC room. This parameter is required if advanced permission control is enabled in the console, in which case the TRTC backend will verify users’ PrivateMapKey, which include an encrypted room ID and permission bit list. A user providing only UserSig and not PrivateMapKey will be unable to enter the room.

3. Output Parameters

Parameter Name Type Description
TaskId String The task ID assigned by the recording service, which uniquely identifies a recording process and becomes invalid after a recording task ends. After a recording task starts, if you want to perform other actions on the task, you need to specify the task ID when making API requests.
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Starting an on-cloud recording task

This example shows you how to start on-cloud recording in room 3560 under the application whose SDKAppID is 1234.

The timeout period for recording is one minute.
The recording mode is mixed-stream recording.
The type of the streams recorded are audio and video.
The streams of all anchors in the room are subscribed.
The recording file is saved to Tencent Cloud with the prefix directory1/directory2/.
The resolution of the recorded video is 360 x 640, the frame rate is 15 fps, and the bitrate is 500,000 bps. The default background color is used.
The grid layout template is used.

Input Example

POST / HTTP/1.1
Host: trtc.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateCloudRecording
<Common request parameters>

{
    "StorageParams": {
        "CloudStorage": {
            "Vendor": 0,
            "Region": "xx",
            "Bucket": "xx",
            "FileNamePrefix": [
                "directory1",
                "directory2"
            ],
            "SecretKey": "xx",
            "AccessKey": "xx"
        }
    },
    "UserSig": "xx",
    "UserId": "xx",
    "RecordParams": {
        "MaxIdleTime": 60,
        "StreamType": 0,
        "RecordMode": 2
    },
    "RoomIdType": 1,
    "MixTranscodeParams": {
        "VideoParams": {
            "Width": 360,
            "BitRate": 500000,
            "Fps": 15,
            "Height": 640,
            "Gop": 10
        }
    },
    "SdkAppId": 1234,
    "RoomId": "3560"
}

Output Example

{
  "Response": {
    "TaskId": "5df46eb2-8e4b-490e-9c3c-dbd3b84faefc",
    "RequestId": "71993312-6ab8-4768-9124-118e0a20c45f"
  }
}

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
AuthFailure CAM signature/authentication error.
AuthFailure.UnRealNameAuthenticated Identity verification has not been completed, so this operation is not allowed.
AuthFailure.UnauthorizedOperation CAM authentication failed.
AuthFailure.UnsupportedOperation Unsupported operation.
FailedOperation Operation failed.
FailedOperation.CRUnsupportMethod Unsupported on-cloud recording method.
FailedOperation.RestrictedConcurrency Maximum number of concurrent on-cloud recording tasks reached. Contact us to raise the limit.
InternalError.CRInternalError On-cloud recording internal error.
InvalidParameter.OutOfRange Parameter value is out of range.
MissingParameter.AccessKey AccessKey parameter missing.
MissingParameter.Bucket Bucket parameter missing.
MissingParameter.CloudStorage CloudStorage parameter missing.
MissingParameter.RecordMode RecordMode parameter missing.
MissingParameter.RecordParams RecordParams parameter missing.
MissingParameter.Region Region parameter missing.
MissingParameter.RoomId RoomId is missing.
MissingParameter.SdkAppId SdkAppId is missing.
MissingParameter.SecretKey SecretKey parameter missing.
MissingParameter.StorageParams StorageParams parameter missing.
MissingParameter.StreamType StreamType parameter missing.
MissingParameter.TaskId TaskId parameter missing.
MissingParameter.UserId Missing UserId parameter.
MissingParameter.UserSig UserSig parameter missing.
MissingParameter.Vendor Vendor parameter missing.
Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support