RESTful API

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

API Overview

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

mixconfig

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

output

watermark

timestamp

textList

imageList

background

image

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:

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

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

Status Codes

Error Codes

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.