# Live Streaming

The platform provides digital human product capabilities that support pushing digital human streaming content to user-specified live streaming platforms, while also supporting real-time voice interaction between users and 2D digital humans. The platform retains legacy interactive live streaming API interfaces. Users are advised to integrate with the new version of live streaming services according to the online documentation. Legacy version interfaces will be scheduled for decommission. Legacy documentation reference: 文档链接 (opens new window)

# Feature Introduction

The virtual digital human live streaming service integrates graphic, image, voice, and other algorithmic capabilities, providing API services to customers for quick creation and broadcasting of live content. The main target industries include government affairs, finance, education and training, media, etc. The platform provides digital human product capabilities that support real-time voice interaction between users and 2D digital humans. Currently, interactive digital human live streaming supports both text and voice interaction methods. During digital human speech, interruption through specific phrases is supported, enabling a more user-friendly full-duplex voice conversation experience, aimed at delivering personalized services, enhancing user experience, and improving efficiency and competitiveness.

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

# 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 ，异常时通常为空

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

# Live Stream Takeover (Interruptible)

# API Description

Sends broadcast text or audio files to the server. The digital human will stop the scheduled broadcast content based on the text/audio, perform real-time TTS generation, expression and motion driving, and render the video stream to the user.

# Request URL

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

# 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": "{\"tts_query\": {\"content\": \"有一颗蛋在地上滚。滚过树林，滚过花园，又从斜坡滚了下去，最后滚进一个鸭巢里。鸭妈妈并没有发现不对劲，继续孵蛋。有一天，蛋破了。第一颗蛋孵出的是一只有蓝点的小鸭，叫蜡笔。第二颗蛋孵出的是一只有条纹的小鸭，叫斑马。第三颗蛋孵出的是一只黄色的小鸭，叫月光。第四颗蛋孵出的是一只全身蓝绿色的小怪鸭，嘴里还不停的发出咕叽咕叽的叫声，所以就叫做咕叽咕叽.\",\"ssml\": false},\"audio\": \"/data/common/song.mp3\"}"
}

# Response Elements

Field Type Required Description
code Integer True 0 - 成功, 其他 - 异常
message String True Error details
data Object True
  - isSuccess Boolean True Whether the takeover was successful
  - commandTraceId String False Takeover task TraceId (required when cancelling takeover)

# Response Example

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

# Live Stream Takeover Queue (Interruptible)

# API Description

可排队的直播接管，如果当前有接管中的任务，则将该接管加入队列，并按顺序进行接管。当前正在接管中的任务位置序号为1。
可插入的范围为：1- N，含义为将按照插入的位置序号顺序+1进行播报。例如：插入位置序号为1，则为排队队列的第2条播放内容，将在当前正在播放的任务结束后播放该条内容，后续的排队任务自动调整顺序。
接管加入队列状态分为2种（33：接管入队初始化中；34：接管加入队列完成），如果返回状态为33表示初始化时间（下载文件等）超过阈值（当前为10s）。后续入队状态将通过异步回调的方式通知。
如果接管包含的文件内容较大，例如图片文件较大或声音文件较大等，需要较长时间下载。目前系统会将需要下载的内容都下载完成后才进入排队队列，返回接管加入队列完成。
为保证程序处理正常，接管排队队列长度建议不超过15个。

# Request URL

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

# Request Headers

Content-Type: application/json

# Request Parameters

Field Type Required Description
sessionId String True Unique session identifier
priority Integer False Expected position number for queue insertion. If not specified or exceeds current queue max length, inserts at the end
param String True Takeover content (this parameter is a JSON-escaped string)

# Request Example

