Cloud Recording RESTful API

Make sure you have read Quickstart Guide before reading this section.

How to call API

Item	Description
Request URL	{https}://{domain}/app/{appid}/v1/recordoss/{reqUri}?traceId={yourTraceId} appid: the AppID used in your project traceId: for tracing each API call; use "server IP + time when ID is generated + auto-increment sequence + current process number"
Domain	Domestic: api.jocloud.com International: api-oversea.jocloud.com
Head	Content-Type：application/json;charset=UTF-8 AppID: the AppID used in your project Token: is Basic authorization. See its generation method in Basic HTTP Authentication.

applyrecord

Features

Before you enable cloud recording, call this method to get a resource ID (resid).

Request

Request method: GET
Request URL: app/{appid}/v1/recordoss/applyrecord?traceId={yourTraceId}

Notes:

Each AppID is limited to 10 requests per second.

Sample Request

Request URL:

https://api.jocloud.com/app/10034/v1/recordoss/applyrecord?traceId=23116613407505472693518435

Sample Response

{
    "code": 0,
    "message": "success",
    "resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
    "traceId": "23116613407505472693518435"
}

code: int, Response Code.
message: string; any situation other than "success" will contain error details.
resid: string, the cloud recording resource ID. With this ID, you can initiate one cloud recording. This ID remains valid for five minutes; request again in case of timeout.
traceId: string; traceId carried by a request; convenient for tracing

startrecord

Features

After calling applyrecord and obtaining resid, call this API to start cloud recording.

Request

Request method: POST
Request URL: app/{appid}/v1/recordoss/startrecord?traceId={yourTraceId}

Parameters

Name	Type	Mixed stream	Source stream	Description
resid	string	Required	Required	resid returned after calling applyrecord
appid	int	Required	Required	the AppID used in your project
roomid	string	Required	Required	ID of the room to be recorded
recordtype	int	Required	Required	Record type 0: audio/video recording (default) 1: video recording 2: audio recording Value range: 0,1,2
streamtype	int	1	2	1: Mixed stream recording 2: Source stream recording Value range: 1,2
mixconfig	JSON	Required	No	Mixed Streams Configuration
uid	string	No	Required	User ID
storagecfg	JSON	Required	Required	Your OSS Storage Path
callbackurl	string	Optional	Optional	Specify callback address

mixconfig

Parameter	Type	Layout template	Custom layout	Description
intput	JSONArray	No	Required	Input parameter. Do not fill it when using Layout template .
templateid	int	Required	No	Layout template ID, See Mix layout for details: 1: Horizontal Layout 2: Vertical Layout 3: Tiled Layout 4: Corner Layout 5: 5 Users Horizontal Layout Only valid for stream mixing in one room
output	JSON	Required	Required	Output parameter

input

Parameter	Type	Video and audio	Video	Audio	Description
uid	string	Custom	Custom	Custom	Source stream user ID
roomid	string	Custom	Custom	Custom	Room ID of the source stream user
streamtype	int	0	1	2	Stream type: 0: video and audio 1: video 2: audio
zOrder	int	Custom	Custom	No	Layer (0 indicates the bottommost layer and 1 is the first layer from bottom to top, and so on, up to 16 layers)
layoutX	int	Custom	Custom	No	Top left x-coordinate in canvas ( coordinate system: abscissa axis extended rightward and ordinate axis extended downward ) Value range: [0, 1920]
layoutY	int	Custom	Custom	No	Top left y-coordinate in canvas Value range: [0, 1920]
layoutH	int	Custom	Custom	No	Height in canvas Value range: (0, 1920]
layoutW	int	Custom	Custom	No	Width in canvas Value range: (0, 1920]
crop	int	Custom	Custom	No	Zooming display options 0: centered display of input stream, with black sides filled 1: filling in input stream as much as possible, and centering and cropping
cropX	int	Optional	Optional	No	An x coordinate of a cutout region in an original image if an input is a cutout image from the original image Value range: [0, 1920]
cropY	int	Optional	Optional	No	An y coordinate of a cutout region in an original image if an input is a cutout image from the original image Value range: [0, 1920]
cropH	int	Optional	Optional	No	Height of a cutout region if an input is a cutout image from the original image Value range: (0, 1920]
cropW	int	Optional	Optional	No	Width of a cutout region if an input is a cutout image from the original image Value range: (0, 1920]
alpha	float	Optional	Optional	No	Transparency in mixed flow, value range: [0, 1.0]. 0 means completely transparent, 1.0 means completely opaque.

