离线数字人

  新华智云离线数字人API，提供2D仿真数字人、3D写实数字人统一API合成服务

前提准备

标题部分 前提准备

1. 域名及请求加签

标题部分 1. 域名及请求加签

域名说明

https://api.shuwen.com

2. 数字人列表查询接口

标题部分 2. 数字人列表查询接口

2.1 接口调用

标题部分 2.1 接口调用
  • 请求地址：/open/digitalMan/pageQuery?pageNo=1&pageSize=10
  • 请求方式：GET
  • 说明：查询结果不包含声音及服饰信息

请求参数说明：

字段是否必填类型说明
pageNo是Integer分页页码
pageSize是Integer分页大小

2.2 接口结果

标题部分 2.2 接口结果
{
  "pageNo":1,
  "pageSize":10,
  "total":321,
  "data":[{
    "id":12,
    "name":"云小鹿",
    "description":"测试数字人的描述呀",
    "preImg":"https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
    "tenantId":"xxxxxx"
  }]
}

参数说明：

字段类型说明
pageNoInteger分页页码
pageSizeInteger分页大小
totalInteger数据总量
dataJSONArray数字人信息

data结构：

字段类型说明
idLong数字人id
nameString名称
descriptionString描述
preImgString预览图
tenantIdString租户ID

3. 数字人详情查询接口

标题部分 3. 数字人详情查询接口

3.1 接口调用

标题部分 3.1 接口调用
  • 请求地址：/open/digitalMan/detaiQuery/{id}
  • 请求方式：GET
  • 请求参数：数字人id，必填

3.2 接口结果

标题部分 3.2 接口结果
{
  "success": true,
  "data": {
    "id": 12,
    "name": "云小鹿",
    "description": "测试数字人的描述呀",
    "preImg": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
    "tenantId": "xxxxxx",
    "voices": [
      {
        "gender": "female",
        "name": "小云（标准）",
        "voiceId": "1",
        "type": "Alibaba",
        "maxVolume": 100,
        "minVolume": 0,
        "maxSpeed": 500,
        "minSpeed": -500,
        "maxTone": 500,
        "minTone": -500,
        "onTop": 0,
        "per": "1"
      }
    ],
    "clothes": [
      {
        "code": "91",
        "audioGenerate": "true",
        "fullBodyImg": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
        "cameraStands": [
          {
            "code": "front",
            "description": "正机位",
            "imgUrl": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png"
          }
        ],
        "emotions": [
          {
            "code": "12",
            "imgUrl": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
            "name": "测试情绪",
            "actions": [
              {
                "code": "123",
                "imgUrl": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/hosts/clear_virtual_xhzy_peiran_4_xhzy_2x_full.png",
                "name": "测试动作"
              }
            ]
          }
        ]
      }
    ]
  }
}

参数说明：

字段类型说明
voicesJSONArray数字人声音
clothesJSONArray数字人服饰
其余字段同2.2中data参数

voices结构：

字段类型说明
genderString发音人性别
nameString名称
voiceIdString声音ID（注：4.1算法调用时tts字段中per取该值）
typeString类型
maxVolumeInteger最大音量，用于4.1中tts音量可选范围
minVolumeInteger最小音量，用于4.1中tts音量可选范围
maxRateInteger最大语速，用于4.1中tts语速可选范围
minRateInteger最小语速，用于4.1中tts语速可选范围
maxPitchInteger最大语调，用于4.1中tts语调可选范围
minPitchInteger最小语调，用于4.1中tts语调可选范围
onTopInteger置顶顺序

clothes结构：

字段类型说明
codeString服饰code（注：4.1算法调用时avatar参数取该值）
fullBodyImgString全身图
audioGenerateBoolean是否支持音频驱动
cameraStandsJSONArray机位
emotionsJSONArray情绪集合（包含动作列表）

cameraStands结构：

字段类型说明
codeString机位code（注：4.1算法调用时speak标签中的camera标签取该值）
descriptionString描述
imgUrlString图片

emotions结构：

字段类型说明
codeString情绪code（注：4.1算法调用时speak标签中的emotion标签取该值）
nameString名称
imgUrlString图片
actionsJSONArray关联的动作

actions结构：

字段类型说明
codeString动作code（注：4.1算法调用时speak标签中的motion标签取该值）
nameString名称
imgUrlString图片

4. 数字人合成相关接口

标题部分 4. 数字人合成相关接口

4.1 合成接口调用

标题部分 4.1 合成接口调用
  • 请求地址：/open/digitalMan/batch/generate
  • 请求方式：POST
  • 请求参数：
{
    "generateParam": [
        {
            "algoParam": {
                "video": {
                    "width": 1080,
                    "height": 1920
                },
                "background": "https://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/resource/green_16_9.jpg",
                "tts": {
                    "text": "<speak rate=\"0\" pitch=\"0\" volume=\"50\">你好吗 今天天气真好</speak>",
                    "per": "1012"
                },
                "position": [
                    0,
                    0,
                    1080,
                    1801
                ],
                "code": "50",
                "is_green": true,
                "subtitle": true
            }
        }
    ],
    "callBackUrl":"http://xxxxxxx"
}