{
  "sessionId": "sessionId",
  "priority": 1,
  "param": "{\"tts_query\": {\"content\": \"有一颗蛋在地上滚。滚过树林，滚过花园，又从斜坡滚了下去，最后滚进一个鸭巢里。鸭妈妈并没有发现不对劲，继续孵蛋。有一天，蛋破了。第一颗蛋孵出的是一只有蓝点的小鸭，叫蜡笔。第二颗蛋孵出的是一只有条纹的小鸭，叫斑马。第三颗蛋孵出的是一只黄色的小鸭，叫月光。第四颗蛋孵出的是一只全身蓝绿色的小怪鸭，嘴里还不停的发出咕叽咕叽的叫声，所以就叫做咕叽咕叽.\",\"ssml\": false},\"audio\": \"/data/common/song.mp3\"}"
}

# Response Elements

Field Type Required Description
code Integer True 0 - 成功, 其他 - 异常
message String True Error details
data Object True
  - commandStatus Integer True 接管队列状态（33：接管入队初始化中；34：接管加入队列完成）
  - commandTraceId String True Takeover task TraceId (required when cancelling takeover)

# Response Example

{   
  "code": 0,
  "message": "success",
  "data": {
    "commandStatus": 34,
    "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"]
  }
}

# Live Stream Filler Speech Takeover

# API Description

Interactive digital human scenario live stream filler speech takeover. Cannot be queued; filler speech takeover is not available when there is an active takeover script.

# Request URL

POST /api/2dvh/v2/material/live/channel/command/quick

# 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": "{\"quick_response\": true,   \"order\": -1 ,\"quick_response_id\":  \"234323\"}"
}

# param Parameter Description

Field Type Required Description
quick_response Boolean True Must be set to "true"
order Integer True Index number, -1 for random
quick_response_id String False Filler word library ID

# Response Elements

Field Type Required Description
code Integer True 0 - 成功, 其他 - 异常
message String True Error details
data Object True
  - isSuccess Boolean True Whether the takeover was successful
  - commandTraceId String False Takeover task TraceId

# Response Example

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

# Live Stream Takeover Queue (Streaming Text Input/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 (Upstream Messages)

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是自动排到队尾）
# 连接建立

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": 10,
        "message": "begin",
        "commandTraceId": "aaaaxxxyyyzzz111222333", 
        "priority": 1
    }
# 流式文本内容，文本在messageField中传输
    {
        "code": 11,
        "message": "流式文本内容1",
        "commandTraceId": "aaaaxxxyyyzzz111222333"
}
# 流式文本内容，文本在messageField中传输
    {
        "code": 11,
        "message": "流式文本内容2",
        "commandTraceId": "aaaaxxxyyyzzz111222333"
}
# 发送结束
    {
        "code": 99,
        "message": "eof",
        "commandTraceId": "aaaaxxxyyyzzz111222333"
    }

# Response Elements

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

# Response Example (Downstream Messages)

# Authentication failed
   {
        "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": "算法端接管冲突被拒绝"
   }
# http形式发起的接管（文字接管/音频接管）Takeover playback started通知
   {
        "code": 19,
        "message": "开始播放接管",
        "data": {
            "sessionId": "xxxxx",
            "commandTraceId": "yyyyyy",
            "timestamp": 1234567890
        }
   }
# http形式发起的接管（文字接管/音频接管）Takeover enqueued successfully通知
   {
        "code": 20,
        "message": "接管入队完成",
        "data": {
            "sessionId": "xxxxx",
            "commandTraceId": "yyyyyy",
            "timestamp": 1234567890
        }
   }
# webSocket形式发起的接管（文字接管/音频接管）的消息接收成功通知(目前只响应消息 99 eof)
   {
      "code": -1,
      "message": "接管消息ACK",
      "data": {
        "sessionId": "xxxxx",
        "code": 99,
        "commandTraceId": "yyyyyy",
        "timestamp": 1740998208131
      }
    }

# Add New Preheated Materials During Live Stream

# API Description

直播中增加新的预热素材。

# 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
  - isSuccess Boolean True Whether successful
  - commandTraceId String False 任务TraceId

# Response Example

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

# Streaming Voice Takeover (Deprecated)

# API Description

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