output

Parameter	Type	Video and audio	Video	Audio	Description
streamtype	int	0	1	2	Stream type: 0: video and audio 1: video 2: audio
videoheight	int	Custom	Custom	No	Video height, value range: [16, 1920], integral multiple of 4. (If not, round to the nearest multiple of 4)
videowidth	int	Custom	Custom	No	Video width, value range: [16, 1920], integral multiple of 4. (If not, round to the nearest multiple of 4)
videobitrate	int	Custom	Custom	No	Video bit rate in kbps, value range: (0, 10000]
videofps	int	15 recommended	15 recommended	No	Video frame rate, value range: (0, 60]. The default value is 15fps. If video frame rate is set higher than 60, the service will be adjusted to 60.
videogop	int	30 recommended	30 recommended	No	Video GOP, value range (0, 1000), unit: fps, default value: 30fps. Adopting calculation method: videogop = videofps × Key frame interval (seconds). When it is not satisfied, it will round up and adjust the videogop.
videoencode	int	100	100	No	Video encoding 100: H264 (not support H265)
audiobitrate	int	128	Optional	128	Audio bitrate (kbps), value: 128.
audiochannel	int	2	Optional	2	Number of audio tracks. 2: Stereo Value is 2.
audiosample	int	48000	Optional	48000	Audio sampling rate, value is 48000.
audioformat	int	2	Optional	2	Audio code 2: AAC Value is 2.
patch	int	Optional	Optional	No	Video frame patching method: 0: not patching the frame 1: patching black screen 2: patching the last frame 3: patching the specified picture
patchUrl	string	Optional	Optional	No	When video frame patching method is 3, specifying the picture address with the length not more than 256 bytes
watermark	JSON	Optional	Optional	No	Watermark
background	JSON	Optional	Optional	No	Background image and background color
base64seidata	string	Optional	Optional	No	Customize the video frame SEI information. The input string is Base64 encoded, and the length of original string does not exceed 2048 bytes. Server encodes the original content into each video frame. This setting does not work for pure audio output.

watermark

Name	Type	Required	Description
timestamp	JSON	No	Timestamp watermark
textList	JSON Array	No	Text watermark
imageList	JSON Array	No	Image watermark

timestamp

Name	Type	Required	Description
x	int	Yes	The horizontal axis coordinate when taking the upper left corner as the origin, with the value range: [0, 1920), and does not exceed the width of the output picture.
y	int	Yes	The vertical axis coordinate when taking the upper left corner as the origin, with the value range: [0, 1920), and does not exceed the height of the output picture.
format	string	Yes	Posix time display format. The following are supported: "%Y/%m/%d": displayed as 2020/01/01 "%Y-%m-%d": displayed as 2020-01-01 "%H:%M:%S": displayed as 13:00:00 "%Y/%m/%d %H:%M:%S": displayed as 2020/01/01 13:00:00 "%Y-%m-%d %H:%M:%S": displayed as 2020-01-01 13:00:00
font	string	No	Font format, only support value "NotoSansCJK".
size	int	Yes	Font size, with the value range: (0, 100].
color	string	No	Font color, RGB color definition, with the value range: 000000-FFFFFF, letters are all uppercase or all lowercase. Default value is "FFFFFF" which means white.
backgroundColor	string	No	Background color, RGB color definition, with the value range: 000000-FFFFFF, letters are all uppercase or all lowercase. Default value is "000000" which means black
alpha	float	No	Transparency, with the value range: [0.0, 1.0]. 0.0 means completely transparent, and 1.0 means completely opaque.

textList

Name	Type	Required	Description
x	int	Yes	The horizontal axis coordinate when taking the upper left corner as the origin, with the value range: [0, 1920), and does not exceed the width of the output picture.
y	int	Yes	The vertical axis coordinate when taking the upper left corner as the origin, with the value range: [0, 1920), and does not exceed the height of the output picture.
content	string	Yes	Display content string.
font	string	No	Font format, only support value "NotoSansCJK".
size	int	Yes	Font size, with the value range: (0, 100]
color	string	No	Font color, RGB color definition, with the value range: 000000-FFFFFF, letters are all uppercase or all lowercase. Default value is "FFFFFF" which means white.
backgroundColor	string	No	Background color, RGB color definition, with the value range: 000000-FFFFFF, letters are all uppercase or all lowercase. Default value is "000000" which means black
alpha	float	No	Transparency, with the value range: [0.0, 1.0]. 0.0 means completely transparent, and 1.0 means completely opaque.

