# 云服洞察 API 接入手册

契约版本：2026.10.31。本文包含 12 个显式开放的洞察操作。

本文档可脱离通用开放平台单独使用，覆盖授权明文会话导入、录音导入、转写、说话人确认、质检和人工复核。

## 调用前准备

- 本文覆盖公开的 insights.audio 与 insights.conversations 操作；控制台专用的 /api/insights 不是公开 API 别名。
- 企业必须先开通洞察，API Key 还必须明确授权对应操作。
- 设置 YUNFU_BASE_URL，并只在服务端保存 YUNFU_API_KEY。
- 只申请实际需要的操作权限；每个 POST 使用唯一的 Idempotency-Key。

```sh
curl "$YUNFU_BASE_URL/v1/operations/insights.audio.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

## 调用前准备

- 企业须开通洞察；企业管理员须具有 reports、service、applications 权限，并为密钥逐项授权所需 insights.audio 或 insights.conversations 操作。密钥与企业/管理员绑定，不接受请求自报租户或账户。
- 标准会话导入无需ASR或模型。录音转写须先在控制台配置并授权北京百炼 ASR；独立洞察资源优先，多个候选时明确选择 asrResourceId。engine=model 还须配置文本模型与已发布分析方案。本组不开放这些配置写入。
- YUNFU_BASE_URL 是部署根地址（不含 /api），服务端保存 YUNFU_API_KEY。发送 Authorization: Bearer；POST 使用 application/json 与8–100位 Idempotency-Key。网关自动固定action，调用方可以省略。

## 标准会话：导入、去重与更新

- POST insights.conversations.import导入已获授权且调用方已持有的明文，正文为{records:[...]}；1–50条会话，每条1–1000条消息，整份JSON最多150000字节。每条必填externalId、source、startedAt和messages；时间必须带时区，role为customer/agent/ai/unknown。
- externalId须稳定且为1–100字符，source为1–80字符，title可选且提供时为1–200字符；duration及messages的seconds/endSeconds单位为秒，sentAt提供时须带时区。导入为整批原子写入，任意无效项或冲突不会部分落库。
- 新externalId返回created；规范化内容相同返回unchanged。修改既有会话前GET insights.conversations.read?externalId=原编号，使用record.revision和新Idempotency-Key提交；缺少或过期revision返回409。read仅返回元数据和最新版本，不返回消息明文。
- 保存返回results中的conversationId/revision和created/updated/unchanged数量。analysisStarted固定false；本接口不调用ASR、模型或自动分析，不产生供应商调用费用。企业微信会话专区的明文提取属于专用授权链路，本标准接口不执行该提取。

## 单文件：创建、分块、提交

- 1. GET insights.audio.read（不传jobId），核对 config.resources、config.asrModels、limits 和 retention。列表最多100条，按更新时间倒序；没有通用分页。
- 2. POST create：requestId、filename、bytes、source、startedAt、channels 必填。startedAt 必须带时区；title 可选。保存返回 job.id 及原始元数据。requestId 与网关幂等key是两层独立标识；同requestId不得更改元数据或“显式/省略模型”的意图。
- 3. 按原始字节切成1048576字节（1MiB）分块，序号从0起。除最后一块外长度必须恰好1MiB；末块长度为 min(1MiB, bytes-index*1MiB)。将每块编码为规范Base64，不带data:前缀；逐块POST chunk。received是该块序号。
- 4. 每个chunk使用独立稳定key；同块重传保持key与内容不变。全部块齐全后POST complete。服务端核对连续序号、总字节、完整性、时长与实际声道；普通音频返回queued只表示待识别。

## 清单与ZIP批量导入

- 清单模式：POST batch，传batchId与1–100项manifest。子项支持create字段，覆盖顶层默认值；子项requestId省略时使用batchId-序号（从1起，整体仍须≤100字符）。返回jobs后，对每条任务分别chunk/complete；传archive元数据不会自动上传或解压。
- ZIP模式：省略manifest或传[]，提供archive:{filename:"calls.zip",bytes:实际ZIP字节数}及顶层source/startedAt；channels默认1，需要左右映射时设为2。返回archiveJob后上传ZIP本身的分块，再对父任务complete；支持直接create一个.zip任务。
- ZIP必须平铺，最多100条支持格式的录音；压缩包≤100MiB，单条解压≤100MiB，解压合计≤512MiB；拒绝目录路径、重复文件名、嵌套ZIP和非音频条目。实际内容会解码验证；archive.manifest只是来源元数据，不控制实际子项。
- 清单与ZIP子项不是整批原子事务；可能已保存部分任务后遇到错误。保持原batchId/元数据安全重放；若网关key已缓存错误须先read核对，再用新网关key重放同一业务清单。ZIP重新complete会接续已建子任务。父任务completed仅表示解包完成；逐条读取jobs或archiveChildren确认转写和分析。

## 角色、方案、分析与人工复核

- 转写后read返回job.segments及conversation。roles的键必须使用实际segments[].speaker，覆盖全部且不能猜测或多传；值为customer/agent/ai/unknown。所有角色已知且至少一位customer后才可分析。
- 双声道create/batch可传channelMapping:{left:"agent",right:"customer"}，仅channels=2合法；left对应provider声道0，right对应1。两侧可用agent/customer/unknown。它只标注provider声道，不做音轨分离，也不保证每个说话人都被识别。核对read中的roleConfirmed，必要时人工roles确认。
- 仅在角色或确认状态发生变化时，roles 才递增会话 revision、归档人工复核并将旧结果标为 stale。重复确认相同角色保留现有分析和人工评分。每次roles/analyze/review前读取最新conversation.revision；409时保留输入并重新核对。accountId为只读归属，由服务端设置为密钥绑定的管理员，不能在导入时指定。
- POST analyze：jobId/revision/requestId/engine/planMode必填，planId可选。engine=model用文本模型，local仅做字面规则；bound优先复用已绑定快照，latest使用当前发布方案。单会话最多1000段、60000字。当前同步成功返回{conversationId,status:"completed",accepted:false}，重复完成可返回duplicate:true；没有公开202排队契约。
- 分析后read查看conversation.runs、证据、analysisJob/analysisAttempts与最新revision。POST review提交0–100分与非空reason；它直接返回完整会话（含id/revision/review），不包在job中。模型原结论与历史保留；噪音、音量、抢话仍需回听原音核对。

## 轮询、断点与未知结果

- 保存job.id、batchId、原始元数据、文件与本地已确认分块索引。服务重启后read恢复任务；没有公开已上传分块列表，客户端可对uploading任务安全重传同内容分块。勿从最近100条列表中未看到任务就认定任务不存在。
- queued/recognizing可用advance有界推进，建议约5秒间隔并遵守Retry-After。每次真正推进使用新的网关key；重复旧key只重放旧响应。submitting表明提交进行中；后台会有限接续，但客户端仍应read/advance核对最终状态。
- uncertain或提交租约过期表示供应商结果未知。先核对供应商控制台与费用，禁止自动重提。明确确认后retry传confirmProviderRetry:true，可选更换授权资源/模型；failed/uncertain或未获得供应商task的queued才允许，任务处理中返回409。未知预留会保留，超过10笔须管理员核对。
- 分析超时/失败后先read核对runs中的requestId及analysisJob/analysisAttempts。本组未开放analysis status/recover操作；已有模型回执但未落库时在控制台恢复，不能虚构公开恢复路径，也不能自动换requestId再次付费。网关409未知响应可含requestId/state。
- 网关POST幂等key支持字母数字、下划线、短横线、点、冒号，共8–100位；同一次写入保持操作/查询/正文完全一致。响应最多有界缓存24小时；unknown、处理中、超限响应或过期不可重放时返回409，服务端不会再次执行。

## 用量、保留与能力边界

- ASR提交前按服务端校验时长向上取整到整分钟预留语音额度；供应商成功后结算，即使下载、转写校验或后续质检失败也不能视为免费。明确拒绝/识别失败可释放对应预留；uncertain不自动退款。模型质检另计文本模型用量，local不调用文本模型。
- read中的usage.asrSeconds是实际原音秒数，不是向上取整后的结算数；quotaReceiptId用于核对。complete/advance/retry都可能推进付费识别，analyze:model可能产生模型费；文档与示例本身不会发起调用。
- 原音默认365天，企业可在控制台设置1–3650天；read返回retention，job含retentionDays/expiresAt/purgedAt。到期即禁止重新上传、回听、识别与retry，清理调度删除原始字节；转写、分析、复核及历史继续保留。本组没有保留设置或删除操作。
- 本组提供insights.audio的10个操作与insights.conversations的2个操作。控制台/api/insights、私有回放、上传URL、任意文档导入及配置管理不是本组公开别名。无异步识别/分析完成Webhook；通用api.request.completed只表示HTTP请求完成，不代表后台任务完成。

## 错误与处理

- 400: 参数、时间、声道、角色或Base64格式不合法。
- 401: 密钥缺失、失效、轮换或调用期间撤销。
- 402: 没有可用语音分钟额度；先核对套餐余额。
- 403: 企业未开通洞察、非管理员或权限/操作授权不足。
- 404: 操作不存在，或任务不存在/不属于当前企业。
- 405: 方法与操作不一致；使用Allow响应头中的方法。
- 409: 版本、状态、幂等或容量冲突；保留输入并read核对，勿盲目换号重试。
- 410: 原音到期或已清理；转写、分析与复核仍保留。
- 413: 请求正文、文件或ZIP解压量超过上限；调整上传与分块。
- 415: POST必须使用application/json。
- 422: ASR/文本模型/方案缺失，音频或转写无法校验，或分析超限。
- 429: 密钥限流或识别并发已满；按Retry-After退避。
- 502: 供应商结果缺失或模型输出无效；先read核对状态与已计费用。
- 503: 依赖、存储完整性或服务暂不可用；保存任务编号与输入。

## 开放操作

### 读取录音导入任务

- 操作 ID：`insights.audio.read`
- 方法与路径：`GET /v1/operations/insights.audio.read`
- 权限：reports · service · applications
- 计费：不直接产生供应商调用费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobId (query) | string | 按分支 | 可选；省略返回最近100个任务及可用ASR资源。指定时返回job及已有conversation。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobs / config / limits / retention | object fields | 按分支 | 省略jobId时返回最近更新的100个任务（不含segments）、config.resources/asrModels、文件上限和当前retentionDays/revision/updatedAt；没有分页或分块进度查询。 |
| conversation.accountId | string | 按分支 | 只读归属：由服务端设置为密钥绑定的管理员账户；create/batch不接受accountId指定归属。 |
| conversation.revision | integer | 按分支 | roles/analyze/review使用的会话版本；不是工作区或任务版本。每次写后重新read。 |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl "$YUNFU_BASE_URL/v1/operations/insights.audio.read?jobId=YOUR_AUDIO_JOB_ID" -H "Authorization: Bearer $YUNFU_API_KEY"
```