此外，所有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 (Upstream Messages)

Field Type Required Description
code Integer True Message code
message String True Unique session ID returned after connection establishment
# 连接建立

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

# 流式PCM音频
# 开始接收流式PCM音频通知
    {
        "code": 0,
        "message": "begin"
    }
# 语音数据
二进制语音数据，流式声音要求传输格式为PCM格式，码率要求为16000， 单声道，16bit采样率。
# 发送结束
    {
        "code": 99,
        "message": "eof"
    }

# Response Elements

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

# Response Example (Downstream Messages)

# Authentication failed
   {
        "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": "算法端接管冲突被拒绝"
   }
# http形式发起的接管（文字接管/音频接管）Takeover playback started通知
   {
        "code": 19,
        "message": "开始播放接管",
        "data": {
            "sessionId": "xxxxx",
            "commandTraceId": "yyyyyy",
            "timestamp": 1234567890
        }
   }
# http形式发起的接管（文字接管/音频接管）Takeover enqueued successfully通知
   {
        "code": 20,
        "message": "接管入队完成",
        "data": {
            "sessionId": "xxxxx",
            "commandTraceId": "yyyyyy",
            "timestamp": 1234567890
        }
   }
# webSocket形式发起的接管（文字接管/音频接管）的消息接收成功通知(目前只响应消息 99 eof)
   {
      "code": -1,
      "message": "接管消息ACK",
      "data": {
        "sessionId": "xxxxx",
        "code": 99,
        "commandTraceId": "yyyyyy",
        "timestamp": 1740998208131
      }
    }

# Live Stream NLP Q&A (Deprecated)

# API Description

直播前可以预设多个问答库和问答底稿内容，具体方法需通过平台web端界面 (opens new window)设置；直播时可以设置本场直播匹配的问答库ID（一场直播仅支持匹配一个问答库），直播过程中可根据观众提问的问题在匹配的问答库中进行检索，若命中答案则返回对应的答案内容，用户可选择通过直播接管的形式播放对应答案。

# Request URL

POST /api/2dvh/v1/nlp/model/reply

# Request Headers

Content-Type: application/json

# Request Parameters

Field Type Required Description
appId String True Q&A library ID. Note: Use the string format Q&A library ID, not the auto-increment ID displayed in the UI
device String True Access device info. Select based on the requesting terminal. Values: ios / android / windows / macos
language String True Language. Currently only supports Chinese; value is fixed as "zh"
query String True Query question content
session String True 用户自定义Field，要求为数字/字母/-组合，多轮对话使用同一session，将视为连续问题，可根据上下文信息匹配最佳答案结果
trace String True 用户自定义Field，要求为数字/字母/-组合，用于追踪查询信息

# Request Example

{
  "appId": "app_id",
  "device": "macos",
  "language": "zh",
  "query": "你好",
  "session": "456tf6c2-846c-4b8b-8ga9-e866fgr678a2",
  "trace": "451ee6c2-838c-4b8b-8ba9-e86c2d1692c7"
}

# Response Elements

Field Type Required Description
answer String True Question answer
device_id String True Access device info
language String True Language. Currently only supports "zh"
query String True Query question content
session String True Session ID at query time
trace String True Trace ID at query time
error_message String True Error message

# Response Example

{
    "answer": "卫生间在您右手边",
    "device_id": "DeviceID",
    "error_message": "",
    "language": "LanguageCode",
    "query": "我想去厕所",
    "session": "SessionID",
    "trace": "TraceID"
}

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

# 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 ，异常时通常为空
  - 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 通常为空

# Response Example

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

# Live Stream Takeover (To Be Deprecated, Please Use "Live Stream Takeover (Interruptible)")

# API Description

Sends broadcast text or audio files to the server. The digital human will stop the scheduled broadcast content based on the text/audio, perform real-time TTS generation, expression and motion driving, and render the video stream to the user.

# Request URL

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

