# 超级直播间Pro

# 功能介绍

待补充

# 超级直播间 API 说明

用户调用平台全部API服务，皆需要访问服务接入点：aigc.softsugar.com，并在请求头中加上token信息；WS接口需将token信息拼写到URL上。

# 直播时序图

【等待补充图】

# 新建直播间

# 接口描述

创建一路数字人直播实例，通过传入指定的参数系统进行初始化，并返回会话ID等信息供后续使用。如果初始化耗时过长将返回状态32，后续由回调或客户端查询进行完成状态的的更新。当状态为35时表示视频流初始化完成，可以操作开启直播。
web sample使用的播放方法为集成第三方SDK服务，具体可参考：三方SDK使用说明 (opens new window)。

注意：创建直播间即开始计时。

# 请求地址

POST /api/2dvh/v2/material/live/channel/create

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`param`	String	True	直播视频生成参数（该参数为json转义后的字符串）
`urtcUseExternalApp`	Boolean	False	是否使用用户声网rtc appId，如果不使用，将使用平台统一的rtc appId（默认否）
`urtcToken`	String	False	用户rtc鉴权token （使用用户rtc app时必填）
`urtcUid`	String	False	用户rtc鉴权uid （使用用户rtc app时必填，必须是大小不超过32uint的纯数字）
`urtcAppId`	String	False	用户rtc APP ID （使用用户rtc app时必填）
`urtcChannelId`	String	False	用户rtc Channel ID （使用用户rtc app时必填，长度不得超过 64 位）
`userData`	String	False	用户信息（回调时原样返回）

# 请求样例

