API接入文档

一、 接入准备

1.1 获取Accesskey

与我司商务合作后，我司会给客户appId和appSecret。请妥善保存appSecret

1.2 开发以及联调测试

客户通过appId和appSecret获取token，将token放入header头中可以请求对应的接口。

二、 API对接方式

2.1 构造签名获取token

通过appId和appSecret请求/duix-openapi/v1/AccessToken接口可以获得token。

2.2 公共返回参数

duix得到token和其他请求数据集合后，会先进行安全校验等验证，一系列验证通过后便会处理完成这次发送过来的数据请求，平台返回的参数格式如下：

字段	类型	是否必须	备注
code	string	Y	返回的状态码，为0表示成功
message	string	N	成功/错误的描述信息
data	object	N	返回的具体内容

2.3 公共错误码

错误码	描述
0	正常
-1	失败
1005	token不能为空
40001	appid或者appscrect无效
40002	内部错误

三、 API接口

3.1 获取token

接口地址: /duix-openapi/v1/AccessToken

请求方式: POST

请求数据类型: application/json

响应数据类型: */*

接口描述: 传入appId和appSecret

请求参数:

参数名称	参数说明	in	是否必须	数据类型	schema
appId	appId	string	true
appSecret	appSecret	string	true

响应状态:

状态码	说明	schema
200	OK	DMResponse«string»
201	Created
401	Unauthorized
403	Forbidden
404	Not Found

响应参数:

参数名称	参数说明	类型	schema
code		string
data		string
message		string
success		boolean

响应示例:

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

3.2 关闭企业所有会话

接口地址: /duix-openapi/v1/distroyCallSessionsByCropId

请求方式: GET

请求数据类型: *

响应数据类型: */*

接口描述:

请求参数:

将token放入header头中请求

响应状态:

状态码	说明	schema
200	OK	DMResponse«string»
401	Unauthorized
403	Forbidden
404	Not Found

响应参数:

参数名称	参数说明	类型	schema
code		string
data		string
message		string
success		boolean

响应示例:

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

3.3 获取企业实时会话

接口地址: /duix-openapi/v1/getconcurrentList

请求方式: GET

请求数据类型: *

响应数据类型: */*

接口描述:

请求参数:

将token放入header头中请求

响应状态:

状态码	说明	schema
200	OK	DMResponse«string»
401	Unauthorized
403	Forbidden
404	Not Found

响应参数:

参数名称	参数说明	类型	schema
code		string
data		string
message		string
success		boolean

响应示例:

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

3.4 获取企业实时并发数

接口地址: /duix-openapi/v1/getconcurrentNumber

请求方式: GET

请求数据类型: *

响应数据类型: */*

接口描述:

请求参数:

将token放入header头中请求

响应状态:

状态码	说明	schema
200	OK	DMResponse«ConcurrentStatus»
401	Unauthorized
403	Forbidden
404	Not Found

响应参数:

参数名称	参数说明	类型	schema
code		string
data		ConcurrentStatus	ConcurrentStatus
cropId		string
totalConcurrentNumber		integer(int32)
userConcurrentNumber		integer(int32)
message		string
success		boolean

响应示例:

{
    "code": "",
    "data": {
        "cropId": "",
        "totalConcurrentNumber": 0,
        "userConcurrentNumber": 0
    },
    "message": "",
    "success": true
}

3.5 关闭指定会话

接口地址: /duix-openapi/v1/sessionStop

请求方式: GET

请求数据类型: *

响应数据类型: */*

接口描述:

请求参数:

将token放入header头中请求

参数名称	参数说明	in	是否必须	数据类型	schema
uuid	uuid	query	true	string

响应状态:

状态码	说明	schema
200	OK	DMResponse«string»
401	Unauthorized
403	Forbidden
404	Not Found

响应参数:

参数名称	参数说明	类型	schema
code		string
data		string
message		string
success		boolean

响应示例:

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

回调接口 接口地址: 客户在官网配置

请求方式: POST

请求数据类型: application/json

响应数据类型: */*

请求参数:

参数名称	参数说明	是否必须	数据类型	schema
uuid	uuid	true	string
status	status	true	string	start/stop
timestamp	时间戳	true	long

说明: 事件的时间以戳时间为准, 事件触发只回调一次。请保持回调接口畅通。

3.6 第三方话术对接

其他会话集成: 其他会话平台可以通过以下的方式提供给数字人使用。DUIX平台可以通过你的数字人，使用POST方式请求一个你定义的远程URL，来获取问题的答案。

会话平台集成样例: 可以参考这个会话平台集成的例子。这个开源的应用实现了一个对话平台集成，该样例应用实现闲聊会话功能。