# 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": "{\"tts_query\": {\"content\": \"有一颗蛋在地上滚。滚过树林，滚过花园，又从斜坡滚了下去，最后滚进一个鸭巢里。鸭妈妈并没有发现不对劲，继续孵蛋。有一天，蛋破了。第一颗蛋孵出的是一只有蓝点的小鸭，叫蜡笔。第二颗蛋孵出的是一只有条纹的小鸭，叫斑马。第三颗蛋孵出的是一只黄色的小鸭，叫月光。第四颗蛋孵出的是一只全身蓝绿色的小怪鸭，嘴里还不停的发出咕叽咕叽的叫声，所以就叫做咕叽咕叽.\",\"ssml\": false},\"audio\": \"/data/common/song.mp3\"}"
}

# Response Elements

Field Type Required Description
code Integer True 0 - 成功, 其他 - 异常
message String True Error details
data Boolean False Whether the takeover was successful

# Response Example

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

# Live Stream Script JSON Definition

# 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配置文件版本号
recycle Integer 0 是 直播重复次数，0为一直循环，值大于0，为循环次数，如指定1，则只播放1遍，如指定6，则循环播放6遍
stream_mode Boolean True 是 是否采用流式播放（快速开播）。满足最低开播条件后马上开播，不等开播脚本的资源全部到位。
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 "live" , "interactive" 否 定义当前直播的Type，可以不填，默认为"live"普通直播模式，"interactive"为互动模式。互动模式下支持口水话（quick_response）定义。
sentence_break Boolean True 否 默认开启按标点打断功能，非Required项，如果不想启用按照标点打断（想直接打断），传false
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模式。
sceneList Object Array 包含内容如下 是 场景数组列表，暂时还未支持多场景，只有第一个数组元素有效
digital_role Object 包含内容如下
 id Integer 1 否 数字人id
 face_feature_id String "1" 是 数字人face feature id
 name String "小李" 否 数字人Name
 url String "https://xxx/role.zip" 是 数字人形象zip包
 position Object 包含内容如下 否 数字人形象图片的起始像素位置，以1080*1920分辨率大小画布的左上角为原点，向右为x方向，向下为y方向
  x Integer 0 是 x方向坐标值
  y Integer 0 是 y方向坐标值
 scale Float 1.0 否 数字人形象比例
 alpha Boolean false 否 设置是否数字人推流为ALPHA透明背景模式。默认false，不推送透明通道。
tts_config Object 包含内容如下 是 tts配置
 qid String "8wfZav:AEA_Z10Mqp9GCwDGMrz8xIzi3VScxNzUtLCh" 否 非Required项，使用qid可以代替id/vendor_id，即（id/vendor_id）可以不填，但id和qid不能同时为空。
 id String "zh-CN-XiaoxuanNeural" 是 发音人id
 name String "晓萱" 是 发音人Name
 vendor_id Integer 4 是 供应商id
 language String "zh-CN" 是 语言码
 pitch_offset Float 0.0 是 音调，数值越大越尖锐，越低越低沉，支持范围 [-60, 60]
 speed_ratio Float 1 是 语速，数值越大语速越慢，支持范围 [0.5, 2]
 volume Integer 100 是 音量，数值越大声音越大，支持范围 [1, 400]
tts_query Object 包含内容如下 否 tts语音合成
 content String "尊敬的观众朋友们，大家好！非常荣幸能够在这个美好的时刻与大家相聚，欢迎收看今天的直播节目。" 是 待合成语音的文本内容，字数不得少于10个字，所有语言的发音人都可以合成英文query；所有语言的发音人都可以合成自己语言的query；粤语、沪语等中文方言发音人可以合成中文query
 ssml Boolean false 否 是否使用ssml，开启后query可以使用USSML和SSML ，推荐使用USSML
audios Object Array 包含内容如下 否 音频驱动，tts_query和audios都存在时，tts_query优先
 url String "https://xxx/audio.mp3" 是 数组，支持多条mp3格式的驱动音频文件