### 创建录音导入

- 操作 ID：`insights.audio.create`
- 方法与路径：`POST /v1/operations/insights.audio.create`
- 权限：reports · service · applications
- 计费：不直接产生供应商调用费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| requestId | string | 是 | 8–100位字母、数字、下划线或短横线。相同编号对应相同文件元数据。 |
| filename | string | 是 | 带支持扩展名的原始文件名；不是服务端路径。 |
| bytes | number | 是 | 原始文件总字节数，1–104857600；不含Base64膨胀。 |
| source | string | 是 | 来源说明，不能用它更改企业范围。 |
| startedAt | string | 是 | 录音真实开始时间，带时区ISO字符串；重跑保持一致。 |
| channels | number | 是 | 1或2；必须与服务端解码所得声道数一致。 |
| asrResourceId | string | 否 | 已授权的独立洞察 ASR 或复用语音 ASR 资源 ID；仅一个独立资源时优先使用，多个独立资源必须明确选择。 |
| asrModel | string | 否 | fun-asr或qwen-audio-3.1-asr-flash-filetrans；省略时使用独立资源的默认模型。 |
| title | string | 否 | 可选录音标题，最多200字符；省略或空字符串时使用filename。 |
| channelMapping | object | 否 | 双声道角色标注：left/right取agent、customer或unknown；只标注provider声道，不执行音轨分离。 |
| batchId | string | 否 | 批量任务编号；同一清单可安全重放，子项按requestId分别幂等。 |
| archive | object | 否 | 可选ZIP元数据；最多100条录音、解压总量512MiB，拒绝路径穿越和非音频扩展名。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.create" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"requestId":"YOUR_STABLE_REQUEST_ID","filename":"call.wav","bytes":32044,"source":"CRM录音","startedAt":"2026-10-17T09:00:00+08:00","channels":1,"asrResourceId":"YOUR_ASR_RESOURCE_ID","asrModel":"fun-asr"}'
```

### 创建批量录音导入

- 操作 ID：`insights.audio.batch`
- 方法与路径：`POST /v1/operations/insights.audio.batch`
- 权限：reports · service · applications
- 计费：不直接产生供应商调用费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| batchId | string | 是 | 批量任务编号；同一清单可安全重放，子项按requestId分别幂等。 |
| manifest | array | 否 | 可选的1–100项音频元数据清单；省略或传空数组时返回待分块的ZIP父任务。 |
| archive | object | 否 | 可选ZIP元数据；最多100条录音、解压总量512MiB，拒绝路径穿越和非音频扩展名。 |
| source | string | 否 | 来源说明，不能用它更改企业范围。 清单模式由子项或顶层默认值提供；ZIP模式source/startedAt必填，channels省略时为1。 |
| title | string | 否 | 可选录音标题，最多200字符；省略或空字符串时使用filename。 |
| startedAt | string | 否 | 录音真实开始时间，带时区ISO字符串；重跑保持一致。 清单模式由子项或顶层默认值提供；ZIP模式source/startedAt必填，channels省略时为1。 |
| channels | number | 否 | 1或2；必须与服务端解码所得声道数一致。 清单模式由子项或顶层默认值提供；ZIP模式source/startedAt必填，channels省略时为1。 |
| channelMapping | object | 否 | 双声道角色标注：left/right取agent、customer或unknown；只标注provider声道，不执行音轨分离。 |
| asrResourceId | string | 否 | 已授权的独立洞察 ASR 或复用语音 ASR 资源 ID；仅一个独立资源时优先使用，多个独立资源必须明确选择。 |
| asrModel | string | 否 | fun-asr或qwen-audio-3.1-asr-flash-filetrans；省略时使用独立资源的默认模型。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.batch" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"batchId":"YOUR_STABLE_BATCH_ID","manifest":[{"requestId":"YOUR_ITEM_REQUEST_ID","filename":"call.wav","bytes":32044,"source":"CRM录音","startedAt":"2026-10-17T09:00:00+08:00","channels":1,"asrResourceId":"YOUR_ASR_RESOURCE_ID","asrModel":"fun-asr"}]}'
```

