# 语音分析接口文档
# 1.接口说明
对上传的音频文件进行对话分析。可以直接使用系统预设的分析模板,也可以用户自定义分析模板。 当前仅支持 中英文 语音的分析。
# 使用简介
- API endpoint: spark-openapi.cn-huabei-1.xf-yun.com/api/v1/voice-insight
- 参考鉴权 (opens new window)
# 2.API接口列表
# 2.1 任务创建接口
- 请求方式: POST /api/v1/voice-insight/create
- 说明: 需要预先将文件上传到转写存储以获取音频文件 url。
# 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskType | string | 是 | 任务类型:当前只支持 audioFile(音频文件) |
| audioFileUrl | string | 是 | ost离线转写存储的url |
| modelCode | string | 是 | 大模型代码。当前仅支持 x1 和 4.0ultra 两种 |
| subTasks | list | 是 | 子任务列表,具体结构见下方 |
| subTasks[].is_customize | bool | 是 | 是否是用户自定义的子任务。 如果为否,必须传入 sub_task_template_id 如果为是,则需要设置对应的 subTasks[].customize_prompt,并基于用户侧自身需要传入 name 与 fields |
| subTasks[].sub_task_template_id | string | 否 | 如果 subTasks[].is_customize == false 则必须设置这个参数。 预设的子任务模板 id: preset_0 满意度分析模板 preset_1 服务质检分析模板 preset_2 商机意向分析模板 preset_3 关键信息抽取模板 |
| subTasks[].customize_prompt | string | 否 | 如果 subTasks[].is_customize == true 则必须设置这个参数。 其中 {ie_content} 具体的值需要在同层级的 fields 字段中定义 |
| subTasks[].name | string | 否 | 自定义的子任务名称 |
| subTasks[].fields | list | 否 | 配合 {ie_content} 使用 |
| subTasks[].fields[].name | string | 是 | 字段名称 |
| subTasks[].fields[].desc | string | 是 | 字段描述 |
| callBackUrl | string | 否 | 回调URL。如果配置会在任务执行结束后回调用户 |
| audioParams | object | 是 | 音频参数 |
| audioParams.vspp_on | int | 否 | 是否开启说话人分离,0-不开启,1-开启角色分离,2-开启角色分离(不推荐此方案,小语种不支持),3-开启声纹角色分离模式。 用户不传默认为1,即开启角色分离。 |
| audioParams.vto | int | 否 | vad强切控制,单位ms,ed默认15000,小语种默认 6000 |
| audioParams.vad_mdn | int | 否 | vad模式,1表示远场模式,2表示近场模式,默认值为 1,小语种不生效 |
| audioParams.vad_margin | int | 否 | 首尾是否带静音信息,1表示是,0表示否,默认值0,小语种不生效 |
| audioParams.dhw | string | 否 | 热词配置 |
| audioParams.pd | string | 否 | 领域个性化参数 |
| audioParams.data_encoding | string | 否 | 音频数据格式,默认是 raw 。raw标识原生音频 (pcm),speex表示speex压缩后的音频。支持的压缩格式还包括:speex-wb,opus-wb,opus-ogg,mp3(传参lame) 实现方法: 1. 安装 ffmpeg 2. 执行下面的代码 bash<br>ffmpeg -i input.mp3 \<br> -ac 1 \<br> -ar 16000 \<br> -f s16le \<br> -acodec pcm_s16le \<br> output.pcm<br> |
# 请求示例
curl -X POST 'spark-openapi.cn-huabei-1.xf-yun.com/api/v1/voice-insight/create' \
--header 'Content-Type: application/json' \
--data '{
"taskType": "audioFile",
"audioFileURL": "https://xfyun-seve-dx/IBAUEX+ollA5b/18xtFQFR+TYlU1dp7UqPcyprLi+OkonmvL+Zrt4hCY+kH40W3Y0//rbhvTwcFWPbG6xQy7OfWGSap2UZu0WLZTJUj0u9tXfuscqZ4uQE7ES2pvKsH109GBj4yinThU7NNin4FE/ShRemB1gxwsJKVLBTa0L6lLkf6hfdTZCk6Ws0dIZF1KAfiHcfYHG5YdkHA7E/tSbanjcMDRknD5VcrHwu/aX8ZAAzt57MNGYOmI76ETPyTqCbylBIo/ehsZjzss3YMyUha+en84EFy4M4G0+P4KUuwh2n4K5ekVUJuacNXshJrj0oFQLqOj0QnvJUiFEg7KKDUywWn044drTUsPk+5WSh874EQ/jwqTRfGvaGCdvt+f",
"audioParams": {},
"modelCode": "4.0ultra",
"subTasks": [
{
"is_customize": false,
"sub_task_template_id": "preset_2"
},
{
"is_customize": true,
"name": "自定义分析-用户留存意愿分析",
"customize_prompt": "${chat_content} 基于以上的用户对话,分析一下用户后续是否还会使用我们的服务,返回值请使用 json 列表格式"
},
{
"is_customize": true,
"customize_prompt": "${chat_content} 基于以上的用户对话,从内容中提取下核心信息,字段包括${ie_content} ,返回值请使用 json 列表格式",
"name": "自定义分析-自定义关键词提取",
"fields": [
{
"name": "天气信息",
"desc": "对话中提及的天气信息"
},
{
"name": "客户国籍与语言信息",
"desc": "对话中提及的用户所属国籍与语言的信息"
}
]
},
{
"is_customize": true,
"customize_prompt": "${chat_content} 基于以上的用户对话,从内容中提取下后续能够改进的工作点",
"name": "自定义分析-自定义关键词提取-一个非json的值(因为没加 json 提示)"
}
]
}'
# 响应参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | integer | 是 | 状态码,0表示成功,非0表示错误。 |
| message | string | 是 | 状态消息,code=0时值为空,code非0时为错误信息。 |
| request_id | string | 是 | 请求的唯一标识符,用于跟踪和调试请求。 |
| data | object | 是 | 包含实际响应数据的对象。 |
| data.task_id | string | 是 | 任务 id 。用户可以基于此值来查询任务当前状态。 |
| data.status | string | 是 | 任务的当前状态。 |
| data.created_at | string | 是 | 任务的创建时间。 |
# 响应示例
{
"code": 0,
"message": "",
"request_id": "a6730908-a21d-4362-8826-e56892faebc6",
"data": {
"task_id": "e7ec8307-0160-491e-8808-29cb15af7ba5",
"status": "Running",
"created_at": "2025-09-17T10:41:03Z"
}
}
# 2.2 任务查询
- 请求方式: GET /api/v1/voice-insight/tasks/{taskId}
- 说明: 查询任务处理状态和结果。
# 请求参数
| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| taskId | string | 是 | 任务 id,来源于 create 请求的返回值 |
# 请求示例
curl -X GET 'spark-openapi.cn-huabei-1.xf-yun.com/api/v1/voice-insight/tasks/your-task-id'
# 响应参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | integer | 是 | 状态码,0表示成功,非0表示错误。 |
| message | string | 是 | 状态消息,code=0时值为空,code非0时为错误信息。 |
| request_id | string | 是 | 请求的唯一标识符,用于跟踪和调试请求。 |
| data | object | 是 | 包含实际响应数据的对象。 |
| data.task_id | string | 是 | 任务 id |
| data.status | string | 是 | 任务状态。任务有三种状态: Running 运行中 Finish 运行成功 Error 运行失败 子任务中如果有一个是成功的则认定当前任务是成功的 |
| data.created_at | string | 是 | 任务创建时间 |
| data.content | string | 否 | 离线转写的文本详情 |
| data.sub_task_results | list | 否 | 子任务结果列表。只有当任务状态流转为 Finish成功 或 Error 失败后,展示子任务结果列表 |
| data.sub_task_results[].is_customize | bool | 是 | 是否是用户自定义的子任务。值是用户创建任务时的入参 |
| data.sub_task_results[].sub_task_template_id | string | 否 | 预设的子任务模板 id |
| data.sub_task_results[].name | string | 否 | 自定义的子任务名称 |
| data.sub_task_results[].status | string | 是 | 子任务状态。子任务有三种状态: Running 运行中 Finish 运行成功 Error 运行失败 |
| data.sub_task_results[].result | object|string | 否 | 子任务结果。 子任务状态流转为 Finish 运行后展示此结果。 如果子任务结果是一个合法的 Json 字符串会解析后返回,否则是一个 string |
# 响应示例
# 运行中
{
"code": 0,
"message": "",
"request_id": "5b20e00b-2c5b-4266-8d52-34f6790f2c11",
"data": {
"task_id": "e7ec8307-0160-491e-8808-29cb15af7ba5",
"status": "Running",
"created_at": "2025-09-17T18:41:03Z"
}
}
# 运行成功
{
"code": 0,
"message": "",
"request_id": "8d487d71-e5dd-4cff-b6f9-3baef4d5fca4",
"data": {
"task_id": "e7ec8307-0160-491e-8808-29cb15af7ba5",
"status": "Finish",
"created_at": "2025-09-17T18:41:03Z",
"content": "离线转写的文本详情",
"sub_task_results": [
{
"is_customize": false,
"sub_task_template_id": "preset_2",
"name": "商机意向分析模板",
"status": "Finish",
"result": [
{
"判断原因": "客户明确表示在网上关注了风云HL这款车,并询问了配置版本、分期付款方式、提车时间、颜色选择等细节,表现出较强的购买意向。",
"原始对话": [
"您是在佛山哪里的?啊嗯噢西樵、南海西樵是吧?噢嗯就看到您这边的话,在网上关注风云hl这款车是吗?",
"您是看哪个配置版本啊噢那可以,那现在的话是打算想换车,还是说想要买新买一台?呀噢那可以,啊主要是考虑一些什么方面的问题还没买车?呢可能是吧?",
"那您这边嗯是打算说分期还是说全款买车?啊可以啊分期的话,我们有个三年10万免息,您是做免息的吗?还是说做那种利息的?",
"那您这边今天有没有时间说过来,我们这边聊一下那车子。呢",
"什么时候要用车,啊有啊现车的话一个星期内就可以提车,啊嗯你要什么颜色的?"
],
"是否符合": true,
"检测维度": "客户购买意向强度"
},
{
"判断原因": "客户对风云HL车型表现出浓厚兴趣,主动了解其配置、价格及购车流程等信息。",
"原始对话": [
"就看到您这边的话,在网上关注风云hl这款车是吗?",
"您是看哪个配置版本啊",
"之前去谈到什么价格",
"因为这个车辆都是15万多。呀对啊",
"那您这边的话之前去谈到什么价格,啊嗯因为这个车辆都是15万多。呀对啊"
],
"是否符合": true,
"检测维度": "产品关注度"
},
{
"判断原因": "客户详细询问了车价、保险费用以及是否有优惠活动,并表现出对价格的关注和比较意识。",
"原始对话": [
"车价那一块的话都是152,900的,嘛那保险的话就实报实销了,保险的话以实际出单为准,大概的话可能5000来块钱,但是的话以最终实际出单的价格为准,嘛反正实际多少你支付多少就可以了。",
"全包,那那你你大概就那就152,900的车价加个保险呀大概的话就158,000左右。嘛",
"车价肯定是同步的,跟厂家同步的,全国都统一的,嘛就有现车你可以尽早提车,喽嗯就是车子啊你说没有啊对啊嗯左右对不行,车价肯定是没有优惠的。"
],
"是否符合": true,
"检测维度": "价格敏感度"
},
{
"判断原因": "客户提到有现车且一周内可提车,并被邀请到店进一步洽谈,显示出短期内可能做出购买决策的迹象。",
"原始对话": [
"现车的话一个星期内就可以提车",
"到时候有空过来这边看看,喽周六日有没有时间过来看看啊可以啊这个都可以啊可以,啊到时候过来抽空过来聊天。",
"肯定要定的,因为要在上面下定,然后配车对嗯对。",
"那我加个你微信,呗后期过来这边聊一下,喽那你要优惠几千块那肯定不可能,啊这个车价格肯定都一样的,啊是不是"
],
"是否符合": true,
"检测维度": "决策时间预期"
}
]
},
{
"is_customize": true,
"sub_task_template_id": "",
"name": "自定义分析-用户留存意愿分析",
"status": "Finish",
"result": [
{
"依据": [
"已建立直接沟通渠道(微信联系)",
"销售主动邀约到店看车并提供试驾机会",
"用户未因价格坚挺而放弃,反而被政策稳定性说服",
"提及APP下单流程说明进入转化后端环节",
"用户反复确认核心条款后仍未退出对话"
],
"关注点": [
"车型配置(风云HL)",
"价格透明度与统一性(全国无优惠)",
"金融方案(三年10万免息分期)",
"提车时间(现车一周内可提)",
"质保政策(终身质保需在4S保养)",
"购置税变动风险(明年可能增加)"
],
"建议行动": [
"通过微信定期推送该车型热销信息强化紧迫感",
"邀约参加周末到店活动体验实车",
"强调免息分期降低资金压力的优势",
"提前准备置换补贴方案应对用户旧车处理需求"
],
"犹豫因素": [
"当前无现金优惠",
"缺乏地方政府补贴(如区补/市补已取消)",
"对冷门车型未来降价的担忧"
],
"用户特征": "潜在购车客户",
"积极信号": [
"明确表达购车意向(考虑换车或新增车辆)",
"接受销售人员添加微信保持联系",
"愿意预约到店进一步洽谈细节",
"认可现车优势和早买早享受理念"
],
"预测结果": "高概率继续使用服务"
}
]
},
{
"is_customize": true,
"sub_task_template_id": "",
"name": "自定义分析-自定义关键词提取",
"status": "Finish",
"result": [
{
"desc": "未提及",
"name": "天气信息"
},
{
"desc": "未提及",
"name": "客户国籍与语言信息"
}
]
},
{
"is_customize": true,
"sub_task_template_id": "",
"name": "自定义分析-自定义键词提取-一个非json的值(因为没加json提示)",
"status": "Finish",
"result": "基于用户对话内容,以下是可以改进的工作点:\n\n---\n\n### 1. 价格透明度与沟通方式优化\n- **问题**:反复强调“无优惠”“全国统一价”,但未主动解释厂家控价原因及市场背景(如政策限制),易引发客户质疑是否隐藏折扣空间。\n- **改进方向**:提前准备书面材料或系统截图证明价格合规性;用更清晰的逻辑说明定价机制(例如:“因芯片短缺/供应链成本上涨导致厂商指导价锁定”),减少对抗感。可补充竞品对比数据强化说服力。\n\n---\n\n### 2. 金融方案灵活性不足\n- **痛点**:仅提供固定免息分期选项(三年10万),未针对不同客户需求设计阶梯式方案(如低首付长周期、气球贷等)。部分客户可能因月供压力放弃购车。\n- **建议动作**:增设个性化信贷计算器工具,支持实时模拟不同贷款年限下的还款额度;明确标注总利息支出差异,帮助客户权衡利弊。对于高净值客户可推荐附加增值服务(延长质保)。\n\n---\n\n### 3. 库存管理可视化缺失\n- **现状漏洞**:当被问及颜色偏好时,销售需临时核查库存,响应延迟影响体验。客户无法直观获取车辆动态信息。\n- **技术赋能方案**:搭建线上选配平台,实时显示各配置车型的外观渲染图、内饰细节及对应库存状态;推送短信/APP通知提醒热门颜色即将售罄,制造紧迫感。\n\n---\n\n### 4. 政策解读专业化程度低\n- **风险点**:对购置税调整的描述存在歧义(将“减半征收”误称为“正常税率的一半”),可能导致法律纠纷;关于质保条款的解释前后矛盾(先称“终身质保”,后又限定4S店保养才有效)。\n- **标准化话术模板**:制作政策速查手册,包含:①官方文件编号及生效日期;②适用条件的完整列表(如旧车置换补贴需提供机动车登记证书原件);③免责条款加粗标注。定期组织法规知识考核确保团队理解一致。\n\n---\n\n### 5. 客户需求挖掘浅层化\n- **典型失误**:询问购车动机时停留在表面回答(“换车/新车”),未深入探究使用场景(家庭代步or商务接待)、决策影响因素排序(安全性>油耗>品牌?)。导致推荐方案缺乏针对性。\n- **SPIN提问法应用**:采用情境引导式发问:“您每天接送孩子上学的话,是否关注儿童安全座椅接口数量?”“经常跑高速的话,自适应巡航功能会不会更重要?”据此匹配相应配置版本。\n\n---\n\n### 6. 跟进机制形式化严重\n- **症结所在**:过度依赖微信添加完成闭环,缺乏实质性邀约动作。客户容易淹没在海量联系人中。\n- **立体触达策略**:①设定三次黄金回访节点(首次接触后24小时内、试驾预约前日、成交后三日);②每次沟通附带价值增量信息(行业报告摘要、保养套餐优惠券);③使用CRM系统记录客户偏好自动触发事件营销推送。\n\n---\n\n### 7. 跨部门协同断层\n- **流程短板**:提到政府补贴时承认“现在没有了”,却未联动市场部策划替代活动(店头促销礼券)。错失转化机会的同时损害品牌形象。\n- **补救措施**:建立快速响应小组,每月分析区域政策变动趋势,同步推出店内补偿方案(例:自费补贴等同于已取消的地方性补助金额),保持终端竞争力连续性。\n\n---\n\n### 8. 异议处理技巧欠缺\n- **话术缺陷**:面对议价要求直接回绝“不可能”,激发对抗心理。未能有效转移焦点至产品价值维度。\n- **FAB法则运用**:将拒绝转化为教育契机:“这辆车采用航天级铝合金车身框架,相比同级别车型减重XXkg从而降低能耗--这些研发投入都体现在您的用车成本节省上了。”通过技术参数化解价格锚定效应。\n\n---\n\n### 9. 服务承诺模糊化倾向\n- **信任危机源**:笼统宣称“终身质保”,实际受诸多免责条款约束。客户预期与实际权益存在落差隐患。\n- **契约化呈现**:出具加盖公章的服务协议明细表,逐条列明保修范围、免赔情形、索赔流程及时限;附赠《车主权利白皮书》图文手册,消除认知盲区。\n\n---\n\n### 10. 数字化工具利用率低下\n- **效率瓶颈**:依赖人工核算保险费用、手动核对订单状态,既耗时又易出错。客户等待过程中产生焦虑情绪。\n- **智能系统部署**:接入DMS系统实现一键生成精准保单报价单;打通ERP与财务模块自动计算分期付款方案;开通在线签约功能缩短交易周期。"
}
]
}
}
# 任务失败
{
"code": 0,
"message": "",
"request_id": "679945dc-33a6-47fe-aad6-865d551b11ad",
"data": {
"task_id": "2d3e783e-20fc-4b94-811f-edac99828f97",
"status": "Error",
"created_at": "2025-09-17T16:21:38Z"
}
}
# 2.3 回调说明
当用户创建任务时设置了 callBackUrl,本服务会在任务成功/失败后回调该地址。
# 回调签名验证
系统支持安全的回调机制,用户可以通过签名验证确保请求来源的可信性。
# 签名计算规则
- 将 taskId=xxx×tamp=xxx&appId=xxx 进行 MD5 计算
- 将 MD5 结果进行 Base64 编码
- 对 Base64 结果进行 URL 编码
# 回调 URL 格式
https://your-callback-url.com/webhook?taskId=xxx×tamp=xxx&taskType=xxx&success=xxx&signature=xxx
# 回调参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskId | string | 是 | 任务 ID |
| timestamp | int64 | 是 | 调用时的时间戳(毫秒) |
| taskType | string | 是 | 任务类型 |
| success | boolean | 是 | 是否成功 |
| signature | string | 是 | 签名,用于验证请求来源 |
# 3.示例代码
在这篇文章中: