CDN加速

文档中心 直播分发 云导播API

云导播API

更新时间：2021-10-14 15:56:02

一． 概述

  在传统电视节目的制作中，导播台是必不可少的设备，由专业的导播操作人员进行多角度，多景别的控制，使得制作的节目更加丰富，更加全面。传统的导播台主要由切换台、内部通话系统、监视器和一体化供电系统等设备组成，不仅结构操作复杂，设备成本昂贵，而且需要专业的导播进行操作，而需要具备这些条件去制作一档节目，对于非专业电视制作媒体来说，几乎是不可能完成的任务。为了顺应直播大潮流，解决传统导播台昂贵，复杂的特性。网宿推出云导播功能，将导播台“云”化，在云端完成传统导播的所有操作，而且价格低廉，随用随启，契合直播行业普遍架构，给直播平台在制作娱乐化直播内容，减少同质化方面提供巨大帮助。

二． 使用说明

2.1云导播API权限控制

  网宿云导播功能分为网宿云导播操作台和网宿云导播API两种实现方式，本篇主要描述如何通过网宿云导播API实现导播操作，为保证产品服务质量和安全，规范API调用的方式，所有接口都需要经过鉴权方可使用，具体分为实例创建接口①调用的用户鉴权和实例控制类接口②调用的控制鉴权，实例创建接口鉴权单独阐述，实例控制类鉴权具有一般共性，在此统一说明API权限控制：
  每个实例控制类接口调用时需在请求头Header中，声明鉴权字段（X-Direct-InstanceId，X-Direct-Token）

  参数说明

字段名称 字段类型 字段含义 必填 举例 备注
X-Direct-InstanceId 字符串 当前实例ID 是 20170426101849595 实例创建接口返回的id
X-Direct-Token 字符串 当前实例Token 是 4M0VKMTQ5MzE5OTkzMDk5OQ== 实例创建接口返回的token

  调用示例

  导播控制：单音画模式接口
  POST请求（Content-Type: application/x-www-form-urlencoded）
  URL: http://console.direct.chinanetcenter.com/v1/20170426101849595/control/single
  HTTP HEADER: X-Direct-InstanceId: 20170426101849595
  X-Direct-Token: 4M0VKMTQ5MzE5OTkzMDk5OQ==
  参数（键值对）： videoIndex=1 audio=80

2.2 创建导播实例

  API 地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/api/create

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
instanceName String 实例名称 是 new-instance
inputSize Int 最大输入流个数 是 4，受限于用户账号的inputLimit
endTime Long 结束时间13位Unix时间戳 是 1493198175999
userId String 用户名（portalId） 是 Zhangsan
callBackUrl String 错误回调地址 是 http://www.a.com/callback
defaultOut String 默认推流地址，用于展示导播画面 否（使用预监功能时为必须） rtmp://push.a.com/live/test
random Long 当前Unix时间戳，13位 是 13位当前unix时间戳（时间误差校验：前后半小时内），如：1493178124001
sign String 签名MD5(userId+secretKey+ random) secretKey需要申请获取 是 假设申请到的secretKey=jiskdsd0sdhuhu MD5(Zhangsanjiskdsd0sdhuhu1493178124001)
isPreviewMode bool 是否开启预监模式：true开启，false不开启； 否 false false 若需要开启预监模式，必须设置defaultOut参数，且inputSize必须小于等于6
enableAutoClose bool 是否启用输入源空闲时关闭实例功能 否 true true
watchCode String 需要回调业务码 否 1xxx,2xxx,3xxx watchCode=1xx,1xxx,2xxx，则该实例100-199业务码，同理，此类业务码会回调给 callBackUrl，具体回调内容见2.3信息回调

  调用示例

  POST http://console.direct.chinanetcenter.com/api/create
  PARAM(json)

{
“instanceName”:”testInstance”,
“inputSize”:4
“endTime”:1493198175999,
“userId”: “Zhangsan”,
“callBackUrl”: “http:// www.wstest.com/callback”,
“defaultOut”: “rtmp://push.a.com/live/live-123”,
“random”: 1493178124001,
“sign”: “6a26eb13afdb05684f886c5d743d4ed4”
“isPreviewMode”: false
“enableAutoClose”:true
}

  Json返回

