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:
- startrtmp
- stoprtmp
HeadContent-Type: application/json;charset=UTF-8
token: Basic authorization. See its generation method in Basic HTTP Authentication

Start Pushing Streams to CDN: startrtmp

The API for pushing streams to CDN carries video mixing parameters.

  • Request method: POST
  • 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}/v2/rtmpforward/startrtmp?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”

Parameters

ParameterRequiredData TypeDescription
appidYesuint64Service application ID
roomidYesstringRoom No.
rtmpurlYesstringAddress(es) for Stream Pushing to CDN (required). Separate multiple addresses with ,; you may specify up to five addresses
streamtypeYesuint32Stream type: 1=mixed stream pushing, 2=source stream pushing
taskidRequired when pushing mixed streamsstringStream mixing task ID, which is unique
mixconfigRequired when pushing mixed streamsJSONVideo mixing configuration
uidRequired when pushing source streamsstringUser ID

mixconfig

ParameterRequiredData TypeDescription
inputNoJSONInput parameter; an array in JSON format; not required when using a template ID, see details in input
outputYesJSONOutput parameter in JSON format, see details in output
templateidNouint32Template ID:
1-horizontal layout
2-vertical layout
3-tiled layout
4-corner layout

Note:

Input stream information is not required when using a layout template. Layout templates are only applicable to co-hosting within a room; for cross-roomco-hosting, custom-set layout information for each uid.

  • Horizontal layout: the first user appears in the large upper window, while other users appear in small windows below. There may be two rows at most, each containing up to eight small windows, thus supporting the display of 17 users in total.
  • Vertical layout: the first user appears in the large-window picture at the left side, with other users in the small-window pictures at the right side. Two rows of small windows can be provided at most, each of which can contain 8 pictures. In total, 17 user pictures can be supported in the small windows.
  • Tiled layout: automatically adjust the size of each picture based on the number of users. The picture sizes of all users are the same, and 16 pictures (4 x 4) can be supported in total.
  • Corner layout: the first user occupies the whole large window, and one small window hovers at each corner. This layout supports four small windows at most, and includes five pictures in total.

input

ParameterRequiredData TypeDescription
uidYesstringAnchor user ID
roomidYesstringInput stream anchor’s publishing room. Current room ID is optional.
streamtypeYesintStream type: 0: audio/video, 1: video, 2: audio
layerYesintLayer (0 indicates the bottommost layer; 1 is the first layer up from the bottom, and so on)
pos_xYesintTop left corner x-coordinate (coordinate system: x-axis increases from left to right; y-axis increases downward). Optional for audio-only stream mixing
pos_yYesintTop left corner y-coordinate. Optional for audio-only stream mixing
pos_hYesintHeight in canvas. Optional during audio-only stream mixing
pos_wYesintWidth in canvas. Optional during audio-only stream mixing
cropNointZoom options, 0: input stream display is centered and surrounded by a black border; 1: the screen is filled as much as possible by centering and clipping
cutout_xNointIf input is a cutout from the original, the cutout area's x-coordinate in the original
cutout_yNointIf input is a cutout from the original, the cutout area's y-coordinate in the original
cutout_hNointIf input is a cutout from the original, the cutout area's height
cutout_wNointIf input is a cutout from the original, the cutout area's width
alphaNofloatThe transparency level of the video frame, value range: [0.0, 1.0]
"0.0"- Completely transparent
"1.0:"-Opaque

output

ParameterRequiredData TypeDescription
streamtypeYesintStream type: 0: audio/video, 1: video, 2: audio
videoheightNointVideo height (required for video streams), a multiple of 8
Value range: (0-10000), recommended value: 600
videowidthNointVideo width (required for video streams), a multiple of 8
Value range: (0-10000), recommended value: 800
videobitrateNointVideo bit rate (kbps) (required for video streams)
Value range: (0-10000), recommended value: 800
videofpsNointVideo frame rate (required for video streams), the server will set it to 60 if the current value is higher than 60
Value range: (0-60), deaflut value: 15, unit: fps
videogopNointVideo GOP in frames (required for video streams), which is a multiple of videofps
Value range: (0-1000), default value: 30, unit: fps
videoencodeNointVideo code (required for video streams)
"100"-H264 (default), "101"-H265
audiobitrateNointAudio bit rate (kbps) (required for audio streams), filled with a fixed value of 64 and adjust situationally according to the audioencode value.
audiochannelNointNumber of audio tracks (required for audio streams), filled with a fixed value of 2
audiosampleNointAudio sampling rate (required for audio streams), filled with a fixed value of 44100
audioencodeNointAudio code (required for audio streams); 1=AAC+; 35=AAC (128kbps); recommended value: 1
patchNointVideo frame interpolation method: 0-no frame interpolation; 1-interpolation by black screen; 2-interpolation of the last frame; 3-interpolation by specified picture
patchUrlNostringFor frame interpolation method=3, specify the picture address not exceeding 256 bytes in length
seilayoutNointSEI video mixing option. When seilayout=1, enter the video source stream layout information into the SEI field for mixed stream video
watermarkNoJSONWatermark types, see details in watermark
backgroundNoJSONBackground, include color and picture
base64seidataNostringSEI encoded in Base64, maximum size: 2048 bytes

