深声科技数字人接口文档

I. 接口调用基础

接口使用HTTP 1.1 协议，遵循RESTful规范；
接口调用的基础地址：https://api.deepsound.cn/
鉴权流程, 请参考深声官网签名方式: 签名方式

II. 数字人管理接口

数字人管理接口交互流程如下:

2.1 数字人生成

请求路径

接口标识请求路径请求方式说明

avatar.v1.2D.createModel /avatar/v1/2d/model/create POST 用于创建数字人。需要提前将视频素材转换为互联网可访问的URL。

接口标识	请求路径	请求方式	说明
avatar.v1.2D.createModel	/avatar/v1/2d/model/create	POST	用于创建数字人。需要提前将视频素材转换为互联网可访问的URL。

请求体

字段名	类型	是否必选	说明
video_url	URL	是	数字人视频链接，不超过256字符。视频需要符合视频录制标准。
callback_url	URL	否	数字人构建结果回调URL；回调调用规格请参考avatar.v1.2D.callback.createModel。
name	String	是	数字人名称，不超过64字符。
client_info	String	否	用户自定义的文本信息，用于标识、备注等用途；不超过256字符。

返回值

字段名	类型	是否返回	说明
code	Integer	是	响应成功时取值为整数0，其它取值详见状态码说明。
message	String	否	关于响应结果的说明。
data	Object	是	后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。
data.model_id	String	是	数字人创建之后的唯一id，用于后续的生成进度查询、视频生成。

错误码

错误码错误码说明

2005 不支持的视频类型

2006 视频大小不符合要求

错误码	错误码说明
2005	不支持的视频类型
2006	视频大小不符合要求

调用示例

curl 命令行

curl -X POST -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'Content-Length: 177' -H 'Content-Type: application/json' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 1218F24F52A36307C989C92F987056C5' -H 'X-Deepsound-Timestamp: 1664348729' -d '{"video_url": "https://tideo.oss-cn-shanghai.aliyuncs.com/upload/video/xxxx.mp4", "client_info": "{\"client_id\": 123456}", "callback_url": null, "name": "MyAvatar1"}' https://api.deepsound.cn/avatar/v1/2d/model/create

返回值

{
   "code": 0,
   "data": {
	  "model_id": "43667"
   },
   "message": "操作成功"
}

2.2 查询单个数字人状态

请求路径

接口标识	请求路径	请求方式	说明
avatar.v1.2D.modelStatus	/avatar/v1/2d/model/status?model_id=$Modelld	GET	查询数字人生成状态。参数$Modelld为avatar.v1.2D.createModel接口返回的model_id参数。

请求体

无

返回值

字段名	类型	是否返回	说明
code	Integer	是	响应成功时取值为整数0，其它取值详见状态码说明。
message	String	否	关于响应结果的说明。
data	Object	是	后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。
data.status	String	是	处理进度，可选值包括：CHECKING（视频检查中），CHECK_FAILED（视频检查失败），PROCESSING（处理中），SUCCESS（生成成功），FAILED（生成失败）；其中，CHECK_FAILED/FAILED状态会通过error_message返回具体的失败信息。
data.error_message	String	否	当data.status为CHECK_FAILED/FAILED时，该字段返回检查失败的具体原因。

错误码

错误码错误码说明

2007 视频下载失败

2008 视频中检测不到人脸

错误码	错误码说明
2007	视频下载失败
2008	视频中检测不到人脸

调用示例

curl 命令行

curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 9E3B863701AE7D2548E84BB65ED8308F' -H 'X-Deepsound-Timestamp: 1664348730' 'https://api.deepsound.cn/avatar/v1/2d/model/status?model_id=43667'

返回值

{
   "code": 0,
   "data": {
	  "model_id": "43667"
   },
   "message": "操作成功"
}

2.3 分页查询所有数字人状态

请求路径

接口标识请求路径请求方式说明

avatar.v1.2D.modelList /avatar/v1/2d/model/list?page_no=1&page_size=20 GET 查询所有数字人生成状态。参考分页调用约定。
请求体

无

接口标识	请求路径	请求方式	说明
avatar.v1.2D.modelList	/avatar/v1/2d/model/list?page_no=1&page_size=20	GET	查询所有数字人生成状态。参考分页调用约定。

返回值

字段名	类型	是否返回	说明
code	Integer	是	响应成功时取值为整数0，其它取值详见状态码说明。
message	String	否	关于响应结果的说明。
data	Object	是	后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。
data.page_total	Integer	是	总页数，参考分页调用约定。
data.model_list	List	是	本分页中的所有数字人信息列表。某个列表元素用 item 代表，item的字段如下。
item.status	String	是	数字人的处理状态，参考avatar.v1.2D.modelStatus中data.status返回值说明。
item.model_id	String	是	数字人id
item.client_info	String	否	创建数字人时输入的client_info字段数据。
item.name	String	是	创建数字人时输入的name字段数据。
item.version	String	是	数字人版本：normal=标准版，high=专业版