### 上传录音分块

- 操作 ID：`insights.audio.chunk`
- 方法与路径：`POST /v1/operations/insights.audio.chunk`
- 权限：reports · service · applications
- 计费：不直接产生供应商调用费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobId | string | 是 | 当前企业录音任务ID，不可跨企业读取。 |
| index | number | 是 | 从0开始的连续分块序号。 |
| data | string | 是 | 该块纯Base64，不带data:前缀；每块原始字节1MiB，最后一块可不足。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.chunk" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"jobId":"YOUR_AUDIO_JOB_ID","index":0,"data":"BASE64_OF_THIS_CHUNK"}'
```

### 完成录音上传

- 操作 ID：`insights.audio.complete`
- 方法与路径：`POST /v1/operations/insights.audio.complete`
- 权限：reports · service · applications
- 计费：可能产生语音分钟或模型费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobId | string | 是 | 当前企业录音任务ID，不可跨企业读取。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.complete" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"jobId":"YOUR_AUDIO_JOB_ID"}'
```

### 推进录音识别

- 操作 ID：`insights.audio.advance`
- 方法与路径：`POST /v1/operations/insights.audio.advance`
- 权限：reports · service · applications
- 计费：可能产生语音分钟或模型费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobId | string | 是 | 当前企业录音任务ID，不可跨企业读取。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.advance" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"jobId":"YOUR_AUDIO_JOB_ID"}'
```

### 确认录音说话人

- 操作 ID：`insights.audio.roles`
- 方法与路径：`POST /v1/operations/insights.audio.roles`
- 权限：reports · service · applications
- 计费：不直接产生供应商调用费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobId | string | 是 | 当前企业录音任务ID，不可跨企业读取。 |
| revision | number | 是 | 查询返回的会话修订号；过期返回409，保留输入并重新读取。 |
| roles | object | 是 | 对象：实际返回的segments[].speaker键映射为customer/agent/ai/unknown。不得猜测角色。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.roles" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"jobId":"YOUR_AUDIO_JOB_ID","revision":1,"roles":{"channel-0-speaker-0":"customer","channel-1-speaker-0":"agent"}}'
```