quick_response Object Array 包含内容如下 否 仅用于互动数字人下快速回复使用，使用接管接口发送快速回复数组中的序号，从0开始。-1代表随机选一条。
TTS文本和音频文件只支持一个，同时存在时TTS优先。口水词要么全部是TTS请求，要么全部是音频请求，请不要混用。
 tts_query Object 否 口水词的请求文本。TTS文本和音频文件只支持一个，同时存在时TTS优先。口水词要么全部是TTS请求，要么全部是音频请求，请不要混用。
  content String "您好，尊贵的客户" 是 口水词的文本内容
  ssml Boolean false 否 是否使用ssml请求
 audio String "https://xxx/audio.mp3" 否 口水词的音频接管文件地址。TTS文本和音频文件只支持一个，同时存在时TTS优先。口水词要么全部是TTS请求，要么全部是音频请求，请不要混用。
quick_response_preload_list Object Array ["001", "002", "003", "004"] 否 快速回复Preloaded material ID list，与quick_response同时存在时，素材ID列表优先
opening_words String "xxxxx" 否 仅用于互动数字人下开场白使用
backgrounds Object Array 包含内容如下 否 背景
 type Integer 0 是 0:图片，1:视频，支持mp4格式，分辨率暂无要求，不同分辨率的视频/图片按照短边撑满，长边居中截取形式处理，2:GIF（需注意GIF素材需要提前预热后才能使用，预热接口请见“平台能力-素材预热-FileId预热”）。
 name String "背景" 是 背景Name
 url String "https://xxx/bg.png" 是 背景文件url
 rect Int Array [0,0,1080,1920] 是 背景起始位置和大小，以1080*1920分辨率画布为参考
 cycle Boolean false 是 针对视频有效，false:单次播放，true:循环播放
 start Integer 0 是 背景开始时间，以ms为单位
 duration Integer -1 是 背景持续时间，以ms为单位，-1为默认值，表示随视频一直存在
 play_offset Integer 0 否 如果type=1，视频可以指定从第几秒开始播放（单位秒）
foregrounds Object Array 包含内容如下 否
 type Integer 0 是 0:图片，1:视频，2: GIF。支持多前景素材文件传入（需注意GIF素材需要提前预热后才能使用，预热接口请见“平台能力-素材预热-FileId预热”）。
 name String "前景" 是
 url String "https://xxx/fg.png" 是 前景文件url
 rect Int Array [0,0,1080,1920] 是 起始位置和大小，以1080*1920分辨率画布为参考
 start Integer 0 是 前景开始时间，以ms为单位
 duration Integer -1 是 前景持续时间，以ms为单位，-1为默认值，表示随视频一直存在
 play_offset Integer 0 否 如果type=1，视频可以指定从第几秒开始播放（单位秒）
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",
  "recycle": 0,
  "resolution": [1080,1920],
  "bit_rate": 5,
  "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": "zh-CN-XiaoxuanNeural",
        "name": "xiaoxuan",
        "vendor_id": 4,
        "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"
        }
      ],
      "quick_response": [
                        "我正在考虑一下,稍后给你答复。",
                        "让我想一想,稍后回复你消息。", 
                        "我需要时间来仔细考虑一下这个问题。",
                        "这个问题有点复杂,我需要稍后回复你。",
                        "我需要一些时间来准备一个详细的回答。",
                        "让我稍微思考一下,然后再回复你。",
                        "我会在稍后给你一个详细的答复,请稍等。",
                        "我会仔细思考这个问题,然后回复你。",
                        "我需要一些时间来彻底理解这个问题。",
                        "我会考虑一下,稍后再告诉你我的看法。"],
      "opening_words": "大家好，欢迎进入直播间",  
      "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": "http://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": {
          "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
        }
      }
    }
  ]
}

# Live Stream Takeover JSON Definition

# Introduction

