# Super Live Room Pro

# Feature Introduction

To be supplemented

# Super Live Room API Reference

To call all API services on the platform, users must access the service endpoint: aigc.softsugar.com, and include the token information in the request header. For WebSocket interfaces, the token information must be appended to the URL.

# Live Streaming Sequence Diagram

【等To be supplemented图】

# Create Live Room

# API Description

Creates a digital human live streaming instance. The system initializes with the specified parameters and returns session ID and other information for subsequent use. If initialization takes too long, status 32 will be returned, and the completion status will be updated via callback or client query. When the status is 35, the video stream initialization is complete and the live stream can be started.
The web sample uses a third-party SDK service for playback. For details, refer to:三方SDK使用Description (opens new window)。

Note: Timing begins as soon as the live room is created.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`param`	String	True	Live video generation parameters (this parameter is a JSON-escaped string)
`urtcUseExternalApp`	Boolean	False	Whether to use user Agora RTC appId. If not, the platform unified RTC appId will be used (default: No)
`urtcToken`	String	False	User RTC authentication token （使用用户rtc app时Required）
`urtcUid`	String	False	用户rtc鉴权uid （使用用户rtc app时Required，必须是大小不超过32uint的纯数字）
`urtcAppId`	String	False	用户rtc APP ID （使用用户rtc app时Required）
`urtcChannelId`	String	False	用户rtc Channel ID （使用用户rtc app时Required，长度不得超过 64 位）
`userData`	String	False	User information (returned as-is during callback)

# Request Example