imageList

Name	Type	Required	Description
x	int	Yes	The horizontal axis coordinate when taking the upper left corner as the origin, with the value range: [0, 1920), and does not exceed the width of the output picture.
y	int	Yes	The vertical axis coordinate when taking the upper left corner as the origin, with the value range: [0, 1920), and does not exceed the height of the output picture.
width	int	Yes	Image width, with the value range: (0, 1920), and does not exceed the width of the output picture.
height	int	Yes	Image height, with the value range: (0, 1920), and does not exceed the height of the output picture.
url	string	Yes	Image URL address, the length does not exceed 256 bytes
scale	int	Yes	Zoom/crop mode. 0: Zoom and crop in equal proportions. 1: Stretch to fill the entire canvas.
alpha	float	No	Transparency, with the value range: [0.0, 1.0]. 0.0 means completely transparent, and 1.0 means completely opaque.

background

Name	Type	Required	Description
color	string	No	Background color, RGB color definition, with the value range: 000000-FFFFFF, all letters are uppercase or all lowercase. Default value is "000000" which means black.
image	JSON	No	Background image, when both color and image are filled in, image value will cover color value.

image

Name	Type	Required	Description
url	string	Yes	Image URL address, the length does not exceed 256 bytes.
scale	int	Yes	Zoom/crop mode. 0: Zoom and crop in equal proportions. 1: Stretch to fill the entire canvas.

storagecfg

Name	Type	Required	Description
vender	int	Yes	Vendor type 0: Alibaba Cloud 1: Tencent Cloud 2: Qiniu Cloud
endpoint	string	Yes	Your OSS endpoint
bucket	string	Yes	Your OSS bucket
accesskey	string	Yes	Your OSS accesskey
secretkey	string	Yes	Your OSS secretkey
fileprefix	JSONArray	No	A multi string array specifies a recording file’s location by third-party cloud storage For example: fileprefix = ["aaaa", "bbbb"], indicates that the prefix "aaaa/bbbb/" will be added to the recording file name, i.e. aaaa/bbbb/testtest.m3u8. The prefix length (slash included) cannot exceed 128 characters. No slashes are allowed in one string. Only support [A,Z],[a,z],[0,9] characters permutation and combination.

Notes:

Each application ID is limited to 10 requests per second.

When using the layout template templateid, you do not need to enter input stream information—however, this only applies to one room; if you need to mix streams across rooms, you will need to enter input parameters.

When using the mixed stream audio recording function, the mixed streams configuration only needs to fill in audio-related parameters. If the input parameter is not filled, it means that mixed audio recording is performed for all audio streams in one room. If you need to mix streams across rooms, you will need to enter input parameters.

Source stream recording does not need to set the mixed streams configuration.

endpoint

When vender value is 0 (The third-party cloud storage is Alibaba Cloud), endpoint value should be filled with the public endpoint.
For example: oss-cn-hangzhou.aliyuncs.com

When vender value is 1 (The third-party cloud storage is Tencent Cloud), endpoint value should be filled with the string of upload domain name without BucketName-APPID.
For example: cos.ap-beijing-1.myqcloud.com

When vender value is 2 (The third-party cloud storage is Qiniu Cloud), endpoint value should be filled with Access Endpoint.
For example: s3-cn-south-1.qiniucs.com

Sample Request

Request URL:

https://api.jocloud.com/app/10034/v1/recordoss/startrecord?traceId=82719231231166134075054726935

Request body contents

{
   "resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
   "appid": 10034,
   "roomid": "abcabc",
   "recordtype": 0,
   "streamtype": 1,
   "mixconfig":{
       "input":[
               {
                   "uid":"10266666",
                   "roomid":"abcabc",
                   "streamtype":0,
                   "zOrder":0,
                   "layoutX":0,
                   "layoutY":0,
                   "layoutH":600,
                   "layoutW":400,
                   "crop":0
               },
               {
                   "uid":"10277777",
                   "roomid":"efdefd",
                   "streamtype":0,
                   "zOrder":1,
                   "layoutX":400,
                   "layoutY":0,
                   "layoutH":600,
                   "layoutW":400,
                   "crop":0
               }
       ],
       "output":{
           "streamtype":0,
           "videoheight":600,
           "videowidth":800,
           "videobitrate":600,
           "videofps":24,
           "videogop":72,
           "videoencode":100,
           "audiobitrate":128,
           "audiosample":48000,
           "audiochannel":2,
           "audioformat":2
       }
   },
   "storagecfg": {
       "vender": 0,
       "endpoint": "xxxx-test-endpoint",
       "bucket": "xxxx-test-bucket",
       "accesskey": "xxxx-test-accesskey",
       "secretkey": "xxxx-test-secretkey",
       "fileprefix": ["test1","test2"]
   }
}

