更新时间:2024-12-12 GMT+08:00

启动数字人智能直播任务

功能介绍

该接口用于启动数字人智能直播任务。

调用方法

请参见如何调用API

URI

POST /v1/{project_id}/smart-live-rooms/{room_id}/smart-live-jobs

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

项目ID,获取方法请参考获取项目ID

room_id

String

剧本ID。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。使用Token鉴权方式时必选。

通过调用IAM服务获取用户Token接口获取。

响应消息头中X-Subject-Token的值。

Authorization

String

使用AK/SK方式认证时必选,携带的鉴权信息。

X-Sdk-Date

String

使用AK/SK方式认证时必选,请求的发生时间。

格式为(YYYYMMDD'T'HHMMSS'Z')。

X-Project-Id

String

使用AK/SK方式认证时必选,携带项目ID信息。

X-App-UserId

String

第三方用户ID。不允许输入中文。

表3 请求Body参数

参数

是否必选

参数类型

描述

video_config

VideoConfig object

视频输出配置。

play_policy

PlayPolicy object

剧本播放策略

output_urls

Array of strings

参数解释

RTMP视频推流第三方直播平台地址。

说明:

直播过程中刷新地址,需要调用COMMAND命令REFRESH_OUTPUT_URL。

约束限制

不涉及

取值范围

当前仅支持一条RTMP出流地址。

默认取值

不涉及。

stream_keys

Array of strings

参数解释

RTMP视频推流第三方直播平台流密钥,与推流地址对应。

说明:

直播过程中刷新地址,需要调用COMMAND命令REFRESH_OUTPUT_URL。

约束限制

不涉及

取值范围

当前仅支持一条RTMP出流地址。

默认取值

不涉及。

interaction_callback_url

String

参数解释

互动回调URL,含鉴权信息。

互动规则trigger.reply_mode配置为CALLBACK时填写

约束限制

不涉及

取值范围

字符长度0-2048位

默认取值

不涉及。

live_event_callback_config

LiveEventCallBackConfig object

直播事件HTTPS回调通知配置

rtc_callback_config

RTCLiveEventCallBackConfig object

RTC回调事件配置。兼容处理,未携带配置则默认订阅LIVE_PROGRESS

view_mode

String

参数解释

横竖屏类型。

约束限制

用户无需填写,通过video_config中分辨率判断

取值范围

  • LANDSCAPE:横屏。

  • VERTICAL: 竖屏。

默认取值:

VERTICAL

co_streamer_config

CoStreamerConfig object

助播配置

表4 VideoConfig

参数

是否必选

参数类型

描述

clip_mode

String

参数解释

输出视频的剪辑方式。

约束限制

不涉及。

取值范围

  • RESIZE:视频缩放。

  • CROP:视频裁剪。

默认取值:

RESIZE

codec

String

参数解释

视频编码格式及视频文件格式。

约束限制

仅分身数字人视频制作支持VP8编码。

取值范围

  • H264:h264编码,输出mp4文件。

  • VP8:vp8编码,输出webm文件。

默认取值

不涉及

bitrate

Integer

参数解释

输出平均码率。单位:kbps。

约束限制

  • 分身数字人视频制作采用质量优先,可能会超过设置的码率。

  • 分身数字人直播码率范围[1000, 8000]。

默认取值

不涉及

取值范围:

40-30000

width

Integer

参数解释

视频宽度。单位:像素。

约束限制

  • clip_mode=RESIZE时,当前支持1920x1080、1080x1920、1280x720、720x1280、3840x2160、2160x3840六种分辨率。4K分辨率视频需要分身数字人模型支持4K的情况下才能使用。

  • clip_mode=CROP,裁剪后视频,(dx,dy)为原点,保留视频像宽度为width。

  • 分身数字人直播目前只支持1080x1920、1920x1080。

默认取值

不涉及

取值范围:

0-3840

height

Integer

参数解释

视频高度。

