开发者文档中心

OpenAPI进入控制台

业务服务接入 · 2026-10-31

录音导入与语音质检

从网页或服务端上传原始录音,跟踪文件识别、确认说话人并执行可核验的质检。

接入流程

  1. 上传原音

    创建任务并分块上传,保留私有原音。

  2. 异步转写

    校验真实时长后提交百炼文件识别;持久化供应商任务号。

  3. 确认角色

    声道和说话人编号先作为未知身份,人工映射客户、坐席或AI。

  4. 分析与复核

    选择已发布分析方案,查看逐字证据、字段、风险、评分及人工复核。

准备条件

  1. 平台为企业开通洞察;网页操作者须为具备服务与报表权限的企业管理员。API还需开放平台权限,并给密钥明确授权对应insights.audio操作。
  2. 管理员在「语音引擎 → 洞察 ASR」独立配置百炼北京密钥、文件识别模型和企业授权,不必配置或修改语音智能体。也可在录音上传时明确选择复用已授权的语音 ASR。仅一个独立资源时优先使用;多个独立资源须明确选择。旧 cn 语音资源按北京处理。
  3. 文件识别使用语音分钟额度,提交前预留、识别成功后按已验证文件时长向上取整分钟结算;文本模型分析另走已有模型计费。
  4. 在洞察设置中选择当前企业可用的分析模型;本地规则检查也可运行,但不能视为模型语义质检。

文件与容量

支持WAV、MP3、M4A、AAC、FLAC、OGG和WebM,单文件100MB、单/双声道、最长2小时;逐次上传1MiB分块。非标准PCM WAV需要服务端ffprobe解码校验(macOS本地预览可使用系统afinfo);工具缺失或解码失败时明确拒绝,不假装识别成功。

每个企业最多300个尚未清理原音的录音任务、声明原音总量2GiB;列表只加载最近100个任务,原音不写入会话JSON或公开目录。原音清理后释放相应上传容量,任务、转写、质检和复核记录独立保留。

单会话语义质检最多1000段、6万字。大文件识别超过此范围保留失败状态,不能截断后伪装完整质检。

原始音频保留时间

  1. 进入洞察 → 配置管理 → 工作区设置,由企业管理员设置原始音频保留期。默认365天,支持1–3650天,例如5天。API上传也遵循上传时的企业策略。
  2. 默认只影响之后上传的录音;每个任务保存当时的保留期和到期时间,后续改设置不会自动修改已有录音。期限以任务创建(开始上传)时间计算,不以录音发生时间计算。
  3. 需要调整已有录音时,单独勾选历史范围,先查看影响数量、将立即到期的数量与容量,再明确确认。配置或任务变化会拒绝旧预览,重新核对后再保存。已到期或已清理原音不能通过延长期限恢复。
  4. 到期立即停止回听、上传续传和新识别/重试,原音访问返回410。已有供应商识别任务可查回已经产生的转写,不重新提交。后台维护按索引分批清理平台保存的原始音频,不把大量清理放进页面请求。
  5. 保留转写、纪要、质检、复核及费用核对记录;原音到期后显示明确状态。此设置不承诺删除供应商侧副本,也不等于删除原始业务渠道自身保留的录音。

API操作与状态

操作方法及路径用途
创建任务POST /v1/operations/insights.audio.createrequestId、filename、bytes、source、startedAt、channels、asrResourceId、asrModel
上传分块POST /v1/operations/insights.audio.chunkjobId、从0开始的index、纯Base64 data;同序号同内容可重放
完成上传POST /v1/operations/insights.audio.completejobId;校验完整分块、格式和时长,随后异步处理
查询任务GET /v1/operations/insights.audio.read?jobId=任务ID查询任务、conversation的转写/质检结果/复核及说话人片段;不传jobId返回最近任务
推进/接续POST /v1/operations/insights.audio.advancejobId;服务重启或浏览器关闭后可接续已有供应商任务
确认角色POST /v1/operations/insights.audio.rolesjobId、当前会话revision、roles对象;使用返回的speaker键
执行质检POST /v1/operations/insights.audio.analyzejobId、会话revision、requestId、engine=model或local、planMode=bound或latest
人工复核POST /v1/operations/insights.audio.reviewjobId、revision、score(0–100)、reason(1–3000字依据);不覆盖模型原结论
明确重试POST /v1/operations/insights.audio.retryjobId、confirmProviderRetry=true;可补asrResourceId/asrModel,先核对供应商任务和费用