请求规范: DUIX平台将问题请求（客户想你的数字人提出的）按照以下格式，通过POST方式发送至你远程URL。

头文件:

Key	Value
Content-Type	application/json

参数体: json

Field	Type	Description	Required
sid	String	你的用户id，在创建用户时产生。可以在账号信息中查看。	Y
dh-code	String	数字人编号，在每个数字人创建时产生，可以在数字人概览查看。	Y
dh-question	String	你需要问数字的问题内容	Y
dh-conversation-id	String	会话id，标识该会话的唯一标识	Y
dh-context	String	关于该会话期间产生的上下文信息，该信息为已经字符串化的JSON格式数据。	N

样例:

{
    "sid": "100003",
    "dh-code": "187265485019156480",
    "dh-question": "who are you?",
    "dh-conversation-id": "0513e935-041f-48e0-9330-652ef4194511",
    "dh-context": "{}"
}

响应规范: 当你收到问题请求的时候，你需要按照下面的格式返回。

有效响应类型:

Code	Status	Response
200	OK	按照下面规范的返回体
400	Bad Request	Request body/headers are invalid
401	Unauthorized	鉴权信息无效
403	Forbidden	鉴权失败
500	Server Error	服务异常

返回体规范:

Field	Type	Description	Required
conversationId	String	会话id，标识该会话的唯一标识，与请求参数体的dh-conversation-id一致。	Y
question	String	用户所问的问题。	N
answer	String	用户问数字人的问题的答案，这是一个字符串化的 JSON 对象。	Y
intent	String	问题匹配到平台的意图	N
errorMsg	String	异常或者对错误的描述	N
extra	String	额外信息，JSON字符串	N

样例:

{
    "conversationId": "0513e935-041f-48e0-9330-652ef4194511",
    "question": "who are you?",
    "answer": {
        "answer": "Welcome to UneeQ, how can I help?",
        "operations": {
            "tipPhrases": {
                "phrases": ["yes", "no"]
            },
            "canShowText": 1
        }
    },
    "intent": "introduce",
    "errorMsg": "",
    "extra": "{}"
}

预期响应时间: 与数字人类的互动，由于他们的实时性，对延迟很敏感。因此，在处理来自DUIX平台的请求时，响应时间是需要考虑的一个重要因素。这些服务的响应时间需要95%以上在200毫秒以内。如果响应时间超过1000ms，该请求将报出超时错误，但是数字人将继续响应。

会话配置: 在创建数字人之后，可以对数字人进行会话配置。选择其他会话集成需要提供请求URL。

Field	Description	Example
Remote	Url	您为会话平台定义的安全URL，这个URL必须由https://作为前缀。DUIX平台将向这个URL发送请求 https://duix-example.com/conversation /

3.7 TTS调用

第一步：获取鉴权

例如：

curl --location --request POST 'http://172.16.17.21:8000/duix-openapi/v1/AccessToken' \
--header 'content-type: application/json' \
--data-raw '{"appId":"87076673-4188-45f0-9b0f-db841b22b0e1","appSecret":"9a6ea4871f49442d"}'

第二步：查询tts克隆模型列表

例如：

curl --location --request GET 'http://172.16.17.21:8000/duix-openapi/v1/queryTtsModelList?lang=zh&language=zh&oneLevelType=&twoLevelType=&ttsName=&pageSize=999&pageNum=1&userId=142865&corpId=1000043' \
--header 'Content-Type: application/json' \
--header 'token: 16A69FBA33D7B7EE563114476C0F979853FE3FF5B618DDCEAA764E3EE7BF46A271339C8C4F4A747A0609DDFB5BDDF555E24EA3FE95AFEDBA1C3A8818EC53123B' \

接口返回:

{
    "success": true,
    "code": "0",
    "message": "Success",
    "data": {
        "records": [
            {
                "id": 345,
                "ttsName": "练达野哥-通用",
                "ttsSpeaker": "160",
                "ttsCover": "/tts-market/liandayege.jpg",
                "labelList": [
                    ""
                ],
                "backup1": "cn",
                "ttsSource": 10,
                "ttsEndpoint": 367,
                "ttsPlatForm": { //平台参数规范
                    "platformId": 10,
                    "platformName": "多纷",
                    "speedMin": -20,
                    "speedMax": 20,
                    "volumeMin": -20,
                    "volumeMax": 20,
                    "intonationMin": -20,
                    "intonationMax": 20,
                    "extendJson": "{\n\"speed\": 1.15,\n    \"volume\": 0.5,\n    \"intonation\": 0\n}"  //默认值
                },
                "ttsExtendJson": "{\"speed\": \"2\", \"volume\": \"0\", \"intonation\": \"1\", \"popularity\": 199, \"features\": \"16000,24000,48000\"}"
            }
        ],
        "total": 0,
        "size": 0,
        "current": 0,
        "orders": [],
        "optimizeCountSql": true,
        "hitCount": false,
        "countId": null,
        "maxLimit": null,
        "searchCount": true,
        "pages": 0
    }
}