错误码

参考公共错误码

调用示例

curl 命令行

curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 2F31D41BAACEC91CEDB382644B6BE2BE' -H 'X-Deepsound-Timestamp: 1664348771' 'https://api.deepsound.cn/avatar/v1/2d/model/list?page_no=1&page_size=20'

返回值

{
   "code": 0,
   "data": {
	  "page_total": 2,
	  "model_list": [
	  {
		 "status": "SUCCESS",
		 "model_id": "43660",
		 "client_info": "",
		 "name": "wxm092001"
	  },
	  {
		 "status": "SUCCESS",
		 "model_id": "43661",
		 "client_info": "",
		 "name": "wxm092001"
	  },
	  {
		 "status": "SUCCESS",
		 "model_id": "43662",
		 "client_info": "",
		 "name": "wxm092001"
	  },
	  {
		 "status": "SUCCESS",
		 "model_id": "43663",
		 "client_info": "",
		 "name": "id183817_00001"
	  }]
   },
   "message": "操作成功"
}

III. 视频管理接口

视频管理接口交互流程如下:

3.1 数字人生成视频

请求路径

接口标识请求路径请求方式说明

avatar.v1.2D.createVideo /avatar/v1/2d/video/create POST 创建数字人视频生成任务。

接口标识	请求路径	请求方式	说明
avatar.v1.2D.createVideo	/avatar/v1/2d/video/create	POST	创建数字人视频生成任务。

请求体

字段名	类型	是否必选	说明
model_id	String	是	avatar.v1.2D.createModel接口返回的model_id参数。用于指定使用哪个数字人生成视频。
audio_url	URL	是	用于驱动数字人生成视频的音频链接；必须公网可访问。音频格式必须满足传入音频标准。
callback_url	URL	否	音频生成结果回调URL；回调调用规格：avatar.v1.2D.callback.createVideo。
video_info	String	否	用户自定义文本，用于标识该视频，或者视频的描述性文本等。不超过128个字符。
width	Integer	否	生成视频的宽度值，单位为像素。默认与数字人原始视频一致。
height	Integer	否	生成视频的高度值，单位为像素。默认与数字人原始视频一致。
fps	Float	否	帧速率，默认与数字人原始视频一致。
bitrate	Integer	否	视频码率，单位为kbps。
name	String	是	视频名称，不超过64个字。

返回值

字段名	类型	是否返回	说明
code	Integer	是	响应成功时取值为整数0，其它取值详见状态码说明。
message	String	否	关于响应结果的说明。
data	Object	是	后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。
data.video_id	String	是	视频任务的唯一id；用于查询视频合成任务状态，以及获取视频生成结果。

错误码

错误码	错误码说明
3001	音频累计时长超过商务许可范围，请联系深声商务。
3002	数字人模型无法使用；请联系深声技术团队。
3003	数字人模型未处理完成，请调用avatar.v1.2D.modelStatus接口确认模型可用后再执行生成任务。

调用示例

curl 命令行

curl -X POST -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'Content-Length: 245' -H 'Content-Type: application/json' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 2ADE85E81D523C4F6AA6AA6C26CD7E89' -H 'X-Deepsound-Timestamp: 1664348772' -d '{"model_id": "43667", "audio_url": "https://oss.tideo.cn/tideo/upload/file/xxxxx.wav", "callback_url": "", "video_info": "MyVideo1", "quality": "normal", "width": 1920, "height": 1080, "fps": "24", "bitrate": 3500, "name": "DemoVideo"}' https://api.deepsound.cn/avatar/v1/2d/video/create

返回值

{
   "code": 0,
   "data": {
	  "video_id": "10553"
   },
   "message": "操作成功"
}

3.2 查询单个视频生成状态

请求路径

接口标识	请求路径	请求方式	说明
avatar.v1.2D.videoStatus	/avatar/v1/2d/video/status?video_id=$Videold	GET	查询数字人视频生成状态。参数$Videold为avatar.v1.2D.createVideo返回的video_id参数。

请求体

无

返回值

字段名	类型	是否返回	说明
code	Integer	是	响应成功时取值为整数0，其它取值详见状态码说明。
message	String	否	关于响应结果的说明。
data	Object	是	后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。
data.status	String	是	视频合成进度，可选值包括：PROCESSING（处理中），SUCCESS（生成成功），FAILED（生成失败）。
data.video_url	URL	否	成功生成的视频的URL。
data.audio_duration	String	是	驱动数字人的音频时长，单位为秒；精确到毫秒。
data.mask_url	URL	否	视频人像部分的掩码视频。
data.expire_at	Integer	否	视频链接失效的秒级时间戳。
data.video_info	String	否	调用avatar.v1.2D.createVideo接口时传入的文本数据。
data.model_id	String	是	合成视频使用的数字人id。
data.error_message	String	否	当data.status = 'FAILED’时，返回失败的具体原因。

