文档

StartInstance - 启动一个数字人

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

启动一路数字人视频流实例,通过传入指定的参数,可以启动一路数字人实例,该接口针对播报数字人、互动数字人等这类使用平台默认视频流渠道的数字人实例会返回阿里公有云RTC拉流需要的参数,使用者无需额外开通阿里公有云RTC产品服务,可直接通过阿里云RTC拉流SDK配合该接口返回的Channel参数进行拉流使用。关于阿里公有云RTC拉流SDK接入文档可参考数字人开放平台帮助中心《客户端SDK接入》文档。

接口说明

二方包引入可参考 API 概览的信息。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
avatar:StartInstanceWrite
  • 全部资源
    acs:avatar:*:{#accountId}:*

请求参数

名称类型必填描述示例值
TenantIdlong

租户 ID,从虚拟数字人开放平台的对应业务配置的开发者信息中获取的 TenantId

9185
Appobject

代表一个业务配置

AppIdstring

AppId,从虚拟数字人开放平台的对应业务配置的开发者信息中获取的 AppId

ALIPUB5748B17121450
Userobject

启动该数字人的用户信息(客户自身的用户信息,或者设备号等,如果没有可以直接传递随机数)

UserIdstring

客户自身的用户 ID,或者设备号等,如果没有可以直接传递一个随机数

23423
UserNamestring

与 UserId 对应的用户名,可空

测试用户
Channelobject

频道信息,将数字人流媒体推送到指定渠道。目前支持标准 RTMP 协议。

警告
  • 针对使用咨询播报(对应官方文档的播报数字人)和客服助理(对应官方文档的互动数字人)两个场景,请勿传此参数,平台会自动使用阿里云 RTC 渠道进行推流,同时官方文档中心提供了拉流端 SDK方便集成。
  • 仅针对使用虚拟主播(对应官方文档的推流数字人)场景需要传递对应的推流参数信息。
  • Typestring

    频道类型:

    • RTMP: RTMP 推流
    RTMP
    ReqConfigobject

    频道请求协议体,map 类型,

    • RTMP:
    {"url": ""}
    - url: 直播平台 RTMP 推流地址。
    

    警告 针对部分直播平台将推流地址分为 url 和 token,可直接将两部分拼接到一起放入 url 字段传入即可。推流地址的获取请从对应直播平台获取,部分直播平台不开放三方推流,无法获取 RTMP 推流地址。

    RTMP协议体: { "url" : "rtmp的地址" }
    CommandRequestobject

    数字人命令执行请求

    AlphaSwitchboolean

    是否需要透明。如果需要透明,设置 AlphaSwitch=true,同时拉流端需要接入流媒体拉流端 SDK:数字人流媒体服务 AndroidSDK数字人流媒体服务 WebSDK,参考文档实现对应的透明效果(可在文档中搜索“透明”关键字)。

    true:透明通道 false:非透明通道
    BackGroundImageUrlstring

    有效可访问的 url 背景图片地址,背景图片的宽高比必须要与生成的视频宽高比一致

    • 目前支持 jpg,jpeg,png 的图片格式
    可访问的公网url地址
    Locateinteger

    数字人机位

    • 0: 全身近景机位,默认机位
    • 1: 头部近景机位
    • 2: 全身远景机位
    • 3: 半身近景机位
    • 4: 半身远景机位
    • 5: 左边近景机位
    • 6: 右边近景机位

    具体每个机位的效果预览可以参考: 3D 数字人视频合成使用指南

    0
    BizIdstring

    业务请求 id,最大支持 64 位字符

    注意 可以使用该字段做业务启动数字人的幂等,服务端确保同一个 bizId 多次调用只会开启一路实例

    xxxxxxx
    TextRequestobject

    播报内容相关的设置参数

    PitchRateinteger

    TTS 播报声音语调,取值范围:-500~500,不传则使用资产中配置的默认值。

    0
    SpeechRateinteger

    TTS 播报声音语速,取值范围:-500~500,不传则使用资产中配置的默认值。

    [-500, 0, 500] 对应的语速倍速区间为 [0.5, 1.0, 2.0]。

    -500 表示基准语速的 0.5 倍速; 0 表示基准语速的 1 倍速。1 倍速是指模型默认输出的合成语速,语速会依据每一个发音人略有不同,大概每秒钟 4 个字左右; 500 表示基准语速的 2 倍速;

    计算方法如下:

    0.8 倍速(1-1/0.8)/0.002 = -125

    1.2 倍速(1-1/1.2)/0.001 = 166

    0
    Voicestring

    TTS 播报发音人 code,从虚拟数字人开放平台-2D 资产管理页面获取,不传则使用资产中配置的发音人。

    guijie
    Volumeinteger

    TTS 播报声音音量,取值范围:0~100,不传则使用资产中配置的默认值。

    0

    返回参数

    名称类型描述示例值
    object

    Schema of Response

    Codestring

    返回结果码

    0
    Messagestring

    返回信息

    错误信息示例
    Dataobject

    返回结果

    RequestIdstring

    请求 ID

    4C467B38-3910-447D-87BC-AC049166F216
    SessionIdstring

    会话 ID。标识这一路数字人实例的唯一 id,后续发送播报文本、停止数字人实例都需要传入该 ID,如果丢失可以通过“查询运行中的数字人实例”API 进行查询。

    4f63f9e9788449f9adc88d9438c8dec3
    Channelobject

    频道信息,目前返回互动和播报数字人平台默认视频流 AliRTC 渠道的频道信息,用于进行客户端拉流使用; 针对互动和推流数字人使用了三方推流通道的不会返回对应信息, 如 RTMP 推流。

    ChannelIdstring

    频道 ID

    108293819
    Tokenstring

    AliRTC 令牌码。

    e59f61b2482b4d0562ab542da3f824f7
    Typestring

    通道类型

    6
    ExpiredTimestring

    AliRTC 通道到期时间

    1677112265876
    Noncestring

    AliRTC 服务器生成的随机字符串。

    CK-9b5c335b9ae75879441ee7b363886418
    UserIdstring

    AliRTC 生成的 UserId

    userId
    AppIdstring

    AliRTC 应用 id

    ONEX7E28C7C221854
    UserInfoInChannelstring

    公有云音视频 RTC 需要的信息

    公有云音视频RTC需要的信息
    Gslbarray

    AliRTC 通道地址

    string

    AliRTC 通道地址

    https://rgslb.rtc.aliyuncs.com
    Tokenstring

    互动数字人对接需要的鉴权 token ,具体可参考互动数字人接入文档

    879441ee7b363886418
    Successboolean

    调用是否成功。

    True

    示例

    正常返回示例

    JSON格式

    {
      "Code": "0",
      "Message": "错误信息示例",
      "Data": {
        "RequestId": "4C467B38-3910-447D-87BC-AC049166F216",
        "SessionId": "4f63f9e9788449f9adc88d9438c8dec3",
        "Channel": {
          "ChannelId": "108293819",
          "Token": "e59f61b2482b4d0562ab542da3f824f7",
          "Type": "6",
          "ExpiredTime": "1677112265876",
          "Nonce": "CK-9b5c335b9ae75879441ee7b363886418",
          "UserId": "userId",
          "AppId": "ONEX7E28C7C221854",
          "UserInfoInChannel": "公有云音视频RTC需要的信息",
          "Gslb": [
            "https://rgslb.rtc.aliyuncs.com"
          ]
        },
        "Token": "879441ee7b363886418"
      },
      "Success": true
    }

    错误码

    访问错误中心查看更多错误码。

    变更历史

    变更时间变更内容概要操作
    2024-01-24OpenAPI 入参发生变更看变更集
    变更项变更内容
    入参OpenAPI 入参发生变更
      新增入参:TextRequest
    2023-11-08OpenAPI 入参发生变更看变更集
    变更项变更内容
    入参OpenAPI 入参发生变更
      新增入参:BizId
    2022-08-25OpenAPI 入参发生变更看变更集
    变更项变更内容
    入参OpenAPI 入参发生变更
      新增入参:CommandRequest