第三步：设置编辑会话设置tts克隆模型参数

例如：

curl --location --request POST 'http://172.16.17.21:8000/duix-openapi/v1/conversation/modify' \
--header 'token: 16A69FBA33D7B7EE563114476C0F979853FE3FF5B618DDCEAA764E3EE7BF46A21F1D5B3D62894B7031947A33483636B7F840211EE7F15A5EB4169E8E82ECEE0F' \
--header 'Content-Type: application/json' \
--data-raw '{"conversationId":"1575009741866930176","ttsConfig":"{\"id\":30,\"volume\":50,\"pitch\":0,\"speechRate\":0,\"speaker\":\"zhiru\",\"ttsEndpoint\":359,\"ttsSource\":5}"}'

conversationId：会话的appId ttsConfig中的参数说明： volume：音量 -20~20 参考所选模型的ttsPlatForm字段json内容 pitch：音调 -20~20 speechRate：语速 -20~20 参考所选模型的ttsPlatForm字段json内容 id：从选中的模型中取字段id的值即可 speaker：从选中的模型中取字段ttsSpeaker的值即可 ttsSource：从选中的模型中取值即可 注意：此接口需在会话开始前调用，设置参数才能生效，如果会话正在进行需要重新开启会话才能生效

第四步：合成克隆音频文件

curl --location --request POST 'http://172.16.17.21:8000/duix-openapi/v1/ttsSynthesis?lang=zh' \
--header 'content-type: application/json' \
--header 'token: 16A69FBA33D7B7EE563114476C0F979853FE3FF5B618DDCEAA764E3EE7BF46A26AE3E809808461C1B90CD4CF0AEC4B56C9EA5EFCE5A472799AA5733C2AF7596A' \
--data-raw '{"userId":142865,"corpId":1041984,"speaker":"203","endpoint":367,"ttsResource":10,"text":"嗨，各位亲爱的粉丝朋友们，我是你们可爱的宝宝，，为了让大家开心一下，我特意给自己化了妆，穿<phoneme alphabet=\"py\" ph=\"le5\">了</phoneme>美美哒的白裙子，如果你想<phoneme alphabet=\"py\" ph=\"kan4\">看</phoneme>更美的，记<phoneme alphabet=\"py\" ph=\"de5\">得</phoneme>常来<phoneme alphabet=\"py\" ph=\"kan4\">看</phoneme>哦！"}'

四、 相关协议

4.1 人工智能生成合成内容标识规范

（1）我们将依据相关法律法规，对人工智能生成合成内容添加相应标识（如在生成合成内容或者交互场景界面中添加的显式标识，采用技术措施在生成合成内容的文件元数据中添加的隐式标识）。您应确保您已仔细阅读并理解《人工智能生成合成内容标识办法》及其他相关的标识管理要求。您不得使用或尝试使用任何技术手段或其他方法删除、篡改、伪造、隐匿该等生成合成内容标识，不得为他人实施删除、篡改、伪造、隐匿该等生成合成内容标识行为提供工具或者服务，不得通过不正当标识手段损害他人合法权益。
（2）在特定场景下，为更好地满足您的使用需求，我们可能根据您的申请为您提供没有添加显式标识的人工智能生成合成内容。如您申请我们提供没有添加显式标识的生成合成内容的，您需承诺并保证：
①不利用该内容发布、传播任何虚假信息或从事其他任何违法违规活动；
②在发布或传播基于深度学习、虚拟现实、深度合成、生成式人工智能等新技术制作的非真实信息，或其他可能引发公众误解或混淆的信息内容时，应当以显著方式标识；
③在向第三方分享该内容或使用网络信息内容传播服务发布该内容或以其他方式使用该内容时，主动声明其为人工智能生成合成内容；
④遵守其他相关法律、法规、政策、办法的规定。
（3）如您违反上述约定，您应自行承担由此引起的所有责任，并赔偿由此给我们及第三方造成的全部损失（包括但不限于直接损失、间接损失、诉讼费、仲裁费、公证费、鉴定费、律师费、差旅费、保全费用、保全保险费、向任何第三方承担的责任、行政处罚、罚款等）。