参数说明:

字段是否必须类型说明
generateParam是JSONArray合成参数
callBackUrl否String合成回调地址，回调方式需遵循4.5异步回调方式进行设计

generateParam结构：

字段是否必填类型说明
algoParam是JSONObject单个数字人合成任务的参数
extra否JSONObject业务扩展字段，结果查询时会透传

algoParam结构：

字段是否必填类型说明
video是JSONObject视频宽高
background是String视频背景
tts否JSONObject所需播报内容以及声音id，tts和audio_url必选一个
audio_url否String数字人详情字段中audioGenerate为ture时支持音频驱动，tts和audio_url必选一个，音频格式支持wav、pcm、mp3
position是JSONArray数字人在视频中占位[x,y,w,h]
code是String数字人唯一编码
is_green否Boolean是否是绿幕背景，默认false
subtitle否Boolean结果是否需要返回字幕，默认false

tts结构：

字段是否必填类型说明
text是String所需播报文本
per是String播报内容时所用声音id

说明：

  1. tts中的text字段可以带多个speak标签。
  2. speak标签中可以插入停顿，如：
<speak>测试<break time="500ms"/>一下</speak>
  1. <speak>标签可以设置属性，用于控制语音合成参数，也可控制控制主播表情、动作、机位，如：
    • rate用于控制TTS语速，
    • pitch用于控制TTS语调
    • volume用于控制TTS音量
    • motion用于控制主播动作
    • emotion用于控制主播表情
    • camera用于控制机位，3d主播才有
<speak rate="100" pitch="100" volume="100" motion="1" emotion="2" camera="left">今天是个好日子</speak>
  1. <speak>标签支持属性：
    • 语音停顿：<break>
    • 指定单个汉字的读音：<phoneme>
    • 指定分词：<w>

指定分词 <w>

  • 描述用于表示文本的词语结构，该标签是可选标签。英文文本通常采用空格来进行分词，一般无需使用此标签。<w>标签内部必须是一个独立的词或短语，这个词或短语不允许混合使用中文和其他外语。

例子：

<speak>南京市长<w>江大桥</w>今天发表了演讲。</speak>

语音停顿 <break>

  • 描述用于在文本中插入停顿，该标签是可选标签。
  • 属性说明

使用无属性的<break>标签时，停顿时长为“1s”。

属性名称属性类型属性值是否必选描述
timeString[number]s/[number]ms否以秒/毫秒为单位设置停顿的时长 （如“2s“、“50ms”）。
  • [number]s：以秒为单位，[number]取值范围为[1, 10]的整数。
  • [number]ms：以毫秒为单位，[number]取值范围为[50, 10000]的整数。 |

例子:

 <speak>
   请闭上眼睛休息一下<break time="500ms"/>好了，请睁开眼睛。
 </speak>

指定单个汉字的读音 <phoneme>

  • 描述用于控制标签内文本的读音，该标签是可选标签。英文文本不支持该标签。
  • 属性描述
属性名称属性类型属性值是否必选描述
alphabetStringpy是“py”表示拼音。
phString标签内文本对应的拼音串是拼音用法的赋值规范：
  • 字与字的拼音用空格分隔，拼音的数目必须与字数相等。
  • 每个拼音由发音和音调组成，音调为1~5的数字编号，其中”5”表示轻声。

例子：

 <speak>
    去<phoneme alphabet="py" ph="dian3 dang4 hang2">典当行</phoneme>把这个玩意<phoneme alphabet="py" ph="dang4 diao4">当掉</phoneme>
 </speak>
  1. audio_url需按<url>标签进行指定，相关标签内属性同上speak标签 例子：
<url rate="0" volume="50" motion="100" emotion="0" pitch="0" camera="front">
  https://video-mock.oss-cn-hangzhou.aliyuncs.com/upload/audio/mobile/df51e416-b0c5-4dff-bc91-84b78d7b65ec.mp3
</url>

4.2 合成接口结果

标题部分 4.2 合成接口结果

调用成功会返回任务的groupId

{
    "success": true,
    "code": "",
    "msg": "",
    "requestId": "",
    "data": "vh_05d8811ef2fe41ecb487af9c10ff20fe"
}

4.3 合成任务查询接口

标题部分 4.3 合成任务查询接口
  • 请求地址：/open/digitalMan/batch/query/{groupId}
  • 请求方式：GET
  • 请求参数：groupId

4.4 合成任务结果返回