{
  "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\":{}}}]}"
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	False	Whether the live stream started successfully
- `sessionId`	String	True	Unique session identifier
- `sessionToken`	String	True	Token information for microphone takeover
- `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无此值）

# Response Example

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

# Live Stream Status Monitoring

# API Description

Used to maintain the live stream. It is recommended to call this API every 60 seconds. If the heartbeat loss time exceeds the threshold, the live stream will be passively closed.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier

# Request Example

{
  "sessionId": "sessionId"
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	False	data object ，异常时Usually empty

# Response Example

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

# Start Live Stream

# API Description

Starts a digital human live room instance. By passing in the specified parameters, a digital human live stream push instance can be started, which can be pulled using third-party RTC stream-pulling SDK products.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier

# Request Example

{
  "sessionId": "sessionId"
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Boolean	False	Whether the live stream started successfully

# Response Example

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

# Super Live Room Pro控制

# API Description

Super Live Room Pro control, used for directly controlling digital human switching, foreground switching, and background switching in the live room.

Note: After sending a control command in the current version, it will return success/failure of reception. Once the trigger conditions are met, it will be triggered automatically. Currently no additional information is returned.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier
`param`	String	True	Takeover content (this parameter is a JSON-escaped string)

# Request Example

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

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	True
- `commandStatus`	Integer	True	控制命令状态（51:超级控制接收，52:超级控制JSON解析失败，53:超级控制切换数字人失败，未找到该数字人，54:超级控制切换视频失败，解码失败，55:超级控制其他错误，解码失败）
- `commandTraceId`	String	True	Control command TraceId

# Response Example

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

# Live Stream Takeover Queue (Streaming Voice Input)

# API Description

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

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

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

# Request URL

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

# Request Headers

# Request Parameters

Field	Type	Required	Description
`clientType`	String	True	连接端Type：BROWSER：生产端
`sessionId`	String	True	Unique session ID returned after connection establishment
`Authorization`	String	True	This token is the sessionToken returned when creating the live room

# Request Example（上行消息）

Field	Type	Required	Description
`code`	Integer	True	Message code
`message`	String	True	Unique session ID returned after connection establishment
`commandTraceId`	String	True	接管ID。与http接管相似，但需调用方主动传入唯一ID，在直播内有效。并可以通过取消接管接口取消该次接管。仅在code=0，code=10，code=11，code=99时有效
`priority`	Integer	False	优先级,仅在code=0或10时有效（合法值区间1~n或-1，如果传入不合法，插入到队列最后，-1是自动排到队尾）
`tts_query`	Object	False	tts语音合成
content	String	True	示例内容："尊敬的观众朋友们，大家好！非常荣幸能够在这个美好的时刻与大家相聚，欢迎收看今天的直播节目。"，接管的文本内容，要求字数不得少于10个字
ssml	Boolean	false	是否使用ssml，开启后query可以使用USSML和SSML。SSML语法请见“语音处理-USSML语法Description”
`superControl`	String	False	超级直播间Pro控制命令，转义后的json字符串。参考“超级直播间Pro接管json定义Description”
`silk`	boolean	False	接管是否启用silk方式

# 连接建立

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": 101
    }

# Response Elements

Field	Type	Required	Description
`code`	String	True	消息Type编码
`message`	String	True	Detailed information

# Response Example（下行消息）

# Authentication failed

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

# 服务端已准备好接收

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

# Takeover enqueued successfully通知

   {
       "code": 20,
       "message": "接管入队完成",
       "data": {
            "sessionId": "xxxxx",
            "commandTraceId": "yyyyyy",
            "timestamp": 1234567890
        }
   }

# Takeover playback started通知

   {
       "code": 19,
       "message": "开始播放接管",
       "data": {
            "sessionId": "xxxxx",
            "commandTraceId": "yyyyyy",
            "timestamp": 1234567890
        }
   }

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

# 剩余时长通知

   {
      "code": 102,
      "message": {
        "channel_id": "xxxxx",
        "server_time":1749191900412,
        "remain_duration":30
      }
   }

# 帧数通知

   {
      "code": 30,
      "message": {
        "digital_role_file_id": "001",
        "cur_frame": 500
      }
   }

# Add New Preheated Materials During Live Stream

# API Description

Adds new preheated materials during the live stream.

# Request URL

POST /api/2dvh/v1/material/live/channel/command/warmed/file/add

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier
`filePreloadList`	String Array	True	Preloaded material ID list

# Request Example

{
  "sessionId": "sessionId",
  "filePreloadList": ["001", "002", "003", "004"]
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	True
- `commandStatus`	Integer	True	预热素材结果状态（73：预热文件更新异常，74：热文件更新json异常，75：预热文件更新完成）
- `commandTraceId`	String	False	Task TraceId

# Response Example

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

# Live Stream Takeover Requeue

调整接管队列中某个接管任务的顺序。

# API Description

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier
`commandTraceId`	String	True	Takeover task TraceId (returned during takeover)
`priority`	Integer	True	Expected queue insertion priority

# Request Example

{
  "sessionId": "sessionId",
  "commandTraceId": "commandTraceId",
  "priority": 1
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	True
- `isSuccess`	Boolean	True	Whether successful

# Response Example

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

# Live Stream Takeover Cancellation

# API Description

取消已发送的文字或音频文件接管请求。如果想要一次取消多个，trace ID之间用英文“;”隔开。如果为"-1"，将全部内容取消（包括接管中的和队列中的）。 If text/audio takeover is in progress, microphone takeover can only be started after cancelling all current takeovers.

# Request URL

POST /api/2dvh/v1/material/live/channel/command/cancel

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier
`commandTraceId`	String	True	Takeover task TraceId (returned during takeover)，取消多个，英文“;”隔开。"-1":全部取消

# Request Example

{
  "sessionId": "sessionId",
  "commandTraceId": "commandTraceId"
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	True
- `isSuccess`	Boolean	True	Whether the takeover cancellation was successful
- `commandFinishTime`	String	False	Completion time （yyyy-MM-dd HH:mm:ss）
- `message`	String	False	Failure reason

# Response Example

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

# Live Stream Takeover Queue Query

# API Description

Gets all live stream queues. Returns a list of trace IDs sorted by playback order. The currently playing or ready-to-play content is the first entry.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier

# Request Example

{
  "sessionId": "sessionId"
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	True
- `commandTraceIds`	Array	False	Takeover task TraceId array

# Response Example

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

# Close Live Stream

# API Description

Closes a digital human live room instance that is in progress, stops the digital human stream push, closes the live stream, and releases related resources.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier

# Request Example

{
   "sessionId": "sessionId"
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Boolean	False	Whether the live stream was closed successfully

# Response Example

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

# Super Live Room Pro脚本json定义Description

# Introduction

The live stream script is the content definition needed for 2D digital human live streaming, including the avatar to use, speaker voice, broadcast content, foreground/background images for the live room, and various beauty parameters for the host.

# JSON Parameter Description

Name	Type	Example	Required	Description
version	String	"0.0.2"	是	直播json配置文件版本号
resolution	Int Array	[1080,1920]	否	>= 0.0.2: 声网推流及内部blend画布分辨率，最大支持1080p，最小不能小于1010；自研RTMP协议最大支持10802280分辨率； 0.0.1: 声网推流分辨率，最大支持1080p，最小不能小于10*10
bit_rate	Float	3.5	否	声网推流码率，最大值7，最小值需大于0（Mbps）。实际推流码率是否可以达到设置的码率与当前分辨率有关。
live_type	String	"SuperLiveRoomPro"	是	定义当前直播的Type，超级直播间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通知当前进度
auto_fill_silence	Boolean	False	否	仅用于超级直播间下使用，用于websocket流发送不及时，为防止直播间黑屏，自动添加静音。默认不开启
file_preload_list	String Array	["001", "002", "003", "004"]	否	Preloaded material ID list
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 File Example

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

# Super Live Room Pro控制json定义Description

# Introduction

# JSON Parameter Description

Name	Type	Example	Required	Description
digital_role	Object		否	数字人
file_id	String	"aaaaaaaaa"	否	数字人文件id
position	Object	包含内容如下	否	数字人形象图片的起始像素位置，以1080*1920分辨率大小画布的左上角为原点，向右为x方向，向下为y方向
x	Integer	0	是	x方向坐标值
y	Integer	0	是	y方向坐标值
scale	Float	1.0	否	数字人形象比例，请注意不能只填scale，而不填position。这两项必须同时存在，否则不会重新指定新的数字人位置
start	Integer	0	否	指定数字人循环开播播放起点（单位帧）
end	Integer	0	否	指定数字人循环开播播放终点（单位帧），end需要大于start
play_reversible	Boolean	true	否	指定数字人播放是否循环播放，默认为true即循环播放（先正序再倒序），false为仅正序播放，当素材视频播放最后一帧直接跳到第一帧，会产生跳变
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，3:音频
rect	Int Array	[0,0,1080,1920]	是	起始位置和大小，以1080*1920分辨率画布为参考
cycle	Boolean	[false]	是	针对视频有效，false:单次播放，true:循环播放
z_pos	Integer	1	否	默认1，数字人的z_posField为0且不可改变，前景的z_pos为正数则显示在数字人上方，负数显示在下方。数字大的在数字小的图层上面。
start	Integer	0	是	前景图片开始出现时间，以帧为单位，为数字人的播放帧。若接到命令时，不是当前数字人，则等待满足条件后播放。若是当前数字人，但帧数未播放，则等待帧数播放到指定帧后开始播放前景图片/视频。若是当前数字人，且帧数已经播放，则直接开始播放前景图片/视频。
duration	Integer	123	是	前景图片持续时间，以帧为单位，-1为默认值，表示随接管持续一直存在
delay	Boolean	false	是	是否允许延展到下一个接管，若不允许，则该接管结束时，即结束。否则，按照设置的duration进行判断。
volume	Integer	100	否	如果前景是视频、音频，用于和数字人声音混合。指定背景合成音量大小，有效值是[0~400]，如果是0则为前景静音，原视频音量是100。
play_offset	Integer	0	否	如果type=1，视频可以指定从第几秒开始播放（单位秒）
start_trace_id	String		否	素材跟指定接管trace_id一起播放
alpha	Boolean	false	否	针对视频有效，是否支持alpha通道，若传入透明视频，需要将此值设置为true
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，3:音频
rect	Int Array	[0,0,1080,1920]	是	起始位置和大小，以10801920分辨率画布为参考，图片按照短边撑满，长边居中截取形式处理。该Field必须和直播分辨率一致。*
cycle	Boolean	[false]	是	针对视频有效，false:单次播放，true:循环播放
start	Integer	0	是	背景图片开始出现时间，以帧为单位，为数字人的播放帧。若接到命令时，不是当前数字人，则等待满足条件后播放。若是当前数字人，但帧数未播放，则等待帧数播放到指定帧后开始播放背景图片/视频。若是当前数字人，且帧数已经播放，则直接开始播放背景图片/视频。
duration	Integer	-1	是	背景图片持续时间，以帧为单位，-1为默认值，表示随接管持续一直存在
volume	Integer	100	否	如果前景是视频、音频，用于和数字人声音混合。指定背景合成音量大小，有效值是[0~400]，如果是0则Description不合成，原视频音量是100
play_offset	Integer	0	否	如果type=1，视频可以指定从第几秒开始播放（单位秒）
start_trace_id	String		否	素材跟指定接管trace_id一起播放
alpha	Boolean	false	否	针对视频有效，是否支持alpha通道，若传入透明视频，需要将此值设置为true
change_bit_rate	Float	5	否	动态更改RTMP推流码率，最大值7，最小值需大于0（Mbps），收到消息后立即生效

# JSON File Example

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

# Live Room Management API Reference

# Live Stream Takeover Queue Query

# API Description

Gets all live stream queues. Returns a list of trace IDs sorted by playback order. The currently playing or ready-to-play content is the first entry.

Note: Only takeover content can be queried, not control commands.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier

# Request Example

{
  "sessionId": "sessionId"
}

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	True
- `commandTraceIds`	Array	False	Takeover task TraceId array

# Response Example

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

# Query Session Status

# API Description

Supports querying the running status of a live room instance with the specified sessionId. Pass in the sessionId parameter to return the running status information of the live room.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier

# Request Example

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

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	False	Task information
- `status`	Integer	True	任务状态：2:直播中，32:视频流创建中, 35:视频流创建完成，5:直播主动关闭，50:其他关闭（如长时间无心跳，网络链接中断等），9:异常，99：初始化失败
- `sessionToken`	String	False	Token information for microphone takeover
- `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有此值）

# Response Example

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

# Query Active Session List

# API Description

Queries the list of all active live room instances under the current user. This API only returns running instances; closed instances will not be returned.

# Request URL

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

# Request Headers

无

# Request Parameters

无

# Request Example

无

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	Object	False	Task information
- `sessionId`	String	True	Unique session identifier
- `status`	Integer	True	任务状态：2：直播中；32：视频流创建中；35：视频流创建完成
- `startTime`	String	False	Live stream start time （yyyy-MM-dd HH:mm:ss）

# Response Example

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

# Query Historical Session List

# API Description

Queries the list of all historical live room instances under the current user. This API only returns completed historical instances; active instances will not be returned.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	False	直播Unique session identifier
`status`	Integer	False	任务状态： 5：已完成，50：其他关闭（如长时间无心跳，网络链接中断等），9：异常，99：初始化失败，97：系统路数不足，98：客户路数不足
`pageNo`	int	False	Current page number (default 1)
`pageSize`	int	False	Items per page (default 10)
`sortName`	String	False	排序Field名
`sortValue`	String	False	Sort order: asc, desc

# Request Example

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

# Response Elements

Field	Type	Required	Description
`code`	Number	True	0 - 成功, 其他- 异常
`message`	String	True	Error details
`data`	Object	False	data object ，异常时Usually empty
- `pagination`	pagination	True	分页信息(参照共通Description)
- `result`	Object	True	任务列表（参照下面Description）

直播任务列表

Field	Type	Required	Description
`sessionId`	String	True	直播Unique session identifier
`status`	Integer	True	任务状态： 5：直播主动关闭，50：其他关闭（如长时间无心跳，网络链接中断等），9：异常，99：初始化失败
`startTime`	String	True	Live stream start time（yyyy-MM-dd HH:mm:ss）
`endTime`	String	True	Live stream end time （yyyy-MM-dd HH:mm:ss）

# Response Example

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

# Get RTC Token

# API Description

Gets the RTC token. 30 seconds before the permission expires, the SDK will trigger a token-privilege-will-expire callback. After receiving this callback, the client needs to obtain a new Token from the server and call the renewToken method to pass the newly generated Token to the SDK.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier
`rtcChannelId`	String	True	RTC Channel ID

# Request Example

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

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	String	False	rtc token

# Response Example

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

# Update URTC Token

# API Description

Updates the URTC token. The client platform needs to obtain a new Token before expiration and notify the PaaS platform.

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field	Type	Required	Description
`sessionId`	String	True	Unique session identifier
`urtcToken`	String	True	User RTC authentication token

# Request Example

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

# Response Elements

Field	Type	Required	Description
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	Error details
`data`	String	False	Usually empty

# Response Example

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

# Live Stream Status Callback Parameters

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

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

Field	Type	Required	Description
`sessionId`	String	True	直播Unique session identifier
`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: Takeover enqueued successfully 36：接管播放开始 37：接管播放完成 39：接管异常
`commandTraceId`	String	False	Takeover task TraceId
`commandFinishTime`	String	False	打断Completion time （yyyy-MM-dd HH:mm:ss）
`taskResult`	String	False	Error message
`userData`	String	False	User information

The above covers all live streaming capabilities provided by the platform.

← Live Streaming Video Live Streaming (Deprecated) →