### 确认重试录音识别

- 操作 ID：`insights.audio.retry`
- 方法与路径：`POST /v1/operations/insights.audio.retry`
- 权限：reports · service · applications
- 计费：可能产生语音分钟或模型费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobId | string | 是 | 当前企业录音任务ID，不可跨企业读取。 |
| confirmProviderRetry | boolean | 是 | 必须为true；先核对供应商任务及费用，未知提交不会自动退款或重提。 |
| asrResourceId | string | 否 | 已授权的独立洞察 ASR 或复用语音 ASR 资源 ID；仅一个独立资源时优先使用，多个独立资源必须明确选择。 |
| asrModel | string | 否 | fun-asr或qwen-audio-3.1-asr-flash-filetrans；省略时使用独立资源的默认模型。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.retry" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"jobId":"YOUR_AUDIO_JOB_ID","confirmProviderRetry":true}'
```

### 执行录音质检

- 操作 ID：`insights.audio.analyze`
- 方法与路径：`POST /v1/operations/insights.audio.analyze`
- 权限：reports · service · applications
- 计费：可能产生语音分钟或模型费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobId | string | 是 | 当前企业录音任务ID，不可跨企业读取。 |
| revision | number | 是 | 查询返回的会话修订号；过期返回409，保留输入并重新读取。 |
| requestId | string | 是 | 本次分析独立请求编号；结果未知时先读取既有运行回执。 |
| engine | string | 是 | model使用配置模型；local仅执行本地字面规则，不代表模型语义质检。 |
| planMode | string | 是 | bound使用已绑定方案；latest使用当前发布方案。 |
| planId | string | 否 | 可选已发布方案ID；bound且会话已有execution时忽略；否则选择指定方案，省略时使用原方案或服务端可用默认方案。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.analyze" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"jobId":"YOUR_AUDIO_JOB_ID","revision":2,"requestId":"YOUR_ANALYSIS_REQUEST_ID","engine":"model","planMode":"latest"}'
```

