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"
DomainDomestic: api.jocloud.com
International: api-oversea.jocloud.com
HeadContent-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

NameTypeMixed streamSource streamDescription
residstringRequiredRequiredresid returned after calling applyrecord
appidintRequiredRequiredthe AppID used in your project
roomidstringRequiredRequiredID of the room to be recorded
recordtypeintRequiredRequiredRecord type
0: audio/video recording (default)
1: video recording
2: audio recording
Value range: 0,1,2
streamtypeint121: Mixed stream recording
2: Source stream recording
Value range: 1,2
mixconfigJSONRequiredNoMixed Streams Configuration
uidstringNoRequiredUser ID
storagecfgJSONRequiredRequiredYour OSS Storage Path
callbackurlstringOptionalOptionalSpecify callback address

mixconfig

ParameterTypeLayout templateCustom layoutDescription
intputJSONArrayNoRequiredInput parameter. Do not fill it when using Layout template .
templateidintRequiredNoLayout 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
outputJSONRequiredRequiredOutput parameter

input

ParameterTypeVideo and audioVideoAudioDescription
uidstringCustomCustomCustomSource stream user ID
roomidstringCustomCustomCustomRoom ID of the source stream user
streamtypeint012Stream type:
0: video and audio
1: video
2: audio
zOrderintCustomCustomNoLayer (0 indicates the bottommost layer and 1 is the first layer from bottom to top, and so on, up to 16 layers)
layoutXintCustomCustomNoTop left x-coordinate in canvas ( coordinate system: abscissa axis extended rightward and ordinate axis extended downward )
Value range: [0, 1920]
layoutYintCustomCustomNoTop left y-coordinate in canvas
Value range: [0, 1920]
layoutHintCustomCustomNoHeight in canvas
Value range: (0, 1920]
layoutWintCustomCustomNoWidth in canvas
Value range: (0, 1920]
cropintCustomCustomNoZooming 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
cropXintOptionalOptionalNoAn 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]
cropYintOptionalOptionalNoAn 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]
cropHintOptionalOptionalNoHeight of a cutout region if an input is a cutout image from the original image
Value range: (0, 1920]
cropWintOptionalOptionalNoWidth of a cutout region if an input is a cutout image from the original image
Value range: (0, 1920]
alphafloatOptionalOptionalNoTransparency in mixed flow, value range: [0, 1.0]. 0 means completely transparent, 1.0 means completely opaque.

output

ParameterTypeVideo and audioVideoAudioDescription
streamtypeint012Stream type:
0: video and audio
1: video
2: audio
videoheightintCustomCustomNoVideo height, value range: [16, 1920], integral multiple of 4.
(If not, round to the nearest multiple of 4)
videowidthintCustomCustomNoVideo width, value range: [16, 1920], integral multiple of 4.
(If not, round to the nearest multiple of 4)
videobitrateintCustomCustomNoVideo bit rate in kbps, value range: (0, 10000]
videofpsint15 recommended15 recommendedNoVideo 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.
videogopint30 recommended30 recommendedNoVideo 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.
videoencodeint100100NoVideo encoding
100: H264 (not support H265)
audiobitrateint128Optional128Audio bitrate (kbps), value: 128.
audiochannelint2Optional2Number of audio tracks.
2: Stereo
Value is 2.
audiosampleint48000Optional48000Audio sampling rate, value is 48000.
audioformatint2Optional2Audio code
2: AAC
Value is 2.
patchintOptionalOptionalNoVideo frame patching method:
0: not patching the frame
1: patching black screen
2: patching the last frame
3: patching the specified picture
patchUrlstringOptionalOptionalNoWhen video frame patching method is 3, specifying the picture address with the length not more than 256 bytes
watermarkJSONOptionalOptionalNoWatermark
backgroundJSONOptionalOptionalNoBackground image and background color
base64seidatastringOptionalOptionalNoCustomize 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

NameTypeRequiredDescription
timestampJSONNoTimestamp watermark
textListJSON ArrayNoText watermark
imageListJSON ArrayNoImage watermark

timestamp

NameTypeRequiredDescription
xintYesThe 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.
yintYesThe 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.
formatstringYesPosix 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
fontstringNoFont format, only support value "NotoSansCJK".
sizeintYesFont size, with the value range: (0, 100].
colorstringNoFont color, RGB color definition, with the value range: 000000-FFFFFF, letters are all uppercase or all lowercase.
Default value is "FFFFFF" which means white.
backgroundColorstringNoBackground color, RGB color definition, with the value range: 000000-FFFFFF, letters are all uppercase or all lowercase.
Default value is "000000" which means black
alphafloatNoTransparency, with the value range: [0.0, 1.0]. 0.0 means completely transparent, and 1.0 means completely opaque.

