Cloud Recording RESTful API

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

API Overview

ItemDescription
Request hostDomestic: api.jocloud.com; International: api-oversea.jocloud.com
Request URL/app/{appid}/v1/recordoss/{reqUri}?traceId={yourTraceId}
reqUri:
- applyrecord
- startrecord
- stoprecord
- updatemixrecord
HeadContent-Type: application/json;charset=UTF-8
token: Basic authorization. See details in Basic HTTP Authentication.

Get Recording Resources:applyrecord

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

  • Request method: GET
  • Head:
    • Content-type is application/json;charset=utf-8
    • token is Basic authorization. See its generation method in Basic HTTP Authentication.
  • Request host:
    • Domestic: api.jocloud.com
    • International: api-oversea.jocloud.com
  • Request URL: app/{appid}/v1/recordoss/applyrecord?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”

Notes:

Each AppID is limited to 10 requests per second.

applyrecord Sample Request

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

applyrecord 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

Start Recording: startrecord

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

  • Request method: POST

  • Head:

  • Request host:

    • Domestic: api.jocloud.com
    • International: api-oversea.jocloud.com
  • Request URL: app/{appid}/v1/recordoss/startrecord?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”
  • Request body parameters:

    NameTypeRequiredSample ValueDescription
    residstringYes resid returned after calling applyrecord
    appidintYes123456789Basic HTTP Authentication
    roomidstringYesroom1234ID of the room to be recorded
    recordtypeintYes0Record type
    0: audio/video recording (default)
    1: video recording
    2: audio recording
    Value range: 0,1,2
    streamtypeintYes1Mixed stream recording: 1
    Source stream recording: 2
    Value range: 1,2
    mixconfigJSONMixed stream recording (required) Mixed Streams Configuration
    uidstringSource stream recording (required) User ID
    storagecfgJSONYes Your OSS Storage Path
    callbackurlstringNo Specify callback address

    Storagecfg Parameter description

    NameTypeRequiredSample ValueDescription
    venderintYes0Vendor type, 0: Alibaba Cloud
    Value range: 0
    endpointstringYes0Your OSS endpoint
    bucketstringYes0Your OSS bucket
    accesskeystringYes0Your OSS accesskey
    secretkeystringYes0Your OSS secretkey
    fileprefixJSONArrayNo0A 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.
  • A default mixed streams configuration is supported according to application ID levels. Contact customer support if you require this service.
  • Source stream recording does not need to set the mixed streams configuration.

startrecord 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"]
   }
}

startrecord 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 Layoutor Stop Recording.
  • traceId: string; traceId carried by a request; convenient for tracing

Stop Recording: stoprecord

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

  • Request method: POST

  • Request URL: https://api.jocloud.com/app/{appId}/v1/recordoss/stoprecord?traceId={yourTraceId}

  • Head:

    • Content-type is application/json;charset=utf-8
    • token is Basic authorization. See its generation method inBasic HTTP Authentication.
  • Request host:

    • Domestic: api.jocloud.com
    • International: api-oversea.jocloud.com
  • Request URL: app/{appid}/v1/recordoss/startrecord?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”
  • Request body parameters:

    NameTypeRequiredSample ValueDescription
    appidintYes123456789The AppID used in your project
    residstringYes resid returned after calling applyrecord
    roomidstringYesroom1234ID of the room to be recorded
    recordidstringYes0Recording 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.

stoprecord 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"
}

stoprecord 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

Update Mixed Stream Layout: updatemixrecord

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

  • Request method: POST

  • Request URL: https://api.jocloud.com/app/{appId}/v1/recordoss/updatemixrecord?traceId={yourTraceId}

  • Head:

  • Request host:

    • Domestic: api.jocloud.com
    • International: api-oversea.jocloud.com
  • Request URL: app/{appid}/v1/recordoss/startrecord?traceId={yourTraceId}

    • appid: The AppID used in your project
    • traceId: For tracking each API call; use “server IP + time when ID is generated + auto-increment sequence + current process number”
  • Request body parameters:

    NameTypeRequiredSample ValueDescription
    residstringYes resid returned after calling applyrecord
    appidintYes123456789The AppID used in your project
    roomidstringYesroom1234ID of the room to be recorded
    recordidstringYes Cloud recording task ID, identifies a single recording task
    mixconfigJSONYes 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.

updatemixrecord 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
       }
   }
}

updatemixrecord 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

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
<