{
“code”:1,
“msg”:”success”,
“content”: {
    "id": " UlnskUYh_20170426101849595",
    "userId": "Zhangsan",
    "size": 4,
    "createDate": 1493173129595,
    "startTime": 1493173129595,
    "endTime": 1493198175999,
    "name": "new-instance",
    "callBackUrl": "http://www.wstest.com/ callback ",
"type": “API”,
"token":jUxNTU4MDg1MzMzSENETkY1Ulo4M0VKMTQ5MMDYyMDAwMA”,
    "appCode": null,
    "taskid": null,	
"consoleUrl": null	
“defaultOut”: “rtmp://push.a.com/live/live-123”
 }
}

  字段说明

字段名称 字段类型 字段含义
code Int 返回码：1：成功，1xx-6xx：http错误对应的状态码，1000：请求参数错误，2000：无权限（含未授权、实例个数超过、输入流个数超过限制），3000：系统异常
msg 字符串 成功或错误信息
content Map code=1（即成功），返回实例的具体信息，失败时为null，主要关注返回的实例id和token，用于实例控制类接口鉴权。

2.3 导播控制之单音画模式

  API地址

  HTTP POST请求，Content-Type:application/x-www-form-urlencoded，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/control/single
  URL PATH参数：{instanceId}替换成创建实例接口返回的实例id
  备注：本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
videoIndex Int 需要显示的输入源顺序，从 1开始 是 1
audio Int 音量大小0-100 是 90

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/control/single
  PARAM(key-value) videoIndex=1 audio=90

2.4 导播控制之混合音画模式

  API地址

  HTTP POST请求，Content-Type:application/x-www-form-urlencoded，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/control/mingle
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  备注：本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
videoIndex String 混合音画的输入源，若是两个的话，英文逗号分隔 是 只设置单个输入源，则：1。设置2个输入源（大小窗，前面一个是大窗），则：4,3
audios String 音量大小0-100，逗号分隔，数量与输入源个数相同 是 总共4个输入源，则50,60,70,80

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/control/mingle
  PARAM(key-value) videoIndex=4,3 audio=50,60,70,80

2.5 导播控制之会议模式

  API地址

  HTTP POST请求，Content-Type:application/x-www-form-urlencoded，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/control/meeting
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  备注：本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
videoIndex String 会议模式的4路流显示顺序 是 4,3,2,1
audios String 音量大小0-100，逗号分隔，数量与输入源个数相同 是 总共4个输入源，则50,60,70,80

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/control/meeting
  PARAM(key-value) videoIndex=4,3,2,1 audio=50,60,70,80

2.6 导播控制之自定义模式

  API地址

  HTTP POST请求，Content-Type:application/x-www-form-urlencoded，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/control/custom
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  备注：本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
templateId String 使用的模板id，需先添加模板定义后才能使用，具体见2.6.1 是 1
audios String 音量大小0-100，逗号分隔，数量与输入源个数相同 是 如输入源总数为4个，则50,60,70,80

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/control/custom
  PARAM(key-value) templateId=“1” audios=“50,60,70,80”

2.6.1 新增/修改自定义模板

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/template
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  备注：本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
模板数组 Object[] 传入需要新增或修改的模板参数，支持多个（数组形式） 是
id string 模板id 是 无 若该id在服务端不存在，将新增，否则将覆盖修改
name string 模板名称 是 无
videoIndex int 第几输入源 是 无 输入源index从1开始
zoomSize int 缩放比例 是 无 缩放比例范围[1-100]
positionX int 视频定位X轴位置 是 无 输出源左上角为原点范围值为0-100
positionY int 视频定位Y轴位置 是 无 输出源左上角为原点范围值为0-100
videoResolution float 分辨率比例 是 无 计算方式=高度/宽度，如视频分辨率为1280*720则720/1280=0.5625
resolutionX float 宽度占比 是 无 如1280*720，则为1280
resolutionY float 高度占比 是 无 如1280*720，则为720

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/template
  PARAM(json)

