INSIGHTS API

洞察 API 文档

导入已有授权明文会话,或接续录音上传、转写、角色确认、质检与人工复核。

先完成一次只读调用

企业先开通洞察。企业管理员创建仅包含所需 insights.audio 或 insights.conversations 操作的密钥,同时保留 reports、service、applications 权限。API Key 只放在服务端,站点地址必须与密钥绑定的站点一致。

设置 YUNFU_BASE_URL 与 YUNFU_API_KEY 后,可只读核对录音 ASR 资源、大小限制和保留策略。标准明文会话导入无需 ASR 或模型;录音没有可用资源时不能当作已经完成转写。

读取配置与最近任务cURL
curl "$YUNFU_BASE_URL/v1/operations/insights.audio.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"

按这条链路接入

明文会话可直接导入;录音从创建任务开始,按状态逐步推进。

已有明文会话

insights.conversations.import → read:每批 1–50 条、每条 1–1000 条消息,正文最多 150000 字节,整批原子写入。稳定 externalId 去重;修改前 read 取最新 revision。导入不调用 ASR/模型或启动分析。

录音接入

  1. 创建导入

    create / batch:单条录音或批量清单/ZIP。保存返回的 job.id,稳定保留 requestId。

  2. 分块上传

    chunk → complete:按原始字节每块恰好 1 MiB(仅末块可不足),编码为纯 Base64 上传,再提交完成。单文件最多 100 MiB、2 小时;ZIP 解压最多 100 条、总量 512 MiB。

  3. 接续转写

    read / advance:先查询,再按任务状态推进。ZIP 完成后按 archiveChildren 跟进子任务;没有完成回调,集成方需有界轮询。

  4. 核对角色

    roles:使用 segments 返回的 speaker 键标注客户/坐席/AI。双声道可设置 left/right 角色;它依据返回声道标注,不是单声道音源分离。

  5. 分析并复核

    analyze → read → review:使用最新 conversation.revision。所有角色确认且包含客户后才能分析;read 取回原话证据和结果,人工复核保留历史依据。

接口参考

公开契约目录
正在读取接口目录…

状态、费用与失败恢复

uploading → queued → recognizing
任务已保存或等待识别,不代表完成。submitting 是供应商提交中;轮询 advance 每次使用新幂等键,网络重试同一次请求时沿用原键。
transcribed / completed
transcribed 表示已有转写;completed 表示已有当前分析运行,不等于人工复核通过或业务问题已解决。
uncertain / failed / 409
提交未知时先查原任务和费用,禁止自动换 requestId 重传。retry 需明确 confirmProviderRetry=true;版本冲突先 read,按最新 revision 重建待提交请求。
401 / 403 / 402 / 429 / 410
分别检查密钥、权限与洞察授权、余额/额度、Retry-After 和原音到期状态。过期原音不可恢复;转写、分析与人工复核继续保留。

所有 POST 都要求 8–100 位 Idempotency-Key。同键同内容重试,同键不同内容返回 409。24 小时有界响应缓存不是永久结果存储;请保存 job.id,或标准导入的 externalId/conversationId/revision,以及响应 X-Request-Id。标准明文导入不产生供应商调用费用;录音识别使用语音分钟额度,文本模型分析另计。