单位:像素。

约束限制

  • clip_mode=RESIZE时,当前支持1920x1080、1080x1920、1280x720、720x1280、3840x2160、2160x3840六种分辨率分辨率。

  • clip_mode=CROP,裁剪后视频,(dx,dy)为原点,保留视频像高度为height。

  • 分身数字人直播目前只支持1080x1920、1920x1080。

默认取值

不涉及

取值范围:

0-3840

frame_rate

String

参数解释

帧率。单位:FPS。

约束限制

分身数字人视频固定25FPS。

默认取值:

25

is_subtitle_enable

Boolean

参数解释

输出的视频是否带字幕。

约束限制

分身数字人直播暂时不支持字幕。

取值范围

  • true: 打开字幕

  • false: 关闭字幕

默认取值:

false

subtitle_config

SubtitleConfig object

字幕配置。

dx

Integer

参数解释

裁剪视频左上角像素点横坐标。

说明:

以模特分辨率为画布大小,比如1920*1080分辨率的模特,dx最小值是0,最大值是1920。

约束限制

clip_mode= CROP时生效。

默认取值

不涉及

取值范围:

-1920-3840

dy

Integer

参数解释

裁剪视频左上角像素点纵坐标。

说明:

以模特分辨率为画布大小,比如1920*1080分辨率的模特,dy最小值是0,最大值是1080

约束限制

clip_mode= CROP时生效。

默认取值

不涉及

取值范围:

-1920-3840

is_enable_super_resolution

Boolean

参数解释

视频是否开启超分。

约束限制

仅分身数字人视频制作支持。

取值范围

  • true: 开启

  • false: 不开启

默认取值:

false

is_end_at_first_frame

Boolean

参数解释

视频结束帧是否跟起始帧相同。需要多个数字人视频无缝拼接时设置成true。

约束限制

仅分身数字人视频制作支持。

取值范围

  • true: 开启

  • false: 不开启

默认取值:

false

表5 SubtitleConfig

参数

是否必选

参数类型

描述

dx

Integer

参数解释

字幕框左下角像素点坐标。

约束限制

不涉及。

默认取值

不涉及。

取值范围:

0-1920

dy

Integer

参数解释

字幕框左下角像素点坐标。

约束限制

不涉及。

默认取值

不涉及。

取值范围:

0-1920

font_name

String

参数解释

字体。当前支持的字体请参考服务支持的字体

约束限制

不涉及。

取值范围

字符长度0-64位

默认取值:

HarmonyOS_Sans_SC_Black

font_size

Integer

参数解释

字体大小。接口的取值范围为0-120,实际业务使用的取值范围要求为24-120,请以业务实际使用要求为准。

约束限制

不涉及。

取值范围:

0-120

默认取值:

54

h

Integer

参数解释

字幕框高度。

约束限制

参数h用于方便前端计算字幕框左上角坐标,后台不使用该参数。

取值范围:

0-1920

w

Integer

参数解释

字幕框宽度。

约束限制

  • 字幕框宽度固定为屏幕宽度的80%

  • 参数w用于方便前端计算字幕框左上角坐标,后台不使用该参数

取值范围:

0-1920

表6 PlayPolicy

参数

是否必选

参数类型

描述

repeat_count

Integer

参数解释

剧本重复播放次数。

  • -1:表示持续重复,直至人工停止。

  • 0:表示不重复,仅执行一次。

  • 其他值n:实际运行次数为n+1次。

约束限制

不涉及。

取值范围:

-1-100

默认取值:

0

auto_play_script

Boolean

参数解释

是否自动播放剧本。

约束限制

不涉及。

取值范围

  • true:服务完成任务初始化后,自动播放剧本。

  • false:服务完成任务初始化后,等待信号后再开始播放剧本。

默认取值:

true

play_mode

String

参数解释

驱动方式。

约束限制

不涉及。