[				
    {	//第一个模板
        “id”: “1”, 
        “name”: “template1”, 
        “templateItemList”: [   //模板配置项数组
           {//第一个模板配置项，视频层级最高（层级高的视频将覆盖层级低的视频）
                “videoIndex”: 2, 
                “zoomSize”: 50, 
                “positionX”: 50, 
                “positionY”: 50, 
				  “videoResolution”: 0.5625,  
				  “resolutionX”: 1280,
“resolutionY”: 720
            },
            {	//第二个模板配置项，视频层级次于最高级
               “videoIndex”: 3, 
                “zoomSize”: 100,
                “positionX”: 0,
                “positionY”: 0,
				  “videoResolution”: 0.5625,
				  “resolutionX”: 1280,
“resolutionY”: 720
            }
        ]
    },
    {	//第二个模板
        “id”: “2”,
        “name”: “template2”,
        “templateItemList”: [
            {
                “videoIndex”: 3,
                “zoomSize”: 100,
                “positionX”: 0,
                “positionY”: 0,
				“videoResolution”: 0.5625,
				“resolutionX”: 1280, 
				“resolutionY”: 720
            },
            {
                “videoIndex”: 4,
                “zoomSize”: 50,
                “positionX”: 50,
                “positionY”: 50,
				“videoResolution”: 0.5625,
				“resolutionX”: 1280, 
				“resolutionY”: 720
            }
        ]
    }
]

2.6.2 删除自定义模板

  API地址

  HTTP DELETE请求，Content-Type:application/x-www-form-urlencoded，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/template/{templateId}
  URL PATH参数：{instanceId}替换成创建接口返回的实例id，{templateId}替换成模板的id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  调用示例

  DELETE http://console.direct.chinanetcenter.com/v1/20170426101849595/template/1

2.6.3 查询自定义模板

  API地址

  HTTP GET请求，Content-Type:application/x-www-form-urlencoded，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/template/{tempalteId}
  URL PATH参数：{instanceId}替换成创建接口返回的实例id，{tempalteId}替换成模板的id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  调用示例

  查询具体的模板：
  GET http://console.direct.chinanetcenter.com/v1/20170426101849595/template/{tempalteId}
  查询全部的模板：
  GET http://console.direct.chinanetcenter.com/v1/20170426101849595/template
  {tempalteId}表示具体的模板id

2.7 导播控制之弹幕功能

2.7.1 弹幕配置

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/barrage
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
type String 弹幕模式 否 1 0字幕 1弹幕 2滚动弹幕
loopType String 循环类型 否 0 0自定义 1无限
loop Int 循环次数 否 1 1
position String 弹幕位置 否 top Top 顶部 bottom 底部
duration Int 存留时间 否 5 范围[0-25]，单位秒
transparency Int 透明度 否 50 范围[0-100]
size 字号 否 lit big大 mid中 lit小
color String 颜色 是 #333333
bold String 加粗 否 0 0 不加粗 1 加粗
stroke String 描边 否 0 0 不描边 1描边
strokeColor String 颜色 是 #333333

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/barrage
  PARAM(json)

{
  “type” : “1”,
  “loopType” : “0”,
  “loop” : 1,
  “position” : “top”,
  “duration” : 5,
  “transparency” : 50,
  “size” : “lit”,
  “color” : “#333333”,
  “bold” : “0”,
  “stroke” : “0”,
  “strokeColor” : “#333333”
}

2.7.2 弹幕发送

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/barrage/send
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
text String 弹幕内容 是 Just for a test
output String 弹幕输出模式: 0表示输出到预监画面，1表示输出到观众画面，2表示都输出 否 1 1。当未开启预监时，或预监关闭时，弹幕输出模式只能为1

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/barrage/send
  PARAM(json)

{
  “text” : “Just for a test”
“output”:2
}

2.7.3 清除弹幕

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/barrage/sendClear
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
output String 弹幕输出模式:0表示输出到预监画面，1表示输出到观众画面，2表示都输出 否 1 1 当未开启预监时，或预监关闭时，弹幕输出模式只能为1

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/barrage/sendClear
  PARAM(json)

{
“output”:2
}

2.8 导播控制之水印功能

2.8.1 水印添加

  API 地址

  HTTP POST请求，Content-Type:application/json，
  URL:http://console.direct.chinanetcenter.com/v1/{instanceId}/watermark/{watermarkId}
  URL PATH参数：{instanceId}替换成创建接口返回的实例id，{watermarkId}替换为水印id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