Sample Response

Response body contents

{
    "code": 0,
    "message": "success",
    "recordid": "ba1107310000565164da34f816f842da94d",
    "traceId": "82719231231166134075054726935"
}

code: int, Response Code.
message: string; any situation other than "success" will contain error details.
recordid: string; cloud recording task ID, identifies a single recording task. You will need to provide this ID to execute Update Mixed Stream Layout or Stop Recording.
traceId: string; traceId carried by a request; convenient for tracing

stoprecord

Features

Once you have started recording, call this API to stop recording.

Request

Request method: POST
Request URL: app/{appId}/v1/recordoss/stoprecord?traceId={yourTraceId}

Parameters

Name	Type	Required	Description
appid	int	Yes	The AppID used in your project
resid	string	Yes	resid returned after calling applyrecord
roomid	string	Yes	ID of the room to be recorded
recordid	string	Yes	Recording ID returned after calling startrecord successfully

Notes:

Each application ID is limited to 10 requests per second.

When there is no stream in the room for more than the preset time (default is 30 s), cloud recording stops automatically. Contact Customer Support for special configuration.

If recording task has been stopped and you need to record again, call applyrecord to request a new resid.

Sample Request

Request URL:

https://api.jocloud.com/app/10034/v1/recordoss/stoprecord?traceId=214325255213407589332213

Request body contents

{
   "resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
   "appid": 10034,
   "roomid": "abcabc",
   "recordid": "ba1107310000565164da34f816f842da94d"
}

Sample Response

{
    "code": 0,
    "message": "success",
    "recordid": "ba1107310000565164da34f816f842da94d",
    "traceId": "214325255213407589332213"
}

code: int, Response Code.
message: string; any situation other than "success" will contain error details.
recordid: string, cloud recording task ID, identifies a single recording task, returned by startrecord.
traceId: string; traceId carried by a request; convenient for tracing

updatemixrecord

Features

After starting recording, call this API to update the recording task’s mixed stream layout. This API supports mixed streams recording.

Request

Request method: POST
Request URL: app/{appId}/v1/recordoss/updatemixrecord?traceId={yourTraceId}

Parameters

Name	Type	Required	Description
resid	string	Yes	resid returned after calling applyrecord
appid	int	Yes	The AppID used in your project
roomid	string	Yes	ID of the room to be recorded
recordid	string	Yes	Cloud recording task ID, identifies a single recording task
mixconfig	JSON	Yes	Mixed Stream Configuration

Notes:

Each application ID is limited to 10 requests per second.

Call this API after starting but before stopping recording; otherwise it will return an error.

This API only supports mixed stream recording task, and error will be returned when the task is source stream recording task (Response Code: 4019, Recording task type is not mixed stream recording).

If after recording has stopped you need to record again, call applyrecord to request a new resid.

Sample Request

Request URL:

https://api.jocloud.com/app/10034/v1/recordoss/updatemixrecord?traceId=82719231231166134075054726935

Request body contents

{
   "resid": "1d3fe093f9b9dbfa2d34e22cb34a12496ed6b057896358131208a0d981eb-ba11073100006be2",
   "appid": 10034,
   "roomid": "abcabc",
   "recordid": "ba1107310000565164da34f816f842da94d",
   "mixconfig":{
       "input":[
               {
                   "uid":"10266666",
                   "roomid":"abcabc",
                   "streamtype":0,
                   "zOrder":0,
                   "layoutX":0,
                   "layoutY":0,
                   "layoutH":600,
                   "layoutW":400,
                   "crop":0
               },
               {
                   "uid":"10277777",
                   "roomid":"efdefd",
                   "streamtype":0,
                   "zOrder":1,
                   "layoutX":400,
                   "layoutY":0,
                   "layoutH":600,
                   "layoutW":400,
                   "crop":0
               }
       ],
       "output":{
           "streamtype":0,
           "videoheight":720,
           "videowidth":1080,
           "videobitrate":1000,
           "videofps":24,
           "videogop":72,
           "videoencode":100,
           "audiobitrate":128,
           "audiosample":48000,
           "audiochannel":2,
           "audioformat":2
       }
   }
}

Sample Response