### 人工复核录音质检

- 操作 ID：`insights.audio.review`
- 方法与路径：`POST /v1/operations/insights.audio.review`
- 权限：reports · service · applications
- 计费：不直接产生供应商调用费用

私有录音上传、异步转写、角色确认、质检及人工复核；请先阅读录音导入指南。

- 响应示例仅说明结构，不代表已成功识别或质检。API Key必须绑定企业管理员并授权对应操作。
- 单文件1–100MiB、最长7200秒、单/双声道；企业最多300个未清理任务、总声明容量2GiB；批量清单最多100项；ZIP必须平铺，解压最多100条且总量512MiB，超限、嵌套路径、重复文件名或路径穿越明确失败。
- 清单子项支持create字段，覆盖顶层默认值；requestId省略时生成batchId-序号。清单创建可能部分成功，失败后保持原清单重放，不是全有或全无事务。
- ZIP模式省略manifest或传空数组，并传archive:{filename,bytes}及source/startedAt；上传archiveJob的ZIP字节并complete，随后逐条跟踪jobs或archiveChildren。archive.manifest只是元数据，不代替真实ZIP字节。
- uncertain为提交未知；不要自动重提。识别使用语音分钟额度，文本模型质检另计。
- 所有角色确认且含客户后才能分析；语义模型基于转写，噪音、音量与抢话需回听原音核对。
- 原音回放为登录态私有接口，不提供公开音频URL。本组未新增异步完成Webhook，使用read/advance接续。
- 原音默认保留365天，可在控制台设置1–3650天；到期返回410并清理原始字节，转写、质检和复核记录仍保留。本组没有修改保留策略的公开操作。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| jobId | string | 是 | 当前企业录音任务ID，不可跨企业读取。 |
| revision | number | 是 | 查询返回的会话修订号；过期返回409，保留输入并重新读取。 |
| score | number | 是 | 人工复核分数0–100；不覆盖模型原结论。 |
| reason | string | 是 | 人工复核依据，1–3000 字。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| received / conversationId / review | action-dependent | 按分支 | chunk返回received分块序号而非累计数；analyze首次成功返回{conversationId,status:"completed",accepted:false}，重复已完成requestId返回duplicate:true且可省略accepted；review直接返回完整会话及递增revision/review。结果详情请再调用read。 |
| job | object | 按分支 | 按分支返回任务状态、真实文件元数据、原音时长（秒）、说话人片段、usage及retentionDays/expiresAt；batch返回jobs，ZIP创建返回archiveJob，ZIP complete另含jobs；chunk/analyze/review不返回job。不暴露供应商密钥或私有任务凭证。 |
| conversation | object | 按分支 | read指定jobId且转写已入库时返回会话：revision、messages、runs、review等；电话号码遵循隐私权限。 |

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.review" -H "Authorization: Bearer $YUNFU_API_KEY" -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY" -H 'Content-Type: application/json' --data '{"jobId":"YOUR_AUDIO_JOB_ID","revision":3,"score":80,"reason":"已逐段核对原始录音与质检证据，现确认人工评分。"}'
```

### 导入结构化会话

- 操作 ID：`insights.conversations.import`
- 方法与路径：`POST /v1/operations/insights.conversations.import`
- 权限：reports · service · applications
- 计费：不直接产生供应商调用费用

整批原子导入1–50条已有明文会话，以稳定externalId识别重复与更新；不自动分析。

- 仅导入调用方已合法持有并获授权处理的明文会话；企业微信会话专区的明文提取须使用其专用授权链路。本接口不提取企业微信明文。
- 企业须已开通洞察；API Key绑定企业管理员，账号同时具有reports、service、applications权限，密钥逐项授权本操作。企业及归属由服务端确定。
- 导入不调用ASR或文本模型，不自动启动分析，不产生供应商调用费用；analysisStarted始终为false。需要分析时在洞察控制台明确发起。
- 严格按字段契约提交：请求、会话和消息对象中的未知字段都会被拒绝；查询只接受externalId，不接受其他参数。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| records | array | 是 | 1–50条会话；整份JSON正文最多150000字节。任意一项无效或冲突则整批不写入。 |
| records[].externalId | string | 是 | 稳定的外部会话标识，1–100字符；同一企业内识别既有导入，不是幂等请求键。 |
| records[].source | string | 是 | 来源，1–80字符；不授予读取外部平台数据的权限。 |
| records[].title | string | 否 | 可选标题；提供时为1–200字符。 |
| records[].startedAt | string | 是 | 会话开始时间，必须为带时区ISO时间。 |
| records[].duration | number | 否 | 可选会话时长，单位为秒，必须覆盖所有消息起止偏移。 |
| records[].demo | boolean | 否 | 可选演示数据标记。 |
| records[].revision | integer | 否 | 修改既有会话时必填，使用insights.conversations.read返回的最新revision；遗漏或过期返回409。内容规范化后相同返回unchanged。 |
| records[].messages | array | 是 | 每条会话1–1000条消息，按会话顺序提交。 |
| records[].messages[].id | string | 否 | 可选外部消息标识，1–200字符。 |
| records[].messages[].role | string | 是 | customer、agent、ai或unknown；unknown保留待确认角色。 |
| records[].messages[].speaker | string | 否 | 可选说话人名称，1–200字符。 |
| records[].messages[].text | string | 是 | 已获授权的消息明文，1–10000字符，不能只有空白。 |
| records[].messages[].sentAt | string | 否 | 可选消息时间；提供时必须为带时区ISO时间。 |
| records[].messages[].seconds / endSeconds | number | 否 | 可选消息起止偏移，单位为秒；endSeconds必须大于等于seconds（缺省为0）。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| results[] | object | 是 | 每条包含externalId、conversationId、revision、status与messageCount；status为created、updated或unchanged。 |
| created / updated / unchanged | integer | 是 | 本批新建、更新、无变化的会话数量。 |
| analysisStarted | boolean | 是 | 固定false；已保存不代表已分析。 |

```sh
curl --fail-with-body "$YUNFU_BASE_URL/v1/operations/insights.conversations.import" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wecom-demo-import-001" \
  --data-binary @insights-api-import.json