标题部分 4.4 合成任务结果返回
{
    "success": true,
    "code": "",
    "msg": "",
    "requestId": "",
    "data": [
        {
            "id": "vh_25c8eaaebfaf4406b0f9fa92edd58bb7",
            "status": "completed",
            "duration": 3120.0,
            "composeUrl": "http://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/2022-05-23/c4838efb-e24f-4678-80a3-601ce3f5d6ac.mp4",
            "alphaVideoUrl": "http://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/2022-05-23/32ecdb1f-e581-4b39-9dcb-45033ac38f91.mp4",
            "textSegs": [
                {
                    "text": "你好吗 今天天气真好",
                    "startTime": 200,
                    "endTime": 2490
                }
            ],
            "extra": null,
            "errorMsg": null
        }
    ]
}

参数说明：

字段类型说明
idString任务id
statusString当前子任务合成状态
duration Double当前子任务视频的总时长,单位（毫秒）
composeUrlString当前子任务的合成视频，返回智云云上OSS地址，存在临时生命周期，建议客户自行转存（生命周期三个月）
alphaVideoUrlString当前子任务的alpha通道视频，返回智云云上OSS地址，存在临时生命周期，建议客户自行转存（生命周期三个月）
textSegsJSONArray当前子任务所播报内容的相关信息,可用于字幕合成，详见5.1
extraString业务扩展字段，透传
errorMsgString合成失败时的错误信息，详见7.

textSegs结构：

字段类型说明
textString文本内容
startTimeString文本内容开始播报时间,单位（毫秒）
endTimeString文本内容结束播报时间,单位（毫秒）

status结构： | 枚举类型 | 说明 | | | --- | --- | | | fail | 子任务合成失败，常见原因请见7. | | | waiting | 子任务正在合成中 | | | completed | 子任务合成完成 | |

4.5 异步回调方式

标题部分 4.5 异步回调方式

智云请求客户回调地址时，会根据客户aksk进行简单的签名字段生成，客户依据签名校验判断请求是否来自智云，防止对公的回调地址被攻击

统一异步回调aksk验证方式请移动网关认证文档 网关接入文档。

业务自定义的请求体内容:

{
  "code": 200,
  "message": "",
  "data": {
    "id": "vh_25c8eaaebfaf4406b0f9fa92edd58bb7",
    "status": "completed",
    "duration": 3120.0,
    "composeUrl": "http://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/2022-05-23/c4838efb-e24f-4678-80a3-601ce3f5d6ac.mp4",
    "alphaVideoUrl": "http://wordcup-entity.oss-cn-hangzhou.aliyuncs.com/virtual_host/2022-05-23/32ecdb1f-e581-4b39-9dcb-45033ac38f91.mp4",
    "textSegs": [
      {
        "text": "你好吗 今天天气真好",
        "startTime": 200,
        "endTime": 2490
      }
    ],
    "extra": null,
    "errorMsg": null
  },
  "groupId": "vh_25c8eaaebfaf4406b0f9fa92edd58bb0"
}

5. 字幕文件生成

标题部分 5. 字幕文件生成

5.1 接口调用

标题部分 5.1 接口调用

请求地址：/open/digitalMan/subtitle/generate 请求方式：POST 请求参数：

{
    "taskId":"vh_aac24aa2841547399978fc6fccfb6e92",
    "type":"ass"
}

参数说明：

字段类型说明
taskIdString任务id，取4.4合成返回结果中的id
typeString字幕类型，默认srt，可选ass

5.2 合成结果

标题部分 5.2 合成结果
{
    "success":true,
    "code":"",
    "msg":"",
    "requestId":"",
    "data":"https://xhzy-aiprod-production-template-manage.oss-cn-hangzhou.aliyuncs.com/vhost/subtitle/test/85180252-77da-418e-a9ff-893078bb2f4c.ass"
}

返回结果：

字段类型说明
dataString字幕ASS文件，，返回智云云上OSS地址，存在临时生命周期，建议客户自行转存（生命周期三个月）

6. 接口请求失败常见错误码

标题部分 6. 接口请求失败常见错误码

失败code码：

错误码说明
SW-DM-1000数字人合成任务创建失败
SW-DM-1001租户ID缺失
SW-DM-1002主参数缺失
SW-DM-1003generateParam参数缺失
SW-DM-1004generateParam.algoParam参数缺失
SW-DM-1005generateParam.algoParam.code数字人形象code参数缺失
SW-DM-1006generateParam.algoParam.tts数字人tts参数缺失
SW-DM-1007当前租户无权限合成该数字人code
SW-DM-1008generateParam.algoParam.tts.per参数缺失
SW-DM-1009传输的声音ID校验不通过,请从数字人详情中获取对应的voiceId
SW-DM-1010传输的数字人code校验不通过,请从数字人详情中clothes列表中获取对应的code字段值
SW-DM-1011当前数字人未有声音和形象列表