当前内容仅提供英语版本,中文版我们将尽快补充,感谢您的理解。

CreateCloudRecording

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. Currently, you can save recording files to Tencent Cloud VOD or COS.
  • 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 to the storage you specify.
    Mixed-stream recording: Mix the audios and videos of subscribed users (UserId) in a room, record the mixed stream, and save the recording files to the storage you specify. After a recording task ends, you can go to the VOD console (https://console.tencentcloud.com/vod/media) or COS console to view the recording files.

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 NameRequiredTypeDescription
ActionYesStringCommon Params. The value used for this API: CreateCloudRecording.
VersionYesStringCommon Params. The value used for this API: 2019-07-22.
RegionYesStringCommon Params. For more information, please see the list of regions supported by the product. This API only supports: ap-beijing, ap-guangzhou, ap-mumbai, ap-shanghai, ap-singapore.
SdkAppIdYesIntegerThe SDKAppID of the TRTC room whose streams are recorded.
RoomIdYesStringThe room ID of the TRTC room whose streams are recorded.
UserIdYesStringThe user ID of the recording robot in the TRTC room, which cannot be identical to the user IDs of anchors in the room or other recording robots. To distinguish this user ID from others, we recommend you include the room ID in the user ID.
UserSigYesStringThe signature (similar to a login password) required for the recording robot to enter the room. Each user ID corresponds to a signature. For information on how to calculate the signature, see What is UserSig?.
RecordParamsYesRecordParamsThe on-cloud recording parameters.
StorageParamsYesStorageParamsThe storage information of the recording file. Currently, you can save recording files to Tencent Cloud VOD or COS.
RoomIdTypeNoIntegerThe 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)
MixTranscodeParamsNoMixTranscodeParamsThe stream mixing parameters, which are valid if the mixed-stream recording mode is used.
MixLayoutParamsNoMixLayoutParamsThe layout parameters, which are valid if the mixed-stream recording mode is used.
ResourceExpiredHourNoIntegerThe 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.
PrivateMapKeyNoStringThe 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 NameTypeDescription
TaskIdStringThe 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.
RequestIdStringThe 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.

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 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.
The recording file is saved to Tencent Cloud VOD.

Input Example

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

{
    "StorageParams": {
        "CloudVod": {
            "TencentVod": {
                "ExpireTime": 0
            }
        }
    },
    "UserSig": "11xx111",
    "UserId": "10001",
    "RecordParams": {
        "MaxIdleTime": 60,
        "StreamType": 0,
        "RecordMode": 2
    },
    "RoomIdType": 1,
    "MixTranscodeParams": {
        "VideoParams": {
            "Width": 360,
            "BitRate": 500000,
            "Fps": 15,
            "Height": 640,
            "Gop": 10
        }
    },
    "MixLayoutParams": {
        "MixLayoutMode": 3
    },
    "SdkAppId": 1234,
    "RoomId": "3560"
}

Output Example

{
    "Response": {
        "TaskId": "-gCTFWtU7t7DUlo7A8IswFszO9z2O-rbERqJAoK-4pycoZXKjIAAnasdcasdOEycyX4CnzhIm4RAQ..",
        "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 CodeDescription
AuthFailureCAM signature/authentication error.
AuthFailure.UnRealNameAuthenticatedIdentity verification has not been completed, so this operation is not allowed.
AuthFailure.UnauthorizedOperationCAM authentication failed.
AuthFailure.UnsupportedOperationUnsupported operation.
FailedOperationOperation failed.
FailedOperation.CRUnsupportMethodUnsupported on-cloud recording method.
FailedOperation.RestrictedConcurrencyMaximum number of concurrent on-cloud recording tasks reached. Contact us to raise the limit.
InternalError.CRInternalErrorOn-cloud recording internal error.
InvalidParameter.OutOfRangeParameter value is out of range.
InvalidParameter.SdkAppIdSdkAppId is incorrect.
MissingParameter.AccessKeyAccessKey parameter missing.
MissingParameter.BucketBucket parameter missing.
MissingParameter.CloudStorageCloudStorage parameter missing.
MissingParameter.RecordModeRecordMode parameter missing.
MissingParameter.RecordParamsRecordParams parameter missing.
MissingParameter.RegionRegion parameter missing.
MissingParameter.RoomIdRoomId is missing.
MissingParameter.SdkAppIdSdkAppId is missing.
MissingParameter.SecretKeySecretKey parameter missing.
MissingParameter.StorageParamsStorageParams parameter missing.
MissingParameter.StreamTypeStreamType parameter missing.
MissingParameter.TaskIdTaskId parameter missing.
MissingParameter.UserIdMissing UserId parameter.
MissingParameter.UserSigUserSig parameter missing.
MissingParameter.VendorVendor parameter missing.
UnsupportedOperationUnsupported operation.