watermark

ParameterRequiredData TypeDescription
timestampNoJSONTimestamp watermark, see details in timestamp
textListNoJSON ArrayText watermark , see details in textList
imageListNoJSON ArrayImage watermark, see details in imageList

timestamp

ParameterRequiredData TypeDescription
xYesintThe x coordinate of the watermark (taking the top left corner as the origin), range: (0,10000)
it should be less than videowidth of output paramter
yYesintThe y coordinate of the watermark (taking the top left corner as the origin), range: (0,10000)
it should be less than videoheight of output paramter
formatYesstringSupported time formats:
"%Y/%m/%d"
"%Y-%m-%d"
"%H:%M:%S"
"%Y/%m/%d %H:%M:%S"
"%Y-%m-%d %H:%M:%S"
fontNostringFont, default value: NotoSansCJK
sizeYesintFont size, range: (0,100]
colorNostringFont color in RGB format, range: [000000, FFFFFF], default: FFFFFF (white)
backgroundColorNostringBackground color in RGB format, range: [000000, FFFFFF], default: 000000 (black)
alphaNofloatThe transparency level of the video frame, value range: [0.0, 1.0]
"0.0"- Completely transparent
"1.0:"-Opaque

textList

ParameterRequiredData TypeDescription
xYesintThe x coordinate of the watermark (taking the top left corner as the origin), range: (0,10000)
it should be less than videowidth of output paramter
yYesintThe y coordinate of the watermark (taking the top left corner as the origin), range: (0,10000)
it should be less than videoheight of output paramter
contentYesstringContent
fontNostringFont, default value: NotoSansCJK
sizeYesintFont size, range: (0,100]
colorNostringFont color in RGB format, range: [000000, FFFFFF], default: FFFFFF (white)
backgroundColorNostringBackground color in RGB format, range: [000000, FFFFFF], default: 000000 (black)
alphaNofloatThe transparency level of the video frame, value range: [0.0, 1.0]
"0.0"- Completely transparent
"1.0:"-Opaque

imageList

ParameterRequiredData TypeDescription
xYesintThe x coordinate of the watermark (taking the top left corner as the origin), range: (0,10000)
it should be less than videowidth of output paramter
yYesintThe y coordinate of the watermark (taking the top left corner as the origin), range: (0,10000)
it should be less than videoheight of output paramter
widthYesintImage width, which should be less than videohwidth of output paramter, range: (0,10000)
heightYesintImage height, which should be less than videoheight of output paramter, range: (0,10000)
urlYesstringImage URL, maximum length: 256 bytes
scaleYesintZoom mode / cropped mode:
0-Uniformly scales the video until it fills the visible boundaries (cropped)
1-Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit)
alphaNofloatThe transparency level of the video frame, value range: [0.0, 1.0]
"0.0"- Completely transparent
"1.0:"-Opaque

background

ParameterRequiredData TypeDescription
colorNostringBackground color in RGB format, range: [000000, FFFFFF], default: 000000 (black)
imageNoJSONBackground image, only image is valid when both image and color are set

image

ParameterRequiredData TypeDescription
urlYesstringURL of the background image, maximum length: 256 bytes
scaleYesintZoom mode / cropped mode:
0-Uniformly scales the video until it fills the visible boundaries (cropped)
1-Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit)

Note:

The traceId tag is unique.
You do not need to set video mixing parameters for source stream pushing.
In mixed stream pushing scenarios, a streamtype output parameter of 2 enables audio-only stream pushing.
If a taskid already exists in a mixed stream pushing scenario, calling it will trigger a parameter update.
A default stream pushing task configuration is supported according to Appid levels. Contact customer support if you require this service.

startrtmp Sample Request

  • Request URL:
https://api.jocloud.com/app/1470236061/v2/rtmpforward/startrtmp?traceId=biz201909121223210013
  • Request body contents
{
    "appid":1470236061,
    "roomid":"123",
    "rtmpurl":"rtmp://aliyunbiz.upstream.biz.com/live/test",
    "streamtype":1,
    "taskid":"biz007",
    "mixconfig":{
        "input":[
            {
                "uid":"111",
                "roomid":"123",
                "streamtype":0,
                "layer":0,
                "pos_x":0,
                "pos_y":0,
                "pos_h":600,
                "pos_w":400,
                "crop":0
            },
            {
                "uid":"222",
                "roomid":"123",
                "streamtype":0,
                "layer":1,
                "pos_x":400,
                "pos_y":0,
                "pos_h":600,
                "pos_w":400,
                "crop":0
            }
        ],
        "output":{
            "streamtype":0,
            "videoheight":600,
            "videowidth":800,
            "videobitrate":800,
            "videofps":24,
            "videogop":3,
            "videoencode":100,
            "audiobitrate":64,
            "audiosample":44100,
            "audiochannel":2,
            "audioencode":1
        }
    }
}