id int 水印id 是 无 1
name String 水印名称 是 无 台标
url String 水印地址 是 无 http://ws.com/logo.png
fixedPosition String 常用位置 否 无 可选值： TOP_LEFT,TOP_CENTER, TOP_RIGHT, CENTER_LEFT, CENTER, CENTER_RIGHT, BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT
customPixel Obj 自定义偏移量 否 无 单位像素点 {x:10,y:10}
customPercent Obj 自定义偏移量 否 无 单位百分比 {x:5,y:5}
transparency Int 透明度 否 0 数值范围[0-100]
scaling double 原图缩放比 否 0 数值范围[0-1],精确到小数点后两位
adaptation Int 是否自适应 否 1 0 不自适应1 自适应

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/watermark/1
  PARAM(json)

{
  “adaptation”: 1,
  “customPercent”: { “x”:10, “y”:10},
  “id”: 1,
  “name”: “台标”,
  “scaling”: 0.50,
  “transparency”: 0,
  “url”: “http://***.png”
}

2.8.2 水印转码合成

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/watermark/effect
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
watermarkIds String 水印id串 是 无 1,2

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/watermark/effect?watermarkIds=2,3

2.8.3 水印删除

  API地址

  HTTP DELETE请求，Content-Type:application/json，
  URL:http://console.direct.chinanetcenter.com/v1/{instanceId}/watermark/{watermarkId}
  URL PATH参数：{instanceId}替换成创建接口返回的实例id，{watermarkId}替换为水印id。
  本接口需要鉴权，详见2.1 API权限控制【通用】

  调用示例

  DELETE http://console.direct.chinanetcenter.com/v1/20170426101849595/watermark /1

2.9 导播控制之视频抠图

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/cutout
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
operation String 操作开关 是 无 on 开启 off 关闭
color String 颜色 是 无 0x222222
similarity String 相似度 是 无 设置一个百分比[1-100]，当像素的颜色与指定颜色的相似度达到该值时被替换。1为完全相同， 100为匹配任何颜色
coherence String 透明度 是 无 设置一个百分比[0,100]，当值越小则越不透明，100为全透明

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/cutout
  PARAM(json)

 
[
	{  
		“operation” : “on”,
        “color” : “0x222222”,
		“similarity”: 50, 
		“coherence”: 50, 
    },
    {同1}, //输入源2
    {同1}, //输入源3
    {同1} //输入源4
]

2.10 导播控制之转场特效

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/effect
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
operation String 操作 是 无 0.clear（清除）；1.dissolve（化入）--透明度渐变；2.delimit（划入）---视频切入；3.erase（擦除）---视频模糊切入
position String 位置 是 无 TOP;LEFT;RIGHT;BOTTOM;TOP_LEFT;TOP_RIGHT;BOTTOM_LEFT;BOTTOM_RIGHT;
duration Int 指视频切换特效在整个视频画面的存留时间 是 无 单位秒 ,取值范围[1,5]

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/effect
  PARAM(json)

{
	“operation” : “dissolve”, 
	“position” : “TOP”, 
	“duration” ：2
}

2.11 导播控制之导播延时

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/config/delay
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
delayTime Long 延长时间， 是 无 取值范围[1800000,10800000]，单位毫秒

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/config/delay
  PARAM(json)

{
	“ delayTime “ : 180000
}

2.12 导播控制之输入配置API

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/source/input/{index}
  URL PATH参数：
  {instanceId}替换成创建接口返回的实例id（如：20170426101849595）
  {index}为输入源的顺序，从1开始（如设置第一路流的输入源，则：1）
  备注：本接口需要鉴权，详见2.2 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
type String 视频类别: 0直播 1点播 是 0
url String 拉流地址 是 http://www.a.com/video.flv
buffertime Int 缓冲时间 秒 是 2
maxbuffertime Int 最大缓冲时间 秒 是 2

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/source/input/1
  PARAM(json)

{
  "buffertime": 0,
  "maxbuffertime": 0,
  "type": "0",
  "url": "http://www.a.com/video.flv"
}