错误码

错误码	错误码说明
3000	视频任务不存在
3002	数字人模型无法使用；请联系深声技术团队。
3003	数字人模型未处理完成，请调用avatar.v1.2D.modelStatus接口确认模型可用后再执行生成任务。
3004	音频文件下载失败。

调用示例

curl 命令行

curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 0E2A173DB866D84F2E0F250288723ADA' -H 'X-Deepsound-Timestamp: 1664349052' 'https://api.deepsound.cn/avatar/v1/2d/video/status?video_id=10553'

返回值

{
	"code": 0,
	"data": {
	  "status": "SUCCESS",
	  "video_url": "https://ds-avatar-api-sz-prod.oss-cn-shenzhen.aliyuncs.com/avatar/result-xxxx.mp4",
	  "mask_url": "https://ds-avatar-api-sz-prod.oss-cn-shenzhen.aliyuncs.com/avatar/mask-xxxx.mp4",
	  "expire_at": 1664435452,
	  "video_info": "MyVideo1",
	  "model_id": "43667",
	  "error_message": "",
	  "audio_duration": "17.000",
	},
	"message": "操作成功"
}

3.3 分页查询所有视频生成任务

请求路径

接口标识请求路径请求方式说明

avatar.v1.2D.videoList /avatar/v1/2d/video/list?page_no=1&page_size=20 GET 查询所有数字人视频生成状态。参考分页调用约定。
请求体

无

接口标识	请求路径	请求方式	说明
avatar.v1.2D.videoList	/avatar/v1/2d/video/list?page_no=1&page_size=20	GET	查询所有数字人视频生成状态。参考分页调用约定。

返回值

字段名	类型	是否返回	说明
code	Integer	是	响应成功时取值为整数0，其它取值详见状态码说明。
message	String	否	关于响应结果的说明。
data	Object	是	后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。
data.page_total	Integer	是	总页数，参考分页调用约定。
data.video_list	List	是	本分页中的所有数字人信息列表。某个列表元素用 item 代表，item的字段如下。
item.status	String	是	视频的生成状态，参考avatar.v1.2D.videoStatus的返回值data.status说明。
item.video_id	String	是	视频id
item.video_info	String	否	创建数字人时输入的video_info字段数据。
item.audio_duration	String	是	驱动数字人的音频时长，单位为秒；精确到毫秒。
item.video_url	URL	否	参考avatar.v1.2D.videoStatus接口返回值中的data.video_url字段说明。
item.expire_at	Integer	否	参考avatar.v1.2D.videoStatus接口返回值中的data.expire_at字段说明。

错误码

参考公共错误码

调用示例

curl 命令行

curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 0E2A173DB866D84F2E0F250288723ADA' -H 'X-Deepsound-Timestamp: 1664349052' 'https://api.deepsound.cn/avatar/v1/2d/video/list?page_no=1&page_size=20'

返回值

{
   "code": 0,
   "data": {
	  "page_total": 1,
	  "video_list": [{
		 "status": "SUCCESS",
		 "video_id": "10553",
		 "video_info": "MyVideo1",
		 "video_url": "https://ds-avatar-api-sz-prod.oss-cn-shenzhen.aliyuncs.com/avatar/c5fa03e167322e220e109b176733be8b/result-158063.mp4",
		 "mask_url": "https://ds-avatar-api-sz-prod.oss-cn-shenzhen.aliyuncs.com/avatar/c5fa03e167322e220e109b176733be8b/mask-158063.mp4",
		 "expire_at": 1664435452,
		 "audio_duration": "17.045"
	  }]
   },
   "message": "操作成功"
}

IV. 回调接口规格

4.1 生成数字人回调

请求方法

接口标识请求方式说明

avatar.v1.2D.callback.createModel POST 生成数字人状态的回调接口。

接口标识	请求方式	说明
avatar.v1.2D.callback.createModel	POST	生成数字人状态的回调接口。

请求体

字段名	类型	是否必选	说明
model_id	String	是	avatar.v1.2D.createModel接口返回的model_id参数。用于标识数字人。
status	String	是	数字人生成状态。参考avatar.v1.2D.modelStatus中data.status字段说明。
error_message	String	否	data.status为FAILED时，标识失败的具体信息。

4.2 数字人生成视频回调

请求方法

接口标识请求方式说明

avatar.v1.2D.callback.createVideo POST 数字人生成视频状态的回调接口。

接口标识	请求方式	说明
avatar.v1.2D.callback.createVideo	POST	数字人生成视频状态的回调接口。

请求体

字段名	类型	是否必选	说明
video_id	String	是	avatar.v1.2D.createVideo接口返回的video_id参数。用于标识视频。
status	String	是	数字人生成状态。参考avatar.v1.2D.videoStatus中data.status字段说明。
error_message	String	否	data.status为FAILED时，标识失败的具体信息。
audio_duration	String	是	驱动数字人的音频时长，单位为秒；精确到毫秒。