{
  "param": "{\"version\":\"0.0.1\",\"recycle\":0,\"stream_mode\":true,\"sceneList\":[{\"digital_role\":{\"id\":1,\"face_feature_id\":\"0325_nina_s3_beauty\",\"name\":\"小李\",\"url\":\"https://dwg-aigc-paas-test.oss-cn-hangzhou.aliyuncs.com/materials/77/0325_nina_s3_beauty.zip\",\"position\":{\"x\":10,\"y\":60},\"scale\":1},\"tts_config\":{\"id\":\"nina\",\"name\":\"nina\",\"vendor_id\":3,\"language\":\"zh-CN\",\"pitch_offset\":0.0,\"speed_ratio\":1,\"volume\":400},\"tts_query\":{\"content\":\"商汤科技是一家行业领先的人工智能软件公司，以坚持原创，让AI引领人类进步为使命。\",\"ssml\":false},\"audios\":[{\"url\":\"http://dwg-aigc-paas.oss-cn-hangzhou.aliyuncs.com/test/softsugar.mp3\"}],\"backgrounds\":[{\"type\":0,\"name\":\"背景\",\"url\":\"https://dwg-aigc-paas.oss-cn-hangzhou.aliyuncs.com/test/background.png\",\"rect\":[0,0,1080,1920],\"cycle\":true,\"start\":0,\"duration\":-1}],\"foregrounds\":[{\"type\":0,\"name\":\"前景1\",\"url\":\"https://dwg-aigc-paas.oss-cn-hangzhou.aliyuncs.com/test/frontgroud.png\",\"rect\":[0,0,310,88],\"start\":0,\"duration\":100}],\"effects\":{\"version\":\"1.0\",\"beautify\":{}}}]}"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	False	直播开启是否成功
- `sessionId`	String	True	会话的唯一标识
- `sessionToken`	String	True	麦克风接管使用的token信息
- `status`	Integer	True	任务状态：32:视频流创建中, 35:视频流创建完成,9:异常,97：系统路数不足,98：客户路数不足
- `rtcAppId`	String	False	RTC APP ID （状态为32无此值）
- `rtcChannelId`	String	False	RTC Channel ID （状态为32无此值），长度不得超过 64 位
- `rtcUid`	String	False	RTC UID （状态为32无此值），必须是大小不超过32uint的纯数字
- `rtcToken`	String	False	RTC Token （状态为32无此值）

# 响应样例

   {
     "code": 0,
     "message": "success",
     "data": { 
               "sessionId": "sessionId",
               "sessionToken": "sessionToken",
               "status": 35,
               "rtcAppId": "rtcAppId",
               "rtcChannelId": "rtcChannelId",
                "rtcUid": "rtcUid",
                "rtcToken": "rtcToken"
             }
   }

# 直播状态监测

# 接口描述

用于保持直播持续，推荐每隔60秒调用一次该接口。心跳丢失时间超过阈值将被动关闭直播。

# 请求地址

POST /api/2dvh/v1/material/live/channel/heartbeat

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	True	会话的唯一标识

# 请求样例

{
  "sessionId": "sessionId"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	False	data object ，异常时通常为空

# 响应样例

   {
     "code": 0,
     "message": "success"
   }

# 开启直播

# 接口描述

启动一路数字人直播间实例，通过传入指定的参数，可以开启一路数字人直播推流实例，可通过三方RTC拉流SDK产品进行拉流使用。

# 请求地址

POST /api/2dvh/v1/material/live/channel/start

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	True	会话的唯一标识

# 请求样例

{
  "sessionId": "sessionId"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Boolean	False	直播开启是否成功

# 响应样例

{
  "code": 0,
  "message": "success",
  "data": true
}

# 直超级直播间Pro控制

# 接口描述

超级直播间Pro控制，用于直接控制直播间中的数字人切换，前景切换，背景切换。

注意：当前版本控制命令发送后，会返回接收成功/接受失败。满足触发条件后，会自动进行触发。目前无更多信息返回。

# 请求地址

POST /api/2dvh/v1/material/live/super/pro/channel/control

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	True	会话的唯一标识
`param`	String	True	接管内容（该参数为json转义后的字符串）

# 请求样例

{
  "sessionId": "sessionId",
  "param": "{\"digital_role\":\"aaaaaaa\",    \"backgrounds\":          {           \"file_id\": \"backgrounds\",           \"digital_role_file_id\":\"123321\",           \"rect\": [             0,             0,             1080,             1920           ],           \"start\": 0,           \"duration\": 123,           \"volume\":50         },   \"foregrounds\": [         {           \"file_id\": \"foregrounds\",           \"digital_role_file_id\":\"123321\",           \"rect\": [             0,             0,             310,             88           ],           \"start\": 0,           \"duration\": 100,           \"delay\": false,           \"volume\":50         }       ] }"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	True
- `commandStatus`	Integer	True	控制命令状态（入队状态）
- `commandTraceId`	String	True	控制命令TraceId

# 响应样例

{   
  "code": 0,
  "message": "success",
  "data": {
    "commandStatus": 34,
    "commandTraceId": "commandTraceId"
  }
}

# 直播接管排队（流式语音输入）

# 接口描述

注意：该接口为WebSocket接口，数据请求使用 json，编码使用 UTF8。其中流式声音要求传输格式为PCM格式，码率要求为16000，单声道，16bit采样率。发送流式语音信息（如来自麦克风，TTS流式接口等），数字人会基于实时语音进行接管操作，中断当时直播内容，生成新的画面并渲染视频流给到用户。

每一帧有大小需小于4k。 此外，所有http发起的接管，都会在此socket通道中返回对应的状态消息。正常情况下，每一次接管，都会依次下发“接管入队完成”， “开始接管“，“接管完成”。

超级直播间中，在发起接管时，可同步发送控制命令，用于数字人/前景/背景的切换。

# 请求地址

WebSocket /api/live-takeover-cc/v1/material/live/channel/command/microphone?clientType={clientType}&sessionId={sessionId}&Authorization={Token}

# 请求头

# 请求参数

字段	类型	必填	描述
`clientType`	String	True	连接端类型：BROWSER：生产端
`sessionId`	String	True	建立连接后返回唯一会话id
`Authorization`	String	True	该token为创建直播间返回的sessionToken

# 请求样例（上行消息）

字段	类型	必填	描述
`code`	Integer	True	消息编码
`message`	String	True	建立连接后返回唯一会话id
`commandTraceId`	String	True	接管ID。与http接管相似，但需调用方主动传入唯一ID，在直播内有效。并可以通过取消接管接口取消该次接管。仅在code=0，code=10，code=11，code=99时有效
`priority`	Integer	False	优先级,仅在code=0或10时有效（合法值区间1~n或-1，如果传入不合法，插入到队列最后，-1是自动排到队尾）
`superControl`	String	False	超级直播间Pro控制命令，转义后的json字符串。参考"超级直播间Pro接管json定义说明"

# 连接建立

wss://host/api/live-takeover-cc/v1/material/live/channel/command/microphone?clientType=BROWSER&sessionId=123&Authorization=MTZiMjQzMzg4ZTYyMTlkNTBjZWU0ODAxODg5N2MyY2NmMmQzNzNhOC04YzNiLTRlMjEtYmY3Mi0yNzA2YzFkMjg4ODA

# 流式PCM音频

# 开始接收流式PCM音频通知

    {
        "code": 0,
        "message": "begin",
        "commandTraceId": "xxxyyyzzz111333",
        "priority": 1
    }

# 语音数据

二进制语音数据，流式声音要求传输格式为PCM格式，码率要求为16000， 单声道，16bit采样率。

# 发送结束

    {
        "code": 99,
        "message": "eof",
        "commandTraceId": "xxxyyyzzz111333"
    }

# 响应元素

字段	类型	必填	描述
`code`	String	True	消息类型编码
`message`	String	True	详细信息

# 响应样例（下行消息）

# 认证失败

   {
        "code": 1,
        "message": "认证失败"
   }

# 服务端已准备好接收

   {
       "code": 2,
       "message": "准备发送数据"
   }

# http形式发起的接管（音频接管）完成/取消接管完成通知

   {
       "code": 18,
       "message": "接管/取消接管完成",
       "data": {
            "sessionId": "xxxxx",
            "commandTraceId": "yyyyyy",
            "timestamp": 1234567890
        }
   }

# 未匹配或算法连接中断

   {
       "code": 4,
       "message": "停止发送数据"
   }

# 未知原因失败

   {
        "code": 5,
        "message": "发送数据失败"
    }

# 没有对应的直播信息

   {
       "code": 6,
       "message": "服务端未准备好接收"
   }

# 发送的流式接管出现错误，接管冲突给前端发拒绝消息

   {
        "code": 7,
        "message": "算法端接管冲突被拒绝"
   }

# webSocket形式发起的接管（音频接管）的消息接收成功通知(目前只响应消息 99 eof)

   {
      "code": -1,
      "message": "接管消息ACK",
      "data": {
        "sessionId": "xxxxx",
        "code": 99,
        "commandTraceId": "yyyyyy",
        "timestamp": 1740998208131
      }
    }

# 关闭直播

# 接口描述

关闭一路状态为进行中的数字人直播间实例，停止数字人推流关闭直播，释放相关资源。

# 请求地址

POST /api/2dvh/v1/material/live/channel/close

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	True	会话的唯一标识

# 请求样例

{
   "sessionId": "sessionId"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Boolean	False	直播是否关闭成功

# 响应样例

{
    "code": 0,
    "message": "success",
    "data": true
}

# 超级直播间Pro脚本json定义说明

# 简介

直播脚本即2D数字人直播时需要的内容定义，包含使用的人物形象，发音人音色，播报内容，直播间前后景图片，以及主播各类美颜参数等。

# json参数说明

名称	类型	取值示例	必填	说明
version	String	"0.0.2"	是	直播json配置文件版本号
resolution	Int Array	[1080,1920]	否	>= 0.0.2: 声网推流及内部blend画布分辨率，最大支持1080p，最小不能小于1010 0.0.1: 声网推流分辨率，最大支持1080p，最小不能小于1010
bit_rate	Float	3.5	否	声网推流码率，最大值7，最小值需大于0（Mbps）。实际推流码率是否可以达到设置的码率与当前分辨率有关。
live_type	String	"SuperLiveRoomPro"	是	定义当前直播的类型，超级直播间Pro功能需要填入"SuperLiveRoomPro"
streaming_param	Object		否	推流参数相关设置
h264_profile	Integer	100	否	声网PROFILE设置，默认是100，一般情况下不建议修改
key_frame_interval	Integer	0	否	声网I帧间隔设置，单位为秒。默认是0，不更改I帧。一般情况下不建议修改
agora_live_mode	Boolean	False	否	是否设置声网LIVE模式，默认false，即rtc模式。true为live模式。
rtmp_url	String	rtmp://xxx.xxx/xxx	否	默认是RTC推流，字符串不为空，则使用RTMP推流
sceneList	Object Array	包含内容如下	是	场景数组列表，暂时还未支持多场景，只有第一个数组元素有效
digital_role	Object	包含内容如下
face_feature_id	String	"1"	是	数字人face feature id
file_id	String	"aaaabbb"	是	预热素材id
position	Object	包含内容如下	否	数字人形象图片的起始像素位置，以1080*1920分辨率大小画布的左上角为原点，向右为x方向，向下为y方向
x	Integer	0	是	x方向坐标值
y	Integer	0	是	y方向坐标值
scale	Float	1.0	否	数字人形象比例
digital_role_sublist	Object Array	包含内容如下
file_id	String	"aaaa"	是	预热素材id
position	Object	包含内容如下	否	数字人形象图片的起始像素位置，以1080*1920分辨率大小画布的左上角为原点，向右为x方向，向下为y方向
x	Integer	0	是	x方向坐标值
y	Integer	0	是	y方向坐标值
scale	Float	1.0	否	数字人形象比例
notify_frame	Int Array	[500,2000,10000,30000]	否	指定当前数字人播放到列表中指定的帧数时，则发送WEBSOCKET通知当前进度
file_preload_list	String Array	["001", "002", "003", "004"]	否	预加载素材ID列表
effects	Object	包含内容如下	否
version	String	"1.0"	是	特效引擎版本
beautify	Object	包含内容如下	否	美颜
whitenStrength	Float	0.3	否	[0,1.0] 美白, 默认值 0.30, 0.0 不做美白
whiten_mode	Integer	0	否	美白模式：0（偏粉白）, 1（自然白）, 2（只有皮肤区域自然白）
reddenStrength	Float	0.36	否	[0,1.0]红润, 默认值 0.36, 0.0 不做红润
smoothStrength	Float	0.74	否	[0,1.0]磨皮, 默认值 0.74, 0.0 不做磨皮
smooth_mode	Integer	0	否	磨皮模式：0（脸部区域磨皮）, 1（全图磨皮）, 2（脸部区域精细磨皮）
shrinkRatio	Float	0.11	否	[0,1.0]瘦脸, 默认值 0.11, 0.0 不做瘦脸效果
enlargeRatio	Float	0.13	否	[0,1.0]大眼, 默认值 0.13, 0.0 不做大眼效果
smallRatio	Float	0.10	否	[0,1.0]小脸, 默认值 0.10, 0.0 不做小脸效果
narrowFace	Float	0.0	否	[0,1.0] 窄脸, 默认值 0.0, 0.0 不做窄脸
roundEyesRatio	Float	0.0	否	[0,1.0] 圆眼, 默认值 0.0, 0.0不做圆眼
thinFaceShapeRatio	Float	0.0	否	[0,1.0]瘦脸型, 默认值 0.0, 0.0 不做瘦脸型效果
chinLength	Float	0.0	否	[-1, 1]下巴长短, 默认值为 0.0，[-1, 0]为短下巴，[0, 1]为长下巴
hairlineHeightRatio	Float	0.0	否	[-1, 1]发际线, 默认值为 0.0，[-1, 0] 为低发际线，[0, 1]为高发际线
appleMusle	Float	0.0	否	[0, 1.0]苹果肌，默认值为 0.0，0.0 不做苹果肌
narrowNoseRatio	Float	0.0	否	[0, 1.0]瘦鼻，瘦鼻翼，默认值为 0.0，0.0 不做瘦鼻
noseLengthRatio	Float	0.0	否	[-1, 1]长鼻, 默认值为 0.0, [-1, 0]为短鼻，[0, 1]为长鼻
profileRhinoplasty	Float	0.0	否	[0, 1.0]侧脸隆鼻，默认值为 0.0，0.0 不做侧脸隆鼻效果
mouthSize	Float	0.0	否	[-1, 1]嘴巴大小，默认值为 0.0，[-1, 0]为放大嘴巴，[0, 1]为缩小嘴巴
philtrumLengthRatio	Float	0.0	否	[-1, 1]人中长短, 默认值为 0.0，[-1, 0]为长人中，[0, 1]为短人中
eyeDistanceRatio	Float	0.0	否	[-1, 1]调整眼距，默认值为 0.0，[-1, 0]为减小眼距，[0, 1]为增加眼距
eyeAngleRatio	Float	0.0	否	[-1, 1]眼睛角度，默认值为 0.0，[-1, 0]为左眼逆时针旋转，[0, 1]为左眼顺时针旋转，右眼与左眼相对
openCanthus	Float	0.0	否	[0, 1.0]开眼角，默认值为 0.0， 0.0 不做开眼角
shrinkJawbone	Float	0.0	否	[0, 1.0]瘦下颔骨比例，默认值 0.0， 0.0 不做瘦颧骨
shrinkRoundFace	Float	0.0	否	[0, 1.0]圆脸瘦脸，默认值 0.0， 0.0 不做瘦脸
shrinkLongFace	Float	0.0	否	[0, 1.0]长脸瘦脸，默认值 0.0， 0.0 不做瘦脸
shrinkGoddessFace	Float	0.0	否	[0, 1.0]女神瘦脸，默认值 0.0， 0.0 不做瘦脸
shrinkNaturalFace	Float	0.0	否	[0, 1.0]自然瘦脸，默认值 0.0， 0.0 不做瘦脸
shrinkWholeHead	Float	0.0	否	[0, 1.0]整体缩放小头，默认值 0.0, 0.0 不做整体缩放小头效果
contrastStrength	Float	0.05	否	[0,1.0]对比度, 默认值 0.05, 0.0 不做对比度处理
saturationStrength	Float	0.1	否	[0,1.0]饱和度, 默认值 0.10, 0.0 不做饱和度处理
sharpen	Float	0.0	否	[0, 1.0]锐化, 默认值 0.0, 0.0 不做锐化
clear	Float	0.0	否	[0, 1.0]清晰强度，默认值 0.0，0.0 不做清晰

# json文件样例

{
  "version": "0.0.1",
  "resolution": [1080,1920],
  "bit_rate": 5,
  "live_type":"SuperLiveRoomPro",
  "sceneList": [
    {
      "digital_role": {
        "face_feature_id": "0325_nina_s3_beauty",
        "file_id": "test_file_id",
        "position": {
          "x": 10,
          "y": 60
        },
        "scale": 1
      },
      "digital_role_sublist":[{
        "file_id": "test_file_id",
        "position": {
          "x": 10,
          "y": 60
        },
        "scale": 1,
        "notify_frame": [1,400,600,20000]
      },
      {
        "file_id": "test_file_id2",
        "position": {
          "x": 10,
          "y": 60
        },
        "scale": 1,
        "notify_frame": [1,400,600,20000]
      }],
      "effects": {
        "version": "1.0",
        "beautify": {
          "whitenStrength": 1.0,
          "whiten_mode": 0,
          "reddenStrength": 0.36,
          "smoothStrength": 1.0,
          "smooth_mode": 0,
          "shrinkRatio": 1.0,
          "enlargeRatio": 1.0,
          "smallRatio": 0.1,
          "narrowFace": 1.0,
          "roundEyesRatio": 0.0,
          "thinFaceShapeRatio": 0.0,
          "chinLength": 0.0,
          "hairlineHeightRatio": 0.0,
          "appleMusle": 0.0,
          "narrowNoseRatio": 0.0,
          "noseLengthRatio": 0.0,
          "profileRhinoplasty": 0.0,
          "mouthSize": 0.0,
          "philtrumLengthRatio": 0.0,
          "eyeDistanceRatio": 0.0,
          "eyeAngleRatio": 0.0,
          "openCanthus": 0.0,
          "brightEyeStrength": 0.0,
          "removeDarkCircleStrength": 0.0,
          "removeNasolabialFoldsStrength": 0.0,
          "whiteTeeth": 0.0,
          "shrinkCheekbone": 0.0,
          "thinnerHead": 0.0,
          "openExternalCanthus": 0.0,
          "shrinkJawbone": 0.0,
          "shrinkRoundFace": 0.0,
          "shrinkLongFace": 0.0,
          "shrinkGoddessFace": 0.0,
          "shrinkNaturalFace": 0.0,
          "shrinkWholeHead": 0.0,
          "contrastStrength": 0.05,
          "saturationStrength": 0.1,
          "sharpen": 0.0,
          "clear": 0.0
        }
      }
    }
  ]
}

# 超级直播间Pro控制json定义说明

# 简介

# json参数说明

名称	类型	取值示例	必填	说明
digital_role	Object		否	数字人
file_id	String	"aaaaaaaaa"	否	数字人文件id
foregrounds	Object Array	包含内容如下	否	前景图片/视频，目前视频支持的最大数量为2，图片支持的最大数量为40，gif支持的最大支持数量为40（指10张以内图片合成的简单gif图）
digital_role_file_id	String	"bbbbbbb"	是	数字人文件id
file_id	String	"cccc"	是	前景文件id
type	Integer	0	是	0:图片（png，jpg），1:视频（mp4，mov），2:gif
rect	Int Array	[0,0,1080,1920]	是	起始位置和大小，以1080*1920分辨率画布为参考
z_pos	Integer	1	否	默认1，数字人的z_pos字段为0且不可改变，前景的z_pos为正数则显示在数字人上方，负数显示在下方。数字大的在数字小的图层上面。
start	Integer	0	是	前景图片开始出现时间，以帧为单位，为数字人的播放帧。若接到命令时，不是当前数字人，则等待满足条件后播放。若是当前数字人，但帧数未播放，则等待帧数播放到指定帧后开始播放前景图片/视频。若是当前数字人，且帧数已经播放，则直接开始播放前景图片/视频。
duration	Integer	123	是	前景图片持续时间，以帧为单位，-1为默认值，表示随接管持续一直存在
delay	Boolean	false	是	是否允许延展到下一个接管，若不允许，则该接管结束时，即结束。否则，按照设置的duration进行判断。
volume	Integer	100	否	如果前景是视频，用于和数字人声音混合。指定背景合成音量大小，有效值是[0~400]，如果是0则为前景静音，原视频音量是100。
backgrounds	Object	包含内容如下	否	背景图片/视频
digital_role_file_id	String	"bbbbbbb"	是	数字人文件id
file_id	String	"cccc"	是	前景文件id
type	Integer	0	是	0:图片（png，jpg），1:视频（mp4，mov），2:gif
rect	Int Array	[0,0,1080,1920]	是	起始位置和大小，以10801920分辨率画布为参考，图片按照短边撑满，长边居中截取形式处理。该字段必须和直播分辨率一致。*
cycle	Boolean	[false	是	针对视频有效，false:单次播放，true:循环播放
start	Integer	0	是	背景图片开始出现时间，以帧为单位，为数字人的播放帧。若接到命令时，不是当前数字人，则等待满足条件后播放。若是当前数字人，但帧数未播放，则等待帧数播放到指定帧后开始播放背景图片/视频。若是当前数字人，且帧数已经播放，则直接开始播放背景图片/视频。
duration	Integer	-1	是	背景图片持续时间，以帧为单位，-1为默认值，表示随接管持续一直存在
volume	Integer	100	否	如果前景是视频，用于和数字人声音混合。指定背景合成音量大小，有效值是[0~400]，如果是0则说明不合成，原视频音量是100

# json文件样例

{
    "digital_role":"aaaaaaa",
   "backgrounds": 
        {
          "file_id": "backgrounds",
          "digital_role_file_id":"123321",
          "rect": [
            0,
            0,
            1080,
            1920
          ],
          "start": 0,
          "duration": 123,
          "volume":50
        },
  "foregrounds": [
        {
          "file_id": "foregrounds",
          "digital_role_file_id":"123321",
          "rect": [
            0,
            0,
            310,
            88
          ],
          "start": 0,
          "duration": 100,
          "delay": false,
          "volume":50
        }
      ]
}

# 直播间管理 API 说明

# 直播接管排队查询

# 接口描述

获取所有的直播队列，返回内容为，按照直播顺序排序的trace ID 列表。当前正在播放或准备播放的内容为第一条。

注：仅可查询接管内容，不可查询控制命令。

# 请求地址

POST /api/2dvh/v1/material/live/channel/command/queue/list

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	True	会话的唯一标识

# 请求样例

{
  "sessionId": "sessionId"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	True
- `commandTraceIds`	Array	False	接管任务TraceId数组

# 响应样例

{   
  "code": 0,
  "message": "success",
  "data": {
    "commandTraceIds": ["commandTraceId1","commandTraceId2","commandTraceId3","commandTraceId4"]
  }
}

# 查询会话状态

# 接口描述

支持查询指定sessionId的直播间实例的运行状态，传入sessionId参数，返回该直播间的运行状态信息。

# 请求地址

GET /api/2dvh/v1/material/live/channel/stat?sessionId={sessionId}

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	True	会话的唯一标识

# 请求样例

http://{domainname}/api/2dvh/v1/material/live/channel/stat?sessionId=8bfeb2bd58474547a87520643cc2d8df

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	False	任务信息
- `status`	Integer	True	任务状态：2:直播中，32:视频流创建中, 35:视频流创建完成，5:直播主动关闭，50:其他关闭（如长时间无心跳，网络链接中断等），9:异常，99：初始化失败
- `sessionToken`	String	False	麦克风接管使用的token信息
- `rtcAppId`	String	False	RTC APP ID （状态为2和35有此值）
- `rtcChannelId`	String	False	RTC Channel ID （状态为2和35有此值）
- `rtcUid`	String	False	RTC UID （状态为2和35有此值）
- `rtcToken`	String	False	RTC Token （状态为2和35有此值）

# 响应样例

{
    "code": 0,
    "message": "success",
    "data": {
          "sessionToken": "sessionToken",
          "status": 35,
          "rtcAppId": "rtcAppId",
          "rtcChannelId": "rtcChannelId",
          "rtcUid": "rtcUid",
          "rtcToken": "rtcToken"
        }
}

# 查询进行中会话列表

# 接口描述

查询当前用户下所有进行中的直播间实例列表，该接口仅返回运行中的实例，已关闭的实例不会返回。

# 请求地址

GET /api/2dvh/v1/material/live/channel/running/list

# 请求头

无

# 请求参数

无

# 请求样例

无

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	False	任务信息
- `sessionId`	String	True	会话的唯一标识
- `status`	Integer	True	任务状态：2：直播中；32：视频流创建中；35：视频流创建完成
- `startTime`	String	False	直播开始时间（yyyy-MM-dd HH:mm:ss）

# 响应样例

{
    "code": 0,
    "message": "success",
    "data": [{
            "sessionId": "sessionId",
            "status": 2
        },
        {
            "sessionId": "sessionId",
            "status": 32
        }
    ]
}

# 查询历史会话列表

# 接口描述

查询当前用户下所有历史的直播间实例列表，该接口仅返回历史已完成的的实例，进行中的实例不会返回。

# 请求地址

POST /api/2dvh/v1/material/live/channel/history/list

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	False	直播会话的唯一标识
`status`	Integer	False	任务状态： 5：已完成，50：其他关闭（如长时间无心跳，网络链接中断等），9：异常，99：初始化失败，97：系统路数不足，98：客户路数不足
`pageNo`	int	False	当前页码 (默认 1)
`pageSize`	int	False	每页条数 (默认 10)
`sortName`	String	False	排序字段名
`sortValue`	String	False	排序顺序: asc, desc

# 请求样例

{
  "pageSize": 10,
  "pageNo": 1
}

# 响应元素

字段	类型	必填	描述
`code`	Number	True	0 - 成功, 其他- 异常
`message`	String	True	异常详细信息
`data`	Object	False	data object ，异常时通常为空
- `pagination`	pagination	True	分页信息(参照共通说明)
- `result`	Object	True	任务列表（参照下面说明）

直播任务列表

字段	类型	必填	描述
`sessionId`	String	True	直播会话的唯一标识
`status`	Integer	True	任务状态： 5：直播主动关闭，50：其他关闭（如长时间无心跳，网络链接中断等），9：异常，99：初始化失败
`startTime`	String	True	直播开始时间（yyyy-MM-dd HH:mm:ss）
`endTime`	String	True	直播截止时间（yyyy-MM-dd HH:mm:ss）

# 响应样例

{
  "code": 0,
  "message": "success",
  "data": {
    "pagination": {
      "pageNo": 1,
      "numberPages": 1,
      "numberRecords": 2,
      "pageSize": 2,
      "startIndex": 0
    },
    "result": [
      {
        "sessionId": "sessionId",
        "startTime": "2023-02-17 16:53:26",
        "endTime": "2023-02-18 10:03:21",
        "status": 5
      },
      {
        "sessionId": "sessionId",
        "startTime": "2023-02-17 16:56:26",
        "endTime": "2023-02-17 17:43:19",
        "status": 9
      }
    ]
  }
}

# 获取RTC Token

# 接口描述

获取rtc token。在权限过期前 30 秒，SDK 会触发 token-privilege-will-expire 回调。收到该回调后，客户端需要从服务器获取新的 Token 并调用 renewToken 方法将新生成的 Token 传给 SDK。

# 请求地址

POST /api/2dvh/v1/material/rtc/token/audience

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	True	会话的唯一标识
`rtcChannelId`	String	True	RTC Channel ID

# 请求样例

{
    "sessionId": "sessionId",
    "rtcChannelId": "rtcChannelId"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	String	False	rtc token

# 响应样例

{
    "code": 0,
    "message": "success",
    "data": "007eJxTYGD8ItJX2zMjMu2BfJybs/H+9+66e3wXr2p+eTt877SnV3cqMKSZGKRamJomGRqnGZhYmhhamlikGJmaJ6WmGRuYpqQahHteTjmwgoHh8I7fcYwMjAwsQAziM4FJZjDJAiYVGCwNLM3NTdJSLVLMgMZYJFqapqalWZhZJpqnGSabp6YxMhgBADEzLqA="
}

# 更新URTC Token

# 接口描述

更新urtc token。客户平台需要在token过期前获取新Token并通知给PAAS平台。

# 请求地址

POST /api/2dvh/v1/material/rtc/token/host/renew

# 请求头

Content-Type: application/json

# 请求参数

字段	类型	必填	描述
`sessionId`	String	True	会话的唯一标识
`urtcToken`	String	True	用户rtc鉴权token

# 请求样例

{
    "sessionId": "sessionId",
    "urtcToken": "urtcToken"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	String	False	通常为空

# 响应样例

{
    "code": 0,
    "message": "success",
    "data": ""
}

# 直播状态回调参数

使用API时，系统将通过填写的直播状态回调地址，返回直播状态等信息，若需要直播状态回调功能，则需联系管理员在创建账户时提供直播状态回调地址。
直播间状态发生状态变更，且状态变为35：视频流创建完成，5：直播主动关闭，50：其他关闭（如长时间无心跳，网络链接中断等），9：异常，99：初始化失败（http请求为200，先收到状态32:初始化进行中的情况下）时将进行回调。直播接管完成和取消完成（34:接管入队完成，36：接管播放开始，37：接管播放完成，39：接管异常）时将进行回调(不含麦克风接管)。如果用户配置了AuthKey将返回鉴权信息timestamp和signature，具体参考<HTTP回调事件通知>。

提供的接口实现中HTTP Method为POST，Content-Type应为application/json。

字段	类型	必填	描述
`sessionId`	String	True	直播会话的唯一标识
`rtcAppId`	String	False	RTC APP ID （状态为35时有此值）
`rtcChannelId`	String	False	RTC Channel ID （状态为35时有此值）
`rtcUid`	String	False	RTC UID （状态为35时有此值）
`rtcToken`	String	False	RTC Token （状态为35时有此值）
`status`	Integer	True	状态: 35：视频流创建完成 5：直播主动关闭 50：其他关闭（如长时间无心跳，网络链接中断等) 9：异常 99：初始化失败 96：urtcToken过期 34: 接管入队完成 36：接管播放开始 37：接管播放完成 39：接管异常
`commandTraceId`	String	False	接管任务TraceId
`commandFinishTime`	String	False	打断完成时间（yyyy-MM-dd HH:mm:ss）
`taskResult`	String	False	报错信息
`userData`	String	False	用户信息

以上即为平台可以提供的视频直播全部能力。

← 直播视频直播 →