Live stream takeover allows stopping the current scheduled live stream content through text or audio files during 2D digital human live streaming, switching to broadcast user-specified content, while also supporting replacement of foreground/background images during the takeover period.

# JSON Parameter Description
Name Type Example Required Description
tts_query Object 否 tts语音合成
 content String "尊敬的观众朋友们，大家好！非常荣幸能够在这个美好的时刻与大家相聚，欢迎收看今天的直播节目。" 是 待合成语音的文本内容，字数不得少于10个字
 ssml Boolean false 否 是否使用ssml，开启后query可以使用USSML和SSML ，推荐使用USSML
audio String "https://xxx/audio.mp3" 否 mp3格式的驱动音频文件，tts_query和audio都存在时，tts_query优先，忽略audio
foregrounds Object Array 包含内容如下 否 前景素材，需使用可中断的接管服务接口。
 type Integer 0 是 0:图片，1:视频，2: GIF。支持多前景素材文件传入（需注意GIF素材需要提前预热后才能使用，预热接口请见“平台能力-素材预热-FileId预热”）。
 url String "https://xxx/fg.png" 是 前景图片url，支持png或jpg
 rect Int Array [0,0,1080,1920] 是 起始位置和大小，以1080*1920分辨率画布为参考
 start Integer 0 是 前景图片开始出现时间，以ms为单位 ，若设置的接管图片出现时间点晚于TTS播报Completion time，则接管图片不显示，显示无图片效果；若设置的接管图片持续时间超过TTS播报持续时间，则接管图片显示至接管完成的最后时刻；若设置的接管图片持续时间短于TTS播报持续时间，则剩余接管时间内显示无图片效果
 duration Integer -1 是 前景图片持续时间，以ms为单位，-1为默认值，表示随接管持续一直存在
 play_offset Integer 0 否 如果type=1，视频可以指定从第几秒开始播放（单位秒）
backgrounds Object 包含内容如下 否 背景图片，需使用可中断的接管服务接口。
 url String "https://xxx/bg.png" 是 背景图片url，支持png或jpg
 rect Int Array [0,0,1080,1920] 是 起始位置和大小，以1080*1920分辨率画布为参考，图片按照短边撑满，长边居中截取形式处理
 start Integer 0 是 背景图片开始出现时间，以ms为单位，若设置的接管图片出现时间点晚于TTS播报Completion time，则接管图片不显示，显示无图片效果；若设置的接管图片持续时间超过TTS播报持续时间，则接管图片显示至接管完成的最后时刻；若设置的接管图片持续时间短于TTS播报持续时间，则剩余接管时间内显示无图片效果
 duration Integer -1 是 背景图片持续时间，以ms为单位，-1为默认值，表示随接管持续一直存在
 play_offset Integer 0 否 如果type=1，视频可以指定从第几秒开始播放（单位秒）
play_first Boolean false 否 是否打断正在播放的接管，默认为false，即排队逻辑
sei_info String "xxxx" 否 自用于自研RTMP推流添加SEI相关信息
# JSON File Example
{
  "tts_query": {
    "content": "尊敬的观众朋友们，大家好！下面插播一段新闻.",
    "ssml": false
  },
  "audio": "http://dwg-aigc-paas.oss-cn-hangzhou.aliyuncs.com/test/softsugar.mp3",

  "backgrounds": 
        {
          "url": "https://dwg-aigc-paas.oss-cn-hangzhou.aliyuncs.com/test/background.png",
          "rect": [
            0,
            0,
            1080,
            1920
          ],
          "start": 0,
          "duration": -1
        },
  "foregrounds": [
        {
          "url": "http://dwg-aigc-paas.oss-cn-hangzhou.aliyuncs.com/test/frontgroud.png",
          "rect": [
            0,
            0,
            310,
            88
          ],
          "start": 0,
          "duration": 100
        }
      ]

}

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

Last Updated: 4/10/2026, 3:13:22 PM

← Super Live Room Pro →