textList

NameTypeRequiredDescription
xintYesThe 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.
yintYesThe 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.
contentstringYesDisplay content string.
fontstringNoFont format, only support value "NotoSansCJK".
sizeintYesFont size, with the value range: (0, 100]
colorstringNoFont color, RGB color definition, with the value range: 000000-FFFFFF, letters are all uppercase or all lowercase.
Default value is "FFFFFF" which means white.
backgroundColorstringNoBackground color, RGB color definition, with the value range: 000000-FFFFFF, letters are all uppercase or all lowercase.
Default value is "000000" which means black
alphafloatNoTransparency, with the value range: [0.0, 1.0]. 0.0 means completely transparent, and 1.0 means completely opaque.

imageList

NameTypeRequiredDescription
xintYesThe 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.
yintYesThe 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.
widthintYesImage width, with the value range: (0, 1920), and does not exceed the width of the output picture.
heightintYesImage height, with the value range: (0, 1920), and does not exceed the height of the output picture.
urlstringYesImage URL address, the length does not exceed 256 bytes
scaleintYesZoom/crop mode.
0: Zoom and crop in equal proportions.
1: Stretch to fill the entire canvas.
alphafloatNoTransparency, with the value range: [0.0, 1.0]. 0.0 means completely transparent, and 1.0 means completely opaque.

background

NameTypeRequiredDescription
colorstringNoBackground color, RGB color definition, with the value range: 000000-FFFFFF, all letters are uppercase or all lowercase.
Default value is "000000" which means black.
imageJSONNoBackground image, when both color and image are filled in, image value will cover color value.

image

NameTypeRequiredDescription
urlstringYesImage URL address, the length does not exceed 256 bytes.
scaleintYesZoom/crop mode.
0: Zoom and crop in equal proportions.
1: Stretch to fill the entire canvas.

storagecfg

NameTypeRequiredDescription
venderintYesVendor type
0: Alibaba Cloud
1: Tencent Cloud
2: Qiniu Cloud
endpointstringYesYour OSS endpoint
bucketstringYesYour OSS bucket
accesskeystringYesYour OSS accesskey
secretkeystringYesYour OSS secretkey
fileprefixJSONArrayNoA 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

img

  • 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

img

  • 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

NameTypeRequiredDescription
appidintYesThe AppID used in your project
residstringYesresid returned after calling applyrecord
roomidstringYesID of the room to be recorded
recordidstringYesRecording 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

NameTypeRequiredDescription
residstringYesresid returned after calling applyrecord
appidintYesThe AppID used in your project
roomidstringYesID of the room to be recorded
recordidstringYesCloud recording task ID, identifies a single recording task
mixconfigJSONYesMixed 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

NameTypeRequiredDescription
appidintYesThe AppID used in your project
roomidstringYesID of the room to be recorded
recordidstringYesCloud 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:

    NameTypeDescription
    appidintThe AppID used in your project
    roomidstringID of the room to be recorded
    recordidstringCloud recording task ID, identifies a single recording task
    statusintRecord task status
    0: Init status
    1: Task starting
    createtimeintRecord task create time, the unit is milliseconds
    starttimeintRecord task start time, the unit is milliseconds

Appendix

Response code

Return CodeNoteDescription
0SucceededRequest succeeded
1000No token permissionNo token in the service API header
1001Invalid tokentoken format and/or content is incorrect
1002No appidNo application ID
2101Invalid parameterInvalid API parameter
2103TimeoutRequest timeout
2104Internal errorInternal server error
2105Command call errorToo-frequent calling of command
4001Recording errorRecording operation timeout
4004Recording errorUnsupported recording parameters
4005Recording errorRoom is not publishing
4006Recording errorInvalid recording time parameters
4007Recording errorRecording operation timeout
4009Recording errorRecording timeout
4011Recording errorRecording task already exists
4012Recording errorRecording resid is invalid or has been invalidated by timeout
4013Recording errorRecording recordid does not exist
4014Recording errorStream mixing operation failed
4015Recording errorStream mixing operation timed out
4016Recording errorInvalid mixed stream parameters
4017Recording errorStream mixing operation failed
4018Recording errorInternal stream mixing error
4019Recording errorRecording 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.

Was this page helpful?

Helpful Not helpful
Submitted! Your feedback would help us improve the website.
Feedback
Top