{
    "code": 0,
    "message": "success",
    "recordid": "ba1107310000565164da34f816f842da94d",
    "traceId": "82719231231166134075054726935"
}

code: int, Response Code.
message: string; any situation other than "success" will contain error details.
recordid: string, cloud recording task ID, identifies a single recording task.
traceId: string; traceId carried by a request; convenient for tracing

queryrecord

Features

After starting the recording, you can call this API to query the status of the recording task.

Request

Request method: GET
Request URL: app/{appid}/v1/recordoss/queryrecord/{roomid}/{recordid}?traceId={yourTraceId}

Parameters

Name	Type	Required	Description
appid	int	Yes	The AppID used in your project
roomid	string	Yes	ID of the room to be recorded
recordid	string	Yes	Cloud recording task ID, identifies a single recording task

Notes:

Each recordid is limited to 10 requests per second.

Call this API after starting recording and before stopping recording.

After the recording task is stopped (including active stop and timeout stop scenarios), the API will return an error. (Response Code: 4013, Recording recordid does not exist)

Sample Request

Request URL:

https://api.jocloud.com/app/10034/v1/recordoss/queryrecord/abcabc/ba1107310000565164da34f816f842da94d?traceId=82719231231166134075054726935

Sample Response

{
    "code": 0,
    "message": "success",
    "recordid": "ba1107310000565164da34f816f842da94d",
    "data": {
        "recordid": "ba1107310000565164da34f816f842da94d",
        "appid": 10034,
        "roomid": "abcabc",
        "status": 0,
        "createtime": 1608084987733,
        "starttime": 0
    },
    "traceId": "82719231231166134075054726935"
}

code: int, Response Code.
message: string; any situation other than "success" will contain error details.
recordid: string, cloud recording task ID, identifies a single recording task.
traceId: string; traceId carried by a request; convenient for tracing

data: JSON, the information of the recording task is as follows:

Name	Type	Description
appid	int	The AppID used in your project
roomid	string	ID of the room to be recorded
recordid	string	Cloud recording task ID, identifies a single recording task
status	int	Record task status 0: Init status 1: Task starting
createtime	int	Record task create time, the unit is milliseconds
starttime	int	Record task start time, the unit is milliseconds

Appendix

Response code

Return Code	Note	Description
0	Succeeded	Request succeeded
1000	No token permission	No token in the service API header
1001	Invalid token	token format and/or content is incorrect
1002	No appid	No application ID
2101	Invalid parameter	Invalid API parameter
2103	Timeout	Request timeout
2104	Internal error	Internal server error
2105	Command call error	Too-frequent calling of command
4001	Recording error	Recording operation timeout
4004	Recording error	Unsupported recording parameters
4005	Recording error	Room is not publishing
4006	Recording error	Invalid recording time parameters
4007	Recording error	Recording operation timeout
4009	Recording error	Recording timeout
4011	Recording error	Recording task already exists
4012	Recording error	Recording resid is invalid or has been invalidated by timeout
4013	Recording error	Recording recordid does not exist
4014	Recording error	Stream mixing operation failed
4015	Recording error	Stream mixing operation timed out
4016	Recording error	Invalid mixed stream parameters
4017	Recording error	Stream mixing operation failed
4018	Recording error	Internal stream mixing error
4019	Recording error	Recording task type is not mixed stream recording

Common Errors

These are only commonly seen error codes for the cloud recording RESTful API process. Contact Customer Support if you encounter other errors.
HTTP response 404 error:

Content-type error. Make sure Content-type is application/json;charset=utf-8.
Incorrect HTTP (GET/POST) method.

2101: invalid parameter; note that parameters are case-sensitive, and make sure all required parameters have been entered.
4005: make sure the room is publishing a live stream.
4011: recording is already underway; do not repeat the start request with the same resid. To initiate multi-path recording, call applyrecord again to obtain a new resid.
4012: the resid is expired or invalidated. Cloud recording should be started within five minutes of obtaining a new resid. Call applyrecord again to obtain a new resid.

Cloud Recording RESTful API

How to call API

applyrecord

Features

Request

Sample Request

Sample Response

startrecord

Features

Request

Parameters

mixconfig

input

output

watermark

timestamp

textList

imageList

background

image

storagecfg

endpoint

Sample Request

Sample Response

stoprecord

Features

Request

Parameters

Sample Request

Sample Response

updatemixrecord

Features

Request

Parameters

Sample Request

Sample Response

queryrecord

Features

Request

Parameters

Sample Request

Sample Response

Appendix

Response code

Common Errors

Was this page helpful?