2.13导播控制之输出配置API

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/source/output
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  备注：本接口需要鉴权，详见2.2 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
cbr String cbr 0关闭 1开启 是 0
fps Int 帧率fps 是 30
qualityvalue String 视频质量:固定值custom 是 custom
rate Int 码率 Kbps 是 2000
size String 分辨率 是 1280x720，x为小写字母x
urlList 字符串数组 输出源url列表 是 [http://a.com/out,http://b.com/out,“http://c.com/out”]
delay Int 延迟播放，单位秒，范围：0-60 否 0 3

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/source/input/1
  PARAM(json)

{
  "cbr": "0",
  "fps": 30,
  "qualityvalue": "custom",
  "rate": 2000,
  "size": "1280x720",
  "urlList": ["http://a.com/out", "http://b.com/out", "http://c.com/out"]
“delay”: 3
}

2.14 导播控制之输出自定义

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/control/defaultOut
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  本接口需要鉴权，详见2.1 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
controlItemList json数组 传入合成视频位置及每个输入源的位置参数 所有属性值必填 属性不传或传空字符等场景下，默认值为0 数组长度为输入源个数+1；假设实例最大输入源个数为4，则数组长度为5（第一个是合成视频位置，后面4个为对应的输入源位置）
w 宽度 是 无 权量值（0-100），50表示输出宽的一半;支持不超过6位小数点
h 高度 是 无 权量值（0-100），50表示输出高的一半;支持不超过6位小数点
x X轴偏移量 是 无 以左上角为坐标原点，权量值（0-100），50表示横轴的中间位置
y Y轴偏移量 是 无 权量值（0-100），50表示纵轴的中间位置
z 叠加次序 是 无 范围：-1-100，-1不显示，0为最下面，值越大越上面

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/control/defaultOut
  PARAM(json)

{
    “controlItemList”:
  [
    { 	//启用预监模式时，第一个控制项是预监画面位置
        “w”: 91.9, //宽度，权量值（0-100），50表示输出宽的一半；支持不超过6位小数点，下同
        “h”: 63.2, //高度，权量值（0-100），50表示输出高的一半 
        “x”: 4.1, 	//x轴偏移量，以左上角为坐标原点，权量值（0-100），50表示                        横轴的中间位置
        “y”: 8.2, 	//y轴偏移量，权量值（0-100），50表示纵轴的中间位置
        “z”: 0 //叠加次序，范围：-1-100，-1不显示，0为最下面，值越大越上面
},
{	//启用预监模式时，第二个控制项是用户输出画面位置
        “w”: 23.2,
        “h”: 16,
        “x”: 1.4,
        “y”: 77.6,
        “z”: 0
    },
    {	//第1个输入源对应的位置
        “w”: 23.2,
        “h”: 16,
        “x”: 1.4,
        “y”: 77.6,
        “z”: 0
    },
    {	//第2个输入源对应的位置
        “w”: 23.2,
        “h”: 16,
        “x”: 26.1,
        “y”: 77.6,
        “z”: 0
    },
    {	//第3个输入源对应的位置
        “w”: 23.2,
        “h”: 16,
        “x”: 50.7,
        “y”: 77.6,
        “z”: 0
    },
    {	//第4个输入源对应的位置
        “w”: 23.2,
        “h”: 16,
        “x”: 75.4,
        “y”: 77.6,
        “z”: 0
    }
]
}

2.15 停止导播API

  API地址

  HTTP POST请求，Content-Type:application/x-www-form-urlencoded，
  URL: http://console.direct.chinanetcenter.com/v1/{instanceId}/config/stop
  URL PATH参数：{instanceId}替换成创建接口返回的实例id
  备注：本接口需要鉴权，详见2.2 API权限控制【通用】

  调用示例

  POST http://console.direct.chinanetcenter.com/v1/20170426101849595/config/stop

2.16 实例控制类接口返回说明

  json返回值

{
  "code": 1,
  "msg": "success",
  "content": "123456789"
}

  字段说明

字段名称 字段类型 字段含义
code Int 返回码：1：成功，-1: 操作失败，1xx-6xx：http错误对应的状态码，1000：请求参数错误，2000：无权限（含未授权、实例个数超过、输入流个数超过限制），3000：系统异常
msg 字符串 成功或错误信息
content Map 预留参数信息

2.17 错误回调接口

  当发生客户操作失败、输入/输出源异常等一些错误时，会通过2.2实例创建接口填写的callBackUrl（错误回调地址）回调具体的错误信息；
  HTTP POST请求，Content-Type:application/json，
  URL: callBackUrl （如：http://www.a.com/callback )
  请求参数（json）

 
{
    "success": false,
    "instanceId": “20170426101849595”,
    "code": 1001,
"msg": “input source failed”,
“index”: 2
“id”:17678234888,
“flag”:0
“url”:”rtmp://direct.com/live/test”,
“info”: {"resolution": "1920x1080", "videoRate":800, "frameRate": 30, "type":0，"duration":100}
}

  请求参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
success bool 操作是否成功 是 False,true
instanceId String 导播实例ID 是 20170426101849595
code Int 错误码 是 1001，具体错误码说明具体给出
msg String 错误消息 是 “input source failed”
index Int 如果错误有涉及到具体的输入或者输出流，会显示具体是哪一路流异常 是 如果第二路流异常，则index值为2 如果错误不涉及具体的流，则index为null
id Int 水印的异常会告知哪个id的异常 否 如果水印id=23的图片加载不了，则会回调id=23，code=1005
flag Int 回调类别 是 0代表正常模式回调，1代表预监模式回调
url String 引用地址 否 当前只有当101,102业务码时，才会携带该参数表明推流或拉流成功的具体地址
info Map 输入源信息 否 type表示输入源类型，0表示点播，1表示直播。duration表示文件时长，单位秒，只在type为0时有意义（type为1时，不回调该字段或者该字段值默认为-1，接收方忽略该值）

  错误码说明

错误码 含义 是否有index参数
1001 输入流无法获取 有
1002 导播台输出无法连接 无
1003 输出源无法连接 有
1004 参数设置有误 无
1005 水印图片加载失败 如果生效水印的图片解析不了，则会回调code=1005，id=出错的水印id，多个水印无效会多次回调
3001 所有输入源已结束超过20分钟 所有输入源已结束超过20分钟，需要客户确认是否关闭实例。注意：回调客户失败会自动关闭实例。

2.18 预监模式设置

  API地址

  HTTP POST请求，Content-Type:application/json，
  URL: http://$DirectApiDomain/v1/{instanceId}/control/preview
  URL PATH参数：{instanceId}替换成创建接口返回的实例id（如：20170426101849595）
  本接口需要鉴权，详见2.2 API权限控制【通用】

  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例 备注
previewStatus String 预监状态：on("启用"), off("停用"), syn("同步"); 是 无 on 启用预监模式on必须配置导播台推流地址。

  调用示例

  POST http://$DirectApiDomain/v1/20170426101849595/control/preview
  PARAM(json)

{
  "previewStatus": "on"
}

  返回值(json)

{
  “code”: 1,
  “msg”: “success”,
  “content”: “123456789”
}

  字段说明

字段名称 字段类型 字段含义
code Int 返回码：1：成功，-1: 操作失败，1xx-6xx：http错误对应的状态码，1000：请求参数错误，2000：无权限（含未授权、实例个数超过、输入流个数超过限制），3000：系统异常
msg String 成功或错误信息
content String code=1（即成功），返回本次操作的mid（接口预留）

2.19 视频处理：播放控制

  API地址
  HTTP POST请求，Content-Type:application/json，
  URL: http://$DirectApiDomain/v1/{instanceId}/source/playControl/{index}
  URL PATH参数：{instanceId}替换成创建接口返回的实例id（如：20170426101849595）
  {index}为输入源的顺序，从1开始（如设置第一路流的输入源参数，则：1）
  本接口需要鉴权，详见2.2 API权限控制【通用】
  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例 备注
startTime Int 播放开始位置，单位秒 点播输入源，必填 -1 0 1、点播输入源参数，当输入源为点播时填写。2、当系统未获取到点播文件时长时，不能配置startTime、endTime（允许设置为0、0，代表全文件播放）。
endTime Int 播放结束位置，单位秒 点播输入源，必填 -1 120
resume Int 播放模式：0断点续播，1从头播放（转码默认） 点播输入源，必填 -1 1
delay Float 设置输入源播放延迟，[0.0,5.0]s，默认不延迟(0.0)；单位秒，精确到小数点后1位。 直播输入源，必填 -1.0 3.5 1、直播输入源参数，当输入源为直播时填写。2、输入源基准只允许存在1个。
datum Int 设置当前输入源为基准，其他输入源向基准进行延迟同步。0否（转码默认）， 1是。 直播输入源，必填 -1 0

  调用示例
  POST http://$DirectApiDomain/v1/20170426101849595/source/playControl/1
  PARAM(json)
  a.假设输入源1为点播源，则请求参数如下：

 
{
    “startTime”: 0,
    “endTime”: 120,
    “resume”: 1
}

  b.假设输入源1为直播源，则请求参数如下：

 
{
    “delay”: 3.5,
    “datum”: 0
}

2.20 查询用户未结束实例

  API地址
  HTTP GET请求，Content-Type:application/x-www-form-urlencoded，
  URL: http://$DirectApiDomain/api/getAliveInstances
  本接口需要鉴权，详见2.2 API权限控制【通用】
  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
userId String 用户名（portalId） 是 Zhangsan
random Long 当前Unix时间戳，精确到毫秒，13位 是 13位当前unix时间戳（时间误差校验：前后半小时内），如：1493178124001
sign String 签名 MD5(userId+secretKey+ random) secretKey需要申请获取 是 假设申请到的secretKey=jiskdsd0sdhuhu MD5(Zhangsanjiskdsd0sdhuhu1493178124001) 如：6a26eb13afdb05684f886c5d743d4ed4

  调用示例
  GET http://$DirectApiDomain/api/getAliveInstances?userId=Zhangsan&random=1493178124001&sign=6a26eb13afdb05684f886c5d743d4ed4

2.21 场景（HTML5动态场景）

  添加修改
  API地址
  HTTP POST请求，Content-Type:application/json，
  URL: http://$DirectApiDomain/v1/{instanceId}/ h5scene/{ h5sceneId}
  URL PATH参数：{instanceId}替换成创建接口返回的实例id（如：20170426101849595），{h5sceneId}替换为场景id
  本接口需要鉴权，详见2.2 API权限控制【通用】
  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
id int 场景id 是 无 1
name String 场景名称 是 无 **台标
url String 场景地址 是 无 https://scene.aodianyun.com/zimu.php?sceneId=s_3e37295f863a26569c3c17c65df93435&user=9281

  调用示例
  POST http://$DirectApiDomain/v1/20170426101849595/h5scene/1

  PARAM(json)

{
  “id”: 1,
  “name”: “标准图标”,
  “url”: “https://scene.aodianyun.com/zimu.php?sceneId=s_3e37295f863a26569c3c17c65df93435&user=9281”
}

  转码合成
  API地址
  HTTP POST请求，Content-Type:application/json，
  URL: http://$DirectApiDomain/v1/{instanceId}/ h5scene/effect
  URL PATH参数：{instanceId}替换成创建接口返回的实例id（如：20170426101849595）
  本接口需要鉴权，详见2.2 API权限控制【通用】
  注:场景如果有重叠，根据传入的顺序，下面覆盖盖上面。
  参数说明

字段名称 字段类型 字段含义 必填 默认值 举例
h5sceneIds String 场景id串 是 无 1,2

  调用示例
  POST http://$DirectApiDomain/v1/20170426101849595/ h5scene /effect? h5sceneIds =2,3

  删除场景
  API地址
  HTTP DELETE请求，Content-Type:application/json，
  URL: http://$DirectApiDomain/v1/{instanceId}/ h5scene /{h5sceneId}
  URL PATH参数：{instanceId}替换成创建接口返回的实例id（如：20170426101849595），{h5sceneId}替换为场景id。
  本接口需要鉴权，详见2.2 API权限控制【通用】

  调用示例
  DELETE http://$DirectApiDomain/v1/20170426101849595/h5scene/1

三． 应用场景

  云导播功能使用场景广泛，在需要进行直播流切换的业务场景中都可以使用云导播的功能，下面列举一些经典使用场景。
  1. 小型发布会直播，多个视频画面切换，添加广告。
  2. 小型体育比赛多个视角进行切换输出。
  3. 体育、竞技赛事解说，解说员和赛事画面合成输出，出入广告。

四． 注意事项

  1. 需提前开通网宿portal平台账号。
  2. 需对portal账号进行授权，获取到对应鉴权密钥secretkey，流数限制inputLimit，实例限制onlineLimit，三个参数后才可以使用云导播API功能。
  3. 接口调用限制每分钟200次。

五． 附录解释

  ① 实例创建接口：导播实例API
  ② 实例控制类接口：单音画模式API、混合音画模式API、会议模式API、输入配置API、输出配置API、停止导播API

本篇文档内容对您是否有帮助？
有帮助
我要反馈
提交成功！非常感谢您的反馈，我们会继续努力做到更好！