startrtmp Sample Response

{
    "code": 0,
    "message": "success",
    "traceId": "23116613407505472693518435"
}
  • code: int, Response Code.
  • message: a string; any situation other than “success” will contain error details.
  • traceId: a string; traceId carried by a request; convenient for tracing

Stop Pushing Streams to CDN: stoprtmp

Stop the active pushing streams to CDN task

  • 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}/v2/rtmpforward/stoprtmp?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”

Parameters:

ParameterRequiredData TypeNotes
appidYesuint64Service application ID
roomidYesstringRoom No.
streamtypeYesuint32Stream type: 1=mixed stream pushing, 2=source stream pushing
taskidMixed stream pushing (required)stringStream mixing task ID, is the corresponding active stream pushing task’s taskid
uidSource stream pushing (required)stringUser ID, is the corresponding active stream pushing task’s uid

Note:

A default stream pushing task configuration is supported according to Appid levels. Contact customer support if you require this service.

stoprtmp Sample Request

  • Request URL:
https://api.jocloud.com/app/1470236061/v2/rtmpforward/stoprtmp?traceId=biz201909121223210014
  • Request body contents
{
   "appid":1470236061,
   "roomid":"123",
   "streamtype":1,
   "taskid":"biz007"
}

stoprtmp Sample Response

  • Response body contents
{
    "code": 0,
    "message": "success",
    "traceId": "82719231231166134075054726935"
}
  • code: int, Response Code.
  • message: a string; any situation other than “success” will contain error details.
  • traceId: a string; traceId carried by a request; convenient for tracing

Response Code

EncodeDescriptionNote
0SucceededRequest succeeded
1000No token permissionNo token in the service API header
1001Invalid tokentoken format and/or content is incorrect
1002No appidNo appid
2101Invalid parameterInvalid API parameter
2102Abnormal stream statusAbnormal stream pushing status
2103TimeoutRequest timeout
2104Internal errorInternal server error

Stream Pushing Address

Stream Pushing Authentication

Before enabling stream pushing to CDN, make sure that the third-party service has enabled address authentication. Then, check to make sure the streams pushing address has a valid authentication code. After stream pushing failure, refresh the authentication code and push streams again.

Update Address

Update the stream pushing address in full mode. Any preexisting stream pushing tasks not recorded in the new address list will be stopped, and any preexisting tasks given updated addresses in the new address list will be added to the stream pushing task

Sample Address

rtmp://upstream.jocloud.com/live/test?auth_key=1585626386-0-0-8032e26583c58344e43cce3e251173b7

Stream Pushing Callback

The server returns push stream content and statuses by setting a callback address during stream pushing. The service has direct access to CDN callback; however, CDN callback generally only comes after the initial success. It is recommended that you connect your service to Jocloud's stream pushing callback. Contact Jocloud customer support to set up.

Stream Pushing Callback Returning Parameters

ParameterData typeDescription
urlstringStream pushing address
appnamestringApplication name
streamnamestringStream pushing name
appiduint64Service application ID
roomidstringRoom No.
taskidstringTask ID, is the taskid of the corresponding active stream pushing task
statusuint32Stream pushing status code. See the list of stream pushing callback status codes
versionuint64Callback version
errcodeuint32Error code, see details in [Error Codes](#Error Codes)
descriptionstringDetails

Status Codes

CodeDescription
3000Normal stream pushing. This code sends periodically.
3001Audio/video streams cannot be pulled. Check uplink audio/video streams in the channel. This code sends periodically.
3002Abnormal interruption of stream pushing. This code sends periodically.
3003Stream pushing terminated

Error Codes

CodeDescription
0Normal
1Incorrect URL format
2The concurrency limit is reached
3Timed out
1001TCP connection break
1002TCP connection failed
1003RTMP push stream is rejected, please check whether the authentication parameter or the push stream name is repeated
2001The stream pushing stopped
2002The data to be pushed does not exist
2003Internal error in the stream-pushing server

Note: Access to the stream pushing callback service requires background configuration. Contact customer support if you require this service.

Common Callback Errors

The following only introduces common status codes for stream pushing callback. Contact customer support if you encounter additional errors.
3001: audio/video streams cannot be pulled—typically due to an anchor uplink or publishing malfunction. The service side should check anchor status.
3002: stream pushing is interrupted—typically due stream pushing address authentication error or repeated pushing. The service side should check the stream pushing address.

<