```

### 读取 API 会话版本

- 操作 ID：`insights.conversations.read`
- 方法与路径：`GET /v1/operations/insights.conversations.read`
- 权限：reports · service · applications
- 计费：不直接产生供应商调用费用

按externalId查询当前企业已导入会话的元数据和最新revision，供更新或未知结果核对；不返回明文消息。

- 仅导入调用方已合法持有并获授权处理的明文会话；企业微信会话专区的明文提取须使用其专用授权链路。本接口不提取企业微信明文。
- 企业须已开通洞察；API Key绑定企业管理员，账号同时具有reports、service、applications权限，密钥逐项授权本操作。企业及归属由服务端确定。
- 导入不调用ASR或文本模型，不自动启动分析，不产生供应商调用费用；analysisStarted始终为false。需要分析时在洞察控制台明确发起。
- 严格按字段契约提交：请求、会话和消息对象中的未知字段都会被拒绝；查询只接受externalId，不接受其他参数。

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| externalId (query) | string | 是 | 必填，1–100字符，使用原导入的稳定externalId；不存在或不属于当前企业返回404。 |

### 响应字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| record | object | 是 | 包含externalId、conversationId、revision、source、title、startedAt、messageCount与resultStatus；仅返回元数据，不含messages明文。 |
| record.revision | integer | 是 | 修改导入时传回的最新会话修订号。 |
| record.resultStatus | string | 是 | stale表示尚未分析或内容变化后待重新分析；current表示已有当前结果。导入不会自动把结果置为current。 |

```sh
curl --fail-with-body --get "$YUNFU_BASE_URL/v1/operations/insights.conversations.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  --data-urlencode "externalId=wecom-demo-001"
```

## 下载与契约来源

JSON 目录和 OpenAPI 导出与本页面使用同一份服务端契约。接口返回“已受理”或“排队”不等于业务完成；请继续读取任务并核对最终状态。