取值范围

  • TEXT:文本驱动,即通过TTS合成语音。

  • AUDIO:语音驱动。

  • NO_PRESET:无预置剧本,人工控制模式。

默认取值:

TEXT

random_play_mode

String

参数解释

随机播报模式。

约束限制

从第二轮播报开始随机。

取值范围

  • NONE:不启动随机播报。

  • SCENE:按场景随机播报。场景内段落按顺序播报。

  • SCRIPT_ITEM:按段落随机播报。场景按顺序播报。

  • SCENE_AND_SCRIPT_ITEM:场景和段落都随机播报。

默认取值:

SCRIPT_ITEM

need_independent_capture_client

Boolean

参数解释

是否需要独立采集端。用于客户端播放与命令分离场景。

约束限制

不涉及。

取值范围

  • true:分配CAPTURE、PLAYER两个RTC用户。

  • fasle:仅分配PLAYER一个RTC用户。

默认取值:

false

表7 LiveEventCallBackConfig

参数

是否必选

参数类型

描述

live_event_type_callback_url

String

参数解释

直播事件回调地址,为https地址。

约束限制

不涉及。

取值范围

字符长度0-2048位。

默认取值

不涉及。

auth_type

String

参数解释

认证类型。

约束限制

不涉及。

取值范围

  • NONE:URL中自带认证。

  • MSS_A:HMACSHA256签名模式,在URL中追加参数hwSecret、hwTime。

    取值方式:hwSecret=hmac_sha256(Key, URI(live_event_callback_url)+ hwTime)&hwTime=hex(timestamp)

  • MSS_A_HEAD:HMACSHA256签名模式,参数hwSecret、hwTime放置在Head中。

    取值方式:x-hw-mss-secret=hmac_sha256(Key, URI(live_event_callback_url)+ hwTime)

    x-hw-mss-time=hex(timestamp)

  • MEITUAN_DEFAULT:仅用于美团平台调用回调使用。

默认取值:

NONE

key

String

参数解释

密钥Key。

约束限制

不涉及。

取值范围

字符长度0-32位。

默认取值

不涉及。

callback_event_type

Array of strings

参数解释

回调的直播事件类型列表。

约束限制

不涉及。

取值范围

当前仅支持如下取值:

  • SHOOT_SCRIPT_SWITCH:剧本段落切换事件。

  • RTMP_STREAM_STATE_CHANGE:RTMP链接发生变化回调事件。

  • REPLY_COMMAND_FINISH:回复播放完成通知。

回调事件结构体定义:

  • event_type:事件类型。

  • message:事件描述。

    • SHOOT_SCRIPT_SWITCH事件回调定义如下:

      {
        "event_type":  "SHOOT_SCRIPT_SWITCH",
        "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"scene_script_name\":\"商品1\",\"shoot_script_sequence_no\":\"2\",\"shoot_script_title\":\"段落2\"}"
      }
    • RTMP_STREAM_STATE_CHANGE回调定义如下:

      {
        "event_type":  "RTMP_STREAM_STATE_CHANGE",
        "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"output_url\":\"rtmp://xxx/xx/xx\",\"stream_key\":\"xxxxx\",\"state\":\"CONNECTED\"}"
      }

      其中state取值:CONNECTING链路连接中;CONNECTED链路已连接;DISCONNECTED链路已断开,RECONNECTING链路重连中;END联络不再重连,链路已结束。

    • REPLY_COMMAND_FINISH回调定义如下:

      {
        "event_type":  "REPLY_COMMAND_FINISH",
        "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"reply_id\":\"e87104f76d7546ce8a46ac6b04c49c3c"}"
      }
表8 RTCLiveEventCallBackConfig

参数

是否必选

参数类型

描述

rtc_callback_event_type

Array of strings

RTC回调的直播事件类型列表。

当前仅支持如下取值:

  • LIVE_PROGRESS:直播剧本进度通知。

  • REPLY_COMMAND_FINISH:回复播放完成通知。