状态与恢复

uploading表示原音未传完;queued表示已保存待识别;submitting表示可能已调用供应商;recognizing表示已保存供应商任务号;transcribed表示已转写待角色与质检;completed表示当前会话已有未过期分析。

failed不代表业务质检不合格,通常是配置/识别未完成。uncertain表示提交结果未知,必须先核对供应商控制台和费用,再明确重试;禁止自动重复提交。明确未提交/供应商明确失败释放预留,未知结果保留待核对;再次提交使用新的预留凭证,原未知预留会在任务中显示,不自动冒充退款。分析失败仍保留原音及转写,可以在同一会话重新分析或恢复已有模型回执。

当前音频只作为证据回放与ASR输入。语义模型只接收转写,不把文字推断成音量、噪声、静音或抢话的声学测量;这些信息需结合原音人工核查。

可下载的上传示例

本节下方及下载中心提供标准库Python导入示例(insights-audio-import.py)下载。密钥从环境变量读取,不写入源码。

所有写请求需要8–100位Idempotency-Key。每个分块保持稳定key;advance每次使用新key,否则网关会重放旧状态。相同requestId不能对应不同文件元数据。

运行前

run-import.sh · 命令文件

  • 先下载 insights-audio-import.py,与本脚本放在同一目录。
  • 设置脚本列出的环境变量;时间、声道和文件必须对应自己的已授权录音。
完整代码 · 10 行
run-import.shShell
#!/bin/sh
# Copy beside insights-audio-import.py; set all values for your own authorized recording.
set -eu
: "${YUNFU_BASE_URL:?Set the service HTTPS origin}" "${YUNFU_API_KEY:?Set the server API key}"
: "${YUNFU_RECORDING_STARTED_AT:?Set the actual recording timestamp with timezone}"
: "${YUNFU_AUDIO_PATH:?Set the recording file}" "${YUNFU_ASR_RESOURCE_ID:?Set the authorized ASR resource}"
: "${YUNFU_CHANNELS:?Set the actual channel count}" "${YUNFU_REQUEST_ID:?Retain one stable ID for this import}"
python3 ./insights-audio-import.py "$YUNFU_AUDIO_PATH" --origin "$YUNFU_BASE_URL" \
  --resource "$YUNFU_ASR_RESOURCE_ID" --channels "$YUNFU_CHANNELS" \
  --request-id "$YUNFU_REQUEST_ID" --wait 600
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    先下载 insights-audio-import.py,与本脚本放在同一目录。 设置脚本列出的环境变量;时间、声道和文件必须对应自己的已授权录音。

  2. 在项目中使用

    run-import.sh · 命令文件

  3. 核对结果

    执行会上传录音并等待状态;未知结果沿用原 requestId 核对,不重新创建导入。

预期结果:执行会上传录音并等待状态;未知结果沿用原 requestId 核对,不重新创建导入。

验收与错误处理

  1. 上传一个自有、已获授权的短录音;核对bytes、声道及真实时长,确认跨企业jobId返回404。
  2. 等待transcribed后,按原音确认说话人角色;unknown不会自动变为客户或坐席,未确认不能执行质检。
  3. 核对质检采用的方案/模型、原话证据、字段缺失和规则unknown;模型成功不代表服务已解决。
  4. 人工复核保留说明及历史,再按原有整改任务跟进。400/413为输入问题,402为额度,403为开通/权限,409为版本冲突,422为配置/解码,429为并发限制。
实现依据 · 仓库内路径
  • backend/services/insights/insights-audio-service.ts
  • backend/services/insights/insights-audio-provider.ts
  • backend/services/insights/insights-audio-retention.ts
  • database/stores/insights-audio-retention-store.ts
  • app/api/insights-audio/route.ts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。