V. 其他接口约定

5.1 音视频标准

视频录制标准：请联系深声商务获取。

传入音频标准：

支持的音频格式：WAV，MP3
音频为清晰的语音音频，以下为反例：
- 不含任何声音的静音音频
- 只含有器乐演奏，没有语音，或者在唱歌的音频
- 环境嘈杂的音频

5.2 公共错误码

错误码	错误码说明
1000	API服务异常，请联系深声技术团队处理。
1001	请求参数错误；具体错误字段可参考返回值中的message描述。
2000	数字人服务异常，请联系深声技术团队处理。
2001	数字人模型不存在，请核对请求参数。
2002	数字人接口授权时间超限，请联系深声商务。
2003	数字人模型数超限，请联系深声商务。

5.3 分页调用约定

在query参数中使用 page_size 参数指定页面大小；页面大小小于等于50。如不传入，默认为20。
在query参数中使用 page_no 参数指定分页页号；页号从1开始。如不传入，默认为1。
通过返回值中的 page_total 字段返回分页的总页数。

5.4 回调重试策略

数字人相关接口配置的回调接口，深声服务器在调用失败后，会按照如下配置进行重试。请保证回调接口的幂等性，不因为重试引起您的业务处理异常。

回调超时时间：5秒
回调重试次数：3次
重试间隔：15秒

5.5 返回值公共字段

code：接口调用错误码，0表示正常，其它请参考具体的接口定义。
message：接口错误的明细信息。
data: 接口返回的有效数据。

vConsole

Log System Network Element Storage

Error {message: "Cannot read property '0' ...

Error {message: "e.replaceAll is not a fun...

Name (8)

Method

Status

Time

https://www.deepsound.cn:8443/api/banner/list

GET

532ms

Response

https://www.deepsound.cn:8443/api/coorperation_type

GET

1383ms

Query String Parameters

scene

web

Response

https://business-api.deepsound.cn/business/rightcontact/queryContactInfo

GET

11ms

Query String Parameters

address

deepsound.cn

Response

/./doc/docIndex.json

GET

200

332ms

Query String Parameters

1715582917949

Response

[
 {
  "name": "深声科技OpenAPI说明文档",
  "url": "./doc/OpenAPI.md",
  "key": "OpenAPI"
 },
 {
  "name": "数字人接口文档",
  "url": "./doc/dhuman.md",
  "key": "dhuman"
 },
 {
  "name": "语音识别接口文档",
  "url": "./doc/asr.md",
  "key": "asr"
 },
 {
  "name": "语音合成接口(HTTP)",
  "url": "./doc/soundInterface.md",
  "key": "soundInterface"
 },
 {
  "name": "语音合成接口（WebSocket）",
  "url": "./doc/soundInterface_websocket.md",
  "key": "soundInterface_websocket"
 }
]

/./doc/dhuman.md

GET

200

332ms

Query String Parameters

1715582918223

Response

# 深声科技数字人接口文档

## I. 接口调用基础
1. 接口使用HTTP 1.1 协议，遵循RESTful规范；
2. 接口调用的基础地址：https://api.deepsound.cn/
3. 鉴权流程, 请参考深声官网签名方式: [签名方式](https://www.deepsound.cn/devDoc#OpenAPI)

## II. 数字人管理接口
数字人管理接口交互流程如下:
![图片](https://res.deepsound.cn/imgs/avatar_api/interact1.png)

### 2.1 数字人生成
* **请求路径**

	| 接口标识 | 请求路径 | 请求方式 | 说明 |
	| -------- | -------- | -------- | -------- |
	| avatar.v1.2D.createModel | /avatar/v1/2d/model/create | POST | 用于创建数字人。需要提前将视频素材转换为互联网可访问的URL。|

* **请求体**

	| 字段名 | 类型 | 是否必选 | 说明 |
	| -------- | -------- | -------- | -------- |
	| video_url | URL | 是 | 数字人视频链接，不超过256字符。视频需要符合**视频录制标准**。|
	| callback_url | URL | 否 | 数字人构建结果回调URL；回调调用规格请参考**avatar.v1.2D.callback.createModel**。 |
	| name | String | 是 | 数字人名称，不超过64字符。 |
	| client_info | String | 否 | 用户自定义的文本信息，用于标识、备注等用途；不超过256字符。 |

* **返回值**

	| 字段名 | 类型 | 是否返回 | 说明 |
	| -------- | -------- | -------- | -------- |
	| code | Integer | 是 | 响应成功时取值为整数0， 其它取值详见状态码说明。|
	| message | String | 否 | 关于响应结果的说明。 |
	| data | Object | 是 | 后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。 |
	| data.model_id | String | 是 | 数字人创建之后的唯一id，用于后续的生成进度查询、视频生成。 |

* **错误码**

	| 错误码 | 错误码说明 |
	| -------- | -------- |
	| 2005 | 不支持的视频类型 |
	| 2006 | 视频大小不符合要求 |

* **调用示例**
  * curl 命令行
	``` bash
	curl -X POST -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'Content-Length: 177' -H 'Content-Type: application/json' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 1218F24F52A36307C989C92F987056C5' -H 'X-Deepsound-Timestamp: 1664348729' -d '{"video_url": "https://tideo.oss-cn-shanghai.aliyuncs.com/upload/video/xxxx.mp4", "client_info": "{\"client_id\": 123456}", "callback_url": null, "name": "MyAvatar1"}' https://api.deepsound.cn/avatar/v1/2d/model/create
	```
  * 返回值
	``` json
	{
	   "code": 0,
	   "data": {
		  "model_id": "43667"
	   },
	   "message": "操作成功"
	}
	```

### 2.2 查询单个数字人状态
* **请求路径**

	| 接口标识 | 请求路径 | 请求方式 | 说明 |
	| -------- | -------- | -------- | -------- |
	| avatar.v1.2D.modelStatus | /avatar/v1/2d/model/status?model_id=$Modelld | GET | 查询数字人生成状态。参数$Modelld为**avatar.v1.2D.createModel**接口返回的model_id参数。|


* **请求体**

	无

* **返回值**

	| 字段名 | 类型 | 是否返回 | 说明 |
	| -------- | -------- | -------- | -------- |
	| code | Integer | 是 | 响应成功时取值为整数0， 其它取值详见状态码说明。|
	| message | String | 否 | 关于响应结果的说明。 |
	| data | Object | 是 | 后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。 |
	| data.status | String | 是 | 处理进度，可选值包括：CHECKING（视频检查中），CHECK_FAILED（视频检查失败），PROCESSING（处理中），SUCCESS（生成成功），FAILED（生成失败）；其中，CHECK_FAILED/FAILED状态会通过error_message返回具体的失败信息。 |
	| data.error_message | String | 否 | 当data.status为CHECK_FAILED/FAILED时，该字段返回检查失败的具体原因。 |

* **错误码**

	| 错误码 | 错误码说明 |
	| -------- | -------- |
	| 2007 | 视频下载失败 |
	| 2008 | 视频中检测不到人脸 |


* **调用示例**
  * curl 命令行
	``` bash
	curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 9E3B863701AE7D2548E84BB65ED8308F' -H 'X-Deepsound-Timestamp: 1664348730' 'https://api.deepsound.cn/avatar/v1/2d/model/status?model_id=43667'
	```
  * 返回值
	``` json
	{
	   "code": 0,
	   "data": {
		  "model_id": "43667"
	   },
	   "message": "操作成功"
	}
	```

### 2.3 分页查询所有数字人状态
* **请求路径**

	| 接口标识 | 请求路径 | 请求方式 | 说明 |
	| -------- | -------- | -------- | -------- |
	| avatar.v1.2D.modelList | /avatar/v1/2d/model/list?page_no=1&page_size=20 | GET | 查询所有数字人生成状态。参考**分页调用约定**。|

* **请求体**

	无

* **返回值**

	| 字段名 | 类型 | 是否返回 | 说明 |
	| -------- | -------- | -------- | -------- |
	| code | Integer | 是 | 响应成功时取值为整数0， 其它取值详见状态码说明。|
	| message | String | 否 | 关于响应结果的说明。 |
	| data | Object | 是 | 后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。 |
	| data.page_total | Integer | 是 | 总页数，参考**分页调用约定**。 |
	| data.model_list | List | 是 | 本分页中的所有数字人信息列表。某个列表元素用 item 代表，item的字段如下。 |
	| item.status | String | 是 | 数字人的处理状态，参考**avatar.v1.2D.modelStatus**中data.status返回值说明。 |
	| item.model_id | String | 是 | 数字人id |
	| item.client_info | String | 否 | 创建数字人时输入的client_info字段数据。 |
	| <span>item.name</span> | String | 是 | 创建数字人时输入的name字段数据。 |
	| item.version | String | 是 | 数字人版本：normal=标准版，high=专业版 |


* **错误码**

	参考公共错误码


* **调用示例**
  * curl 命令行
	``` bash
	curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 2F31D41BAACEC91CEDB382644B6BE2BE' -H 'X-Deepsound-Timestamp: 1664348771' 'https://api.deepsound.cn/avatar/v1/2d/model/list?page_no=1&page_size=20'
	```
  * 返回值
	``` json
	{
	   "code": 0,
	   "data": {
		  "page_total": 2,
		  "model_list": [
		  {
			 "status": "SUCCESS",
			 "model_id": "43660",
			 "client_info": "",
			 "name": "wxm092001"
		  },
		  {
			 "status": "SUCCESS",
			 "model_id": "43661",
			 "client_info": "",
			 "name": "wxm092001"
		  },
		  {
			 "status": "SUCCESS",
			 "model_id": "43662",
			 "client_info": "",
			 "name": "wxm092001"
		  },
		  {
			 "status": "SUCCESS",
			 "model_id": "43663",
			 "client_info": "",
			 "name": "id183817_00001"
		  }]
	   },
	   "message": "操作成功"
	}
	```


## III. 视频管理接口
视频管理接口交互流程如下:
![图片](https://res.deepsound.cn/imgs/avatar_api/interact2.png)

### 3.1 数字人生成视频
* **请求路径**

	| 接口标识 | 请求路径 | 请求方式 | 说明 |
	| -------- | -------- | -------- | -------- |
	| avatar.v1.2D.createVideo | /avatar/v1/2d/video/create | POST | 创建数字人视频生成任务。 |

* **请求体**

	| 字段名 | 类型 | 是否必选 | 说明 |
	| -------- | -------- | -------- | -------- |
	| model_id | String | 是 | **avatar.v1.2D.createModel**接口返回的model_id参数。用于指定使用哪个数字人生成视频。|
	| audio_url | URL | 是 | 用于驱动数字人生成视频的音频链接；必须公网可访问。音频格式必须满足**传入音频标准**。 |
	| callback_url | URL | 否 | 音频生成结果回调URL；回调调用规格：**avatar.v1.2D.callback.createVideo**。|
	| video_info | String | 否 | 用户自定义文本，用于标识该视频，或者视频的描述性文本等。不超过128个字符。 |
	| width | Integer | 否 | 生成视频的宽度值，单位为像素。默认与数字人原始视频一致。 |
	| height | Integer | 否 | 生成视频的高度值，单位为像素。默认与数字人原始视频一致。 |
	| fps | Float | 否 | 帧速率，默认与数字人原始视频一致。 |
	| bitrate | Integer | 否 | 视频码率，单位为kbps。 |
	| name | String | 是 | 视频名称，不超过64个字。 |


* **返回值**

	| 字段名 | 类型 | 是否返回 | 说明 |
	| -------- | -------- | -------- | -------- |
	| code | Integer | 是 | 响应成功时取值为整数0， 其它取值详见状态码说明。|
	| message | String | 否 | 关于响应结果的说明。 |
	| data | Object | 是 | 后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。 |
	| data.video_id | String | 是 | 视频任务的唯一id；用于查询视频合成任务状态，以及获取视频生成结果。 |


* **错误码**

	| 错误码 | 错误码说明 |
	| -------- | -------- |
	| 3001 | 音频累计时长超过商务许可范围，请联系深声商务。 |
	| 3002 | 数字人模型无法使用；请联系深声技术团队。 |
	| 3003 | 数字人模型未处理完成，请调用**avatar.v1.2D.modelStatus**接口确认模型可用后再执行生成任务。 |


* **调用示例**
  * curl 命令行
	``` bash
	curl -X POST -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'Content-Length: 245' -H 'Content-Type: application/json' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 2ADE85E81D523C4F6AA6AA6C26CD7E89' -H 'X-Deepsound-Timestamp: 1664348772' -d '{"model_id": "43667", "audio_url": "https://oss.tideo.cn/tideo/upload/file/xxxxx.wav", "callback_url": "", "video_info": "MyVideo1", "quality": "normal", "width": 1920, "height": 1080, "fps": "24", "bitrate": 3500, "name": "DemoVideo"}' https://api.deepsound.cn/avatar/v1/2d/video/create
	```
  * 返回值
	``` json
	{
	   "code": 0,
	   "data": {
		  "video_id": "10553"
	   },
	   "message": "操作成功"
	}
	```

### 3.2 查询单个视频生成状态
* **请求路径**

	| 接口标识 | 请求路径 | 请求方式 | 说明 |
	| -------- | -------- | -------- | -------- |
	| avatar.v1.2D.videoStatus | /avatar/v1/2d/video/status?video_id=$Videold | GET | 查询数字人视频生成状态。参数$Videold为**avatar.v1.2D.createVideo**返回的video_id参数。 |

* **请求体**

	无

* **返回值**

	| 字段名 | 类型 | 是否返回 | 说明 |
	| -------- | -------- | -------- | -------- |
	| code | Integer | 是 | 响应成功时取值为整数0， 其它取值详见状态码说明。|
	| message | String | 否 | 关于响应结果的说明。 |
	| data | Object | 是 | 后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。 |
	| data.status | String | 是 | 视频合成进度，可选值包括：PROCESSING（处理中），SUCCESS（生成成功），FAILED（生成失败）。 |
	| data.video_url | URL | 否 | 成功生成的视频的URL。 |
	| data.audio_duration | String | 是 | 驱动数字人的音频时长，单位为秒；精确到毫秒。|
	| data.mask_url | URL | 否 | 视频人像部分的掩码视频。 |
	| data.expire_at | Integer | 否 | 视频链接失效的秒级时间戳。 |
	| data.video_info | String | 否 | 调用**avatar.v1.2D.createVideo**接口时传入的文本数据。 |
	| data.model_id | String | 是 | 合成视频使用的数字人id。 |
	| data.error_message | String | 否 | 当data.status = 'FAILED'时，返回失败的具体原因。 |


* **错误码**

	| 错误码 | 错误码说明 |
	| -------- | -------- |
	| 3000 | 视频任务不存在 |
	| 3002 | 数字人模型无法使用；请联系深声技术团队。 |
	| 3003 | 数字人模型未处理完成，请调用**avatar.v1.2D.modelStatus**接口确认模型可用后再执行生成任务。 |
	| 3004 | 音频文件下载失败。 |


* **调用示例**
  * curl 命令行
	``` bash
	curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 0E2A173DB866D84F2E0F250288723ADA' -H 'X-Deepsound-Timestamp: 1664349052' 'https://api.deepsound.cn/avatar/v1/2d/video/status?video_id=10553'
	```
  * 返回值
	``` json
	{
		"code": 0,
		"data": {
		  "status": "SUCCESS",
		  "video_url": "https://ds-avatar-api-sz-prod.oss-cn-shenzhen.aliyuncs.com/avatar/result-xxxx.mp4",
		  "mask_url": "https://ds-avatar-api-sz-prod.oss-cn-shenzhen.aliyuncs.com/avatar/mask-xxxx.mp4",
		  "expire_at": 1664435452,
		  "video_info": "MyVideo1",
		  "model_id": "43667",
		  "error_message": "",
		  "audio_duration": "17.000",
		},
		"message": "操作成功"
	}
	```

### 3.3 分页查询所有视频生成任务
* **请求路径**

	| 接口标识 | 请求路径 | 请求方式 | 说明 |
	| -------- | -------- | -------- | -------- |
	| avatar.v1.2D.videoList | /avatar/v1/2d/video/list?page_no=1&page_size=20 | GET | 查询所有数字人视频生成状态。参考**分页调用约定**。 |

* **请求体**

	无

* **返回值**

	| 字段名 | 类型 | 是否返回 | 说明 |
	| -------- | -------- | -------- | -------- |
	| code | Integer | 是 | 响应成功时取值为整数0， 其它取值详见状态码说明。|
	| message | String | 否 | 关于响应结果的说明。 |
	| data | Object | 是 | 后续表格中，"data.x"表示data对象的属性x。如果code不为0，data字段为空，data中的其他数据将无法获取。 |
	| data.page_total | Integer | 是 | 总页数，参考**分页调用约定**。 |
	| data.video_list | List | 是 | 本分页中的所有数字人信息列表。某个列表元素用 item 代表，item的字段如下。 |
	| item.status | String | 是 | 视频的生成状态，参考**avatar.v1.2D.videoStatus**的返回值data.status说明。 |
	| item.video_id | String | 是 | 视频id |
	| item.video_info | String | 否 | 创建数字人时输入的video_info字段数据。 |
	| item.audio_duration | String | 是 | 驱动数字人的音频时长，单位为秒；精确到毫秒。|
	| item.video_url | URL | 否 | 参考**avatar.v1.2D.videoStatus**接口返回值中的data.video_url字段说明。 |
	| item.expire_at | Integer | 否 | 参考**avatar.v1.2D.videoStatus**接口返回值中的data.expire_at字段说明。 |


* **错误码**

	参考公共错误码


* **调用示例**
  * curl 命令行
	``` bash
	curl -X GET -H 'Accept: */*' -H 'Accept-Encoding: gzip, deflate, br' -H 'Connection: keep-alive' -H 'X-Deepsound-Appid: testAppId' -H 'X-Deepsound-Sign: MD5 0E2A173DB866D84F2E0F250288723ADA' -H 'X-Deepsound-Timestamp: 1664349052' 'https://api.deepsound.cn/avatar/v1/2d/video/list?page_no=1&page_size=20'
	```
  * 返回值
	``` json
	{
	   "code": 0,
	   "data": {
		  "page_total": 1,
		  "video_list": [{
			 "status": "SUCCESS",
			 "video_id": "10553",
			 "video_info": "MyVideo1",
			 "video_url": "https://ds-avatar-api-sz-prod.oss-cn-shenzhen.aliyuncs.com/avatar/c5fa03e167322e220e109b176733be8b/result-158063.mp4",
			 "mask_url": "https://ds-avatar-api-sz-prod.oss-cn-shenzhen.aliyuncs.com/avatar/c5fa03e167322e220e109b176733be8b/mask-158063.mp4",
			 "expire_at": 1664435452,
			 "audio_duration": "17.045"
		  }]
	   },
	   "message": "操作成功"
	}
	```

## IV. 回调接口规格

### 4.1 生成数字人回调

* **请求方法**

	| 接口标识 | 请求方式 | 说明 |
	| -------- | -------- | -------- |
	| avatar.v1.2D.callback.createModel | POST | 生成数字人状态的回调接口。 |

* **请求体**

	| 字段名 | 类型 | 是否必选 | 说明 |
	| -------- | -------- | -------- | -------- |
	| model_id | String | 是 | **avatar.v1.2D.createModel**接口返回的model_id参数。用于标识数字人。|
	| status | String | 是 | 数字人生成状态。参考**avatar.v1.2D.modelStatus**中data.status字段说明。|
	| error_message | String | 否 | data.status为FAILED时，标识失败的具体信息。 |


### 4.2 数字人生成视频回调

* **请求方法**

	| 接口标识 | 请求方式 | 说明 |
	| -------- | -------- | -------- |
	| avatar.v1.2D.callback.createVideo | POST | 数字人生成视频状态的回调接口。 |

* **请求体**

	| 字段名 | 类型 | 是否必选 | 说明 |
	| -------- | -------- | -------- | -------- |
	| video_id | String | 是 | **avatar.v1.2D.createVideo**接口返回的video_id参数。用于标识视频。|
	| status | String | 是 | 数字人生成状态。参考**avatar.v1.2D.videoStatus**中data.status字段说明。|
	| error_message | String | 否 | data.status为FAILED时，标识失败的具体信息。 |
	| audio_duration | String | 是 | 驱动数字人的音频时长，单位为秒；精确到毫秒。|

## V. 其他接口约定

### 5.1 音视频标准
视频录制标准：请联系深声商务获取。

传入音频标准：
  * 支持的音频格式：WAV，MP3
  * 音频为清晰的语音音频，以下为反例：
	* 不含任何声音的静音音频
	* 只含有器乐演奏，没有语音，或者在唱歌的音频
	* 环境嘈杂的音频

### 5.2 公共错误码

| 错误码 | 错误码说明 |
| -------- | -------- |
| 1000 | API服务异常，请联系深声技术团队处理。 |
| 1001 | 请求参数错误；具体错误字段可参考返回值中的message描述。 |
| 2000 | 数字人服务异常，请联系深声技术团队处理。 |
| 2001 | 数字人模型不存在，请核对请求参数。 |
| 2002 | 数字人接口授权时间超限，请联系深声商务。 |
| 2003 | 数字人模型数超限，请联系深声商务。 |

### 5.3 分页调用约定
* 在query参数中使用 page_size 参数指定页面大小；页面大小小于等于50。如不传入，默认为20。
* 在query参数中使用 page_no 参数指定分页页号；页号从1开始。如不传入，默认为1。
* 通过返回值中的 page_total 字段返回分页的总页数。

### 5.4 回调重试策略
数字人相关接口配置的回调接口，深声服务器在调用失败后，会按照如下配置进行重试。请保证回调接口的幂等性，不因为重试引起您的业务处理异常。
* 回调超时时间：5秒
* 回调重试次数：3次
* 重试间隔：15秒

### 5.5 返回值公共字段
* code：接口调用错误码，0表示正常，其它请参考具体的接口定义。
* message：接口错误的明细信息。
* data: 接口返回的有效数据。

https://business-api.deepsound.cn/business/bottomcontact/queryContactInfo

GET

332ms

Query String Parameters

address

deepsound.cn

Response

https://www.deepsound.cn:8443/api/sign

POST

331ms

Form Data

href

http%3A%2F%2Flocalhost%3A8000%2FdevDoc%23dhuman

Response

https://www.deepsound.cn:8443/api/sign

POST

50ms

Form Data

href

http%3A%2F%2Flocalhost%3A8000%2FdevDoc%23dhuman

Response

深声科技

数字人

语音识别

语音合成

声音克隆定制

开发者中心

关于深声

大道至简

深声科技数字人接口文档

I. 接口调用基础

II. 数字人管理接口

2.1 数字人生成

2.2 查询单个数字人状态

2.3 分页查询所有数字人状态

III. 视频管理接口

3.1 数字人生成视频

3.2 查询单个视频生成状态

3.3 分页查询所有视频生成任务

IV. 回调接口规格

4.1 生成数字人回调

4.2 数字人生成视频回调

V. 其他接口约定

5.1 音视频标准

5.2 公共错误码

5.3 分页调用约定

5.4 回调重试策略

5.5 返回值公共字段

深声科技

数字人

语音识别

语音合成

通用语音合成

粤语语音合成

情感语音合成

声音克隆定制

开发者中心

关于深声

最新资讯

深声介绍

加入深声

大道至简

深声科技数字人接口文档

I. 接口调用基础

II. 数字人管理接口

2.1 数字人生成

2.2 查询单个数字人状态

2.3 分页查询所有数字人状态

III. 视频管理接口

3.1 数字人生成视频

3.2 查询单个视频生成状态

3.3 分页查询所有视频生成任务

IV. 回调接口规格

4.1 生成数字人回调

4.2 数字人生成视频回调

V. 其他接口约定

5.1 音视频标准

5.2 公共错误码

5.3 分页调用约定

5.4 回调重试策略

5.5 返回值公共字段