回调事件结构体定义:

  • message_type:消息类型。

  • data:消息描述。

    • LIVE_PROGRESS事件回调定义如下:

      {
          "message_type": "live_progress_notify",
          "data": {
              "script_name": "场景一",
              "shoot_script_sequence_no": 2,
              "shoot_script_title": "引导语",
              "offset": "247",
              "reply_id": "e87104f76d7546ce8a46ac6b04c49c3c"
          }
      }
    • REPLY_COMMAND_FINISH回调定义如下:

      {
        "message_type": "reply_command_finish_notify",
        "data":"{
          "reply_id":"e87104f76d7546ce8a46ac6b04c49c3c"
        }"
      }
表9 CoStreamerConfig

参数

是否必选

参数类型

描述

voice_config

VoiceConfig object

语音配置参数。

streamer_action

String

参数解释

助播出声时主播行为设置。

约束限制

不涉及

取值范围

  • SILENCE:静默

  • VOLUME_DOWN:音量降低

默认取值

不涉及。

表10 VoiceConfig

参数

是否必选

参数类型

描述

voice_asset_id

String

参数解释

音色资产ID,可以从资产库中查询。

约束限制

不涉及。

取值范围

字符长度1-256位。

默认取值

不涉及。

speed

Integer

参数解释

语速。50表示0.5倍语速,100表示正常语速,200表示2倍语速。

当取值为“100”时,表示一个成年人的正常语速,约为250字/分钟。

约束限制

不涉及。

取值范围:

50-200

默认取值:

100

pitch

Integer

参数解释

音高。

约束限制

不涉及。

取值范围:

50-200

默认取值:

100

volume

Integer

参数解释

音量。

约束限制

不涉及。

取值范围:

90-240

默认取值:

140

响应参数

状态码: 202

表11 响应Header参数

参数

参数类型

描述

X-Request-Id

String

请求ID。

表12 响应Body参数

参数

参数类型

描述

job_id

String

直播任务ID。

rtc_room_info

RTCRoomInfoList object

RTC房间信息。

live_event_report_url

String

直播事件上报地址。用户将自行获取的直播间事件上报到此地址,用于触发智能互动,自动回复话术。

live_event_callback_config

LiveEventCallBackConfig object

直播事件HTTPS回调通知配置

live_warning_info

Array of LiveWarningItem objects

开播风险告警列表。

表13 RTCRoomInfoList

参数

参数类型

描述

app_id

String

RTC应用ID。

room_id

String

RTC房间ID。

users

Array of RTCUserInfo objects

加入RTC房间用户信息。

表14 RTCUserInfo

参数

参数类型

描述

user_type

String

用户类型。

  • CAPTURE: 直播助手,将摄像头获取视频流推送到RTC房间

  • ANIMATION: VDS服务,从RTC房间拉视频流生成动作数据

  • RENDER: 渲染服务,将动作数据渲染成数字人动画

  • PLAYER: 普通观看方,可选择原始视频流或者数字人动画视频流观看

  • INFERENCE_USER: 数字人推理端用户。从RTC房间接收音频流,并推送视频流到RTC房间

  • END_USER: 端侧用户。从推送音频流到RTC房间,并从RTC房间接收视频流

user_id

String

RTC用户ID。

signature

String

RTC鉴权token。

ctime

Long

有效期。时间戳,单位:秒。

取值范围:

0-4294967295

表15 LiveEventCallBackConfig

参数

参数类型

描述

live_event_type_callback_url

String

参数解释

直播事件回调地址,为https地址。

约束限制

不涉及。

取值范围

字符长度0-2048位。

默认取值

不涉及。

auth_type

String

参数解释

认证类型。

约束限制

不涉及。

