# 洞察录音上传示例与模板

本目录全部为公开静态示例，不含客户录音、业务数据或密钥。`sample-01.wav`、`sample-02.wav` 是 16 kHz、16-bit、单声道、各 1 秒的合成测试音；`sample-recordings.zip` 平铺包含这两条 WAV。它们可验证文件选择、上传与 ZIP 解包，不能用于评估对话转写、角色识别或质检质量。上传并推进识别可能消耗语音分钟额度。

## 网页批量 / ZIP 上传

1. 下载 `sample-recordings.zip`，在“上传录音 → 批量 / 压缩包”中选择该文件，点击“批量上传”。
2. 也可分别下载两个 WAV，在同一选择框同时选中它们。
3. ZIP 只能放支持格式的录音，不能放文件夹、说明文档、重复文件名或嵌套 ZIP；最多 100 条。压缩包不超过 100 MiB，单条解压不超过 100 MiB，解压总量不超过 512 MiB。
4. “上传已保存”只证明文件接收。ZIP 父任务 `completed` 只证明解包；查看子任务的转写状态，再进入会话确认角色。

自己的 ZIP 可以按以下结构准备：

```text
my-recordings.zip
  call-001.wav
  call-002.mp3
```

在只包含目标录音的目录中执行 `zip -j my-recordings.zip call-001.wav call-002.mp3` 可生成平铺 ZIP。声道按原录音选择；ZIP 子项会按实际解码声道创建。双声道角色映射仅作标注，不会分离混合音源。

## API：先读取可用资源

先在控制台开通洞察并配置授权 ASR，创建绑定企业管理员的 API Key，逐项授权需要的 `insights.audio.*` 操作。管理员还需要 reports、service、applications 权限。API Key 只保存在服务端环境变量中。

```sh
export YUNFU_BASE_URL='https://your-deployment.example'
export YUNFU_API_KEY='填写自己创建的API Key'
export YUNFU_RECORDING_STARTED_AT='2026-10-18T09:00:00+08:00'
curl "$YUNFU_BASE_URL/v1/operations/insights.audio.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"
```

`YUNFU_BASE_URL` 为站点根地址，不含 `/api`；本机 `http://127.0.0.1:4200` 可用于本地测试。示例不会自带或生成密钥。多个 ASR 资源时，在脚本中明确加 `--resource '真实资源ID'`；省略 `--model` 时保留资源默认模型。

## API：可运行的 Python 单条 / ZIP 示例

下载同目录上一级的 `insights-audio-import.py` 与本目录测试文件到工作目录。脚本只使用 Python 标准库，按每块恰好 1 MiB 原始字节上传，末块可不足；每个操作/分块使用各自稳定的幂等键。默认只上传；增加 `--wait 60` 才会有界推进识别。

```sh
python3 insights-audio-import.py sample-01.wav \
  --origin "$YUNFU_BASE_URL" --source '示例测试音频' \
  --request-id 'sample-audio-create-01'

python3 insights-audio-import.py sample-recordings.zip \
  --origin "$YUNFU_BASE_URL" --source '示例测试音频' \
  --request-id 'sample-audio-zip-direct-01'
```

相同 request-id 重跑必须使用完全相同的文件、开始时间、来源、声道和资源/模型选择；新录音使用新 request-id。脚本不自动确认角色、质检或重新提交 `uncertain` / `failed` 任务。ZIP 完成后通过返回的 `archiveChildren` 逐条 `read` 查询子任务；父任务完成不等于转写完成。

## API：JSON 请求模板

- `create-template.json`：单条 `POST /v1/operations/insights.audio.create`。
- `batch-template.json`：清单 `POST /v1/operations/insights.audio.batch`，返回 `jobs`；清单只创建任务，还须分别上传每条录音的字节。
- `zip-template.json`：ZIP `POST /v1/operations/insights.audio.batch`，返回 `archiveJob`；须把真实 ZIP 的字节上传到父任务，再 `complete`。

模板中的文件名、字节数与本目录样例一致。替换自己的文件时，必须更新字节数、来源、带时区开始时间、声道及稳定请求编号；不能把示例字节数用于真实录音。`source`、`startedAt`、`channels` 是创建必填；清单可以从顶层继承，单项也可覆盖。企业和 accountId 由密钥归属决定，不能在正文中指定。

```sh
curl -X POST "$YUNFU_BASE_URL/v1/operations/insights.audio.batch" \
  -H "Authorization: Bearer $YUNFU_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: sample-manifest-create-01' \
  --data-binary @batch-template.json
```

保存返回的每条 `jobs[].id` 后，可用脚本接续对应任务（替换下面的真实 job id）。ZIP 模板同理，使用返回的 `archiveJob.id` 接续 `sample-recordings.zip`。

```sh
python3 insights-audio-import.py sample-01.wav \
  --origin "$YUNFU_BASE_URL" --job-id '返回的sample-01任务ID' \
  --request-id 'sample-batch-item-01'
```

接续已创建任务不会再调用 create；脚本先读取任务并核对文件名与字节数，再重传相同分块。文件内容必须保持原样。重传同一次写入须保持幂等键和正文；每次 `advance` 使用新的幂等键。

## 状态与恢复

`uploading → queued → submitting / recognizing → transcribed`；未知的 `uncertain` 先核对供应商任务与费用，禁止自动重提。`read?jobId=...` 查询任务，`advance` 只推进一步，HTTP 200 不代表业务已完成。角色确认后，读取最新 `conversation.revision` 才能提交 analyze / review。版本冲突先读回数据；API 没有文本导入、方案配置写入或分析恢复的公开操作。

原音默认保留 365 天，企业可以在控制台修改保留期。到期原音不能重新上传、回放或重新识别，转写、分析和复核记录保留。完整字段、错误码与计费说明见 `/developers/insights` 及其 JSON / OpenAPI / Markdown 下载。