取值范围

  • NONE:URL中自带认证。

  • MSS_A:HMACSHA256签名模式,在URL中追加参数hwSecret、hwTime。

    取值方式:hwSecret=hmac_sha256(Key, URI(live_event_callback_url)+ hwTime)&hwTime=hex(timestamp)

  • MSS_A_HEAD:HMACSHA256签名模式,参数hwSecret、hwTime放置在Head中。

    取值方式:x-hw-mss-secret=hmac_sha256(Key, URI(live_event_callback_url)+ hwTime)

    x-hw-mss-time=hex(timestamp)

  • MEITUAN_DEFAULT:仅用于美团平台调用回调使用。

默认取值:

NONE

key

String

参数解释

密钥Key。

约束限制

不涉及。

取值范围

字符长度0-32位。

默认取值

不涉及。

callback_event_type

Array of strings

参数解释

回调的直播事件类型列表。

约束限制

不涉及。

取值范围

当前仅支持如下取值:

  • SHOOT_SCRIPT_SWITCH:剧本段落切换事件。

  • RTMP_STREAM_STATE_CHANGE:RTMP链接发生变化回调事件。

  • REPLY_COMMAND_FINISH:回复播放完成通知。

回调事件结构体定义:

  • event_type:事件类型。

  • message:事件描述。

    • SHOOT_SCRIPT_SWITCH事件回调定义如下:

      {
        "event_type":  "SHOOT_SCRIPT_SWITCH",
        "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"scene_script_name\":\"商品1\",\"shoot_script_sequence_no\":\"2\",\"shoot_script_title\":\"段落2\"}"
      }
    • RTMP_STREAM_STATE_CHANGE回调定义如下:

      {
        "event_type":  "RTMP_STREAM_STATE_CHANGE",
        "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"output_url\":\"rtmp://xxx/xx/xx\",\"stream_key\":\"xxxxx\",\"state\":\"CONNECTED\"}"
      }

      其中state取值:CONNECTING链路连接中;CONNECTED链路已连接;DISCONNECTED链路已断开,RECONNECTING链路重连中;END联络不再重连,链路已结束。

    • REPLY_COMMAND_FINISH回调定义如下:

      {
        "event_type":  "REPLY_COMMAND_FINISH",
        "message":"{\"room_id\":\"26f065244f754b3aa853b649a21aaf66\",\"job_id\":\"e87104f76d7546ce8a46ac6b04c49c3c\",\"reply_id\":\"e87104f76d7546ce8a46ac6b04c49c3c"}"
      }
表16 LiveWarningItem

参数

参数类型

描述

warning_type

String

告警类型。

  • TOO_LESSS_SCRIPT_ITEMS:段落(话术)数量太少。

  • TOO_SHORT_SCRIPT_TIME:段落(话术)总时长太短。

  • TOO_LESS_DANMAKU_RULES: 弹幕互动规则太少。

  • RANDOM_PLAY_CLOSED: 随机播放开关关闭。

  • ROTATION_MODEL_CLOSED: 主播轮转未配置。

状态码: 400

表17 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

状态码: 401

表18 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

状态码: 500

表19 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

请求示例

POST https://{endpoint}/v1/70b76xxxxxx34253880af501cdxxxxxx/smart-live-rooms/24bad716-87b1-45e5-8912-6102f7693265/smart-live-jobs

{
  "output_urls" : [ "rtmp://vfxpush.hwcloudvr.cn/live/lysa" ]
}

响应示例

状态码: 202

成功。

{
  "job_id" : "26f06524-4f75-4b3a-a853-b649a21aaf66"
}

状态码: 400

{
  "error_code" : "MSS.00000003",
  "error_msg" : "Invalid parameter"
}

状态码: 401

{
  "error_code" : "MSS.00000001",
  "error_msg" : "Unauthorized"
}

状态码: 500

{
  "error_code" : "MSS.00000004",
  "error_msg" : "Internal Error"
}

状态码

状态码

描述

202

成功。

400

请求传参异常,包含错误码及对应描述。

401

未鉴权或鉴权失败。

500

内部服务错误。

错误码

请参见错误码