VoScript API 技能包

VoScript 是一个自托管的语音转写服务，支持多说话人分离、声纹识别、降噪、
多格式导出。本技能包封装了其 REST API 的全部主要工作流。

重要：本技能与代理无关（agent-agnostic），同等适用于 Claude、Codex、
Trae、Hermes、OpenClaw 等任何 AI 代理，不依赖任何厂商专属特性。

1. 配置说明

VoScript 通过两个参数进行访问配置：

• VOSCRIPT_URL：服务地址，例如 http://localhost:7880
• VOSCRIPT_API_KEY：调用 API 所需的鉴权密钥

推荐通过环境变量设置，所有脚本也支持 --url / --api-key 命令行参数覆盖。

当 VOSCRIPT_URL 或 VOSCRIPT_API_KEY 未配置时，代理必须：

1. 先向用户索要服务地址与 API Key；
2. 告知用户配置方式：
   • 环境变量：export VOSCRIPT_URL=... / export VOSCRIPT_API_KEY=...
   • 或使用脚本的 --url <URL> / --api-key <KEY> 参数。

详见 ${SKILL_PATH}/references/configuration.md。

2. 提交音频转写

上传音频文件并创建转写任务。

接口： POST /api/transcribe（multipart/form-data）

请求参数：

curl -X POST "$VOSCRIPT_URL/api/transcribe" \
  -H "X-API-Key: $VOSCRIPT_API_KEY" \
  -F "file=@/path/to/audio.wav" \
  -F "language=zh" \
  -F "min_speakers=1" \
  -F "max_speakers=10"

响应字段说明：

❗ deduplicated: true 不是错误，是正常响应。VoScript 对音频内容计算 SHA-256，
若已处理过相同文件，直接返回已有结果。此时 status 为 "completed"，
无需再次轮询，直接用返回的 id 获取结果。

错误响应表：

执行脚本：

python ${SKILL_PATH}/scripts/submit_audio.py \
  --file <PATH> \
  [--language zh] \
  [--min-speakers 1] \
  [--max-speakers 10]

3. 轮询任务状态

接口： GET /api/jobs/{job_id}

curl -X GET "$VOSCRIPT_URL/api/jobs/tr_xxx" \
  -H "X-API-Key: $VOSCRIPT_API_KEY"

状态机： queued → converting → denoising → transcribing → identifying → completed | failed

状态含义与典型耗时：

⚠️ 轮询建议间隔 5 秒，首次加载模型需 2-5 分钟（仅首次），
轮询超时不代表失败，可继续等待或检查 /healthz。

常见错误：

执行脚本：

python ${SKILL_PATH}/scripts/poll_job.py --job-id tr_xxx

详细状态机与阶段耗时：${SKILL_PATH}/references/job-lifecycle.md

4. 获取转写结果

接口： GET /api/transcriptions/{tr_id}

curl -X GET "$VOSCRIPT_URL/api/transcriptions/tr_xxx" \
  -H "X-API-Key: $VOSCRIPT_API_KEY"

返回内容包括：segments、speaker_map、params 等完整结果。

Segment 字段表：

❗ similarity 是 AS-norm 归一化的 z-score，不是 [0,1] 之间的概率。
值可能超过 1.0（最高观测值约 1.79）。若用 similarity > 0.5 判断是否匹配，
这是合理的经验值，但不能理解为"50% 置信度"。

常见错误：

执行脚本：

python ${SKILL_PATH}/scripts/fetch_result.py --tr-id tr_xxx

5. 导出转写

接口： GET /api/export/{tr_id}?format=srt|txt|json

curl -X GET "$VOSCRIPT_URL/api/export/tr_xxx?format=srt" \
  -H "X-API-Key: $VOSCRIPT_API_KEY" \
  -o transcript.srt

支持格式：

常见错误：

格式细节：${SKILL_PATH}/references/export-formats.md

执行脚本：

python ${SKILL_PATH}/scripts/export_transcript.py --tr-id tr_xxx --format srt

6. 转写列表

接口： GET /api/transcriptions

curl -X GET "$VOSCRIPT_URL/api/transcriptions" \
  -H "X-API-Key: $VOSCRIPT_API_KEY"

响应字段：

执行脚本：

python ${SKILL_PATH}/scripts/list_transcriptions.py

7. 注册声纹

从已有转写中抽取某个 speaker_label 对应片段作为样本，注册或更新声纹。

接口： POST /api/voiceprints/enroll

请求参数：

curl -X POST "$VOSCRIPT_URL/api/voiceprints/enroll" \
  -H "X-API-Key: $VOSCRIPT_API_KEY" \
  -F "tr_id=tr_xxx" \
  -F "speaker_label=SPEAKER_00" \
  -F "speaker_name=张三"

响应字段：

❗ 最常见错误：speaker_label 填写了显示名而非原始标签

• ✗ 错误：--speaker-label "张三"
• ✓ 正确：--speaker-label "SPEAKER_00"

speaker_label 必须是 pyannote 的原始标签（SPEAKER_00, SPEAKER_01 等），
来自转写结果的 segment.speaker_label 字段。

注册成功后，后续转写中识别出的同一说话人会自动匹配到 speaker_name。

错误响应表：

执行脚本：

python ${SKILL_PATH}/scripts/enroll_voiceprint.py \
  --tr-id tr_xxx \
  --speaker-label SPEAKER_00 \
  --speaker-name "张三"

8. 声纹列表

接口： GET /api/voiceprints

curl -X GET "$VOSCRIPT_URL/api/voiceprints" \
  -H "X-API-Key: $VOSCRIPT_API_KEY"

响应字段：

⚠️ sample_spread 偏大（例如 > 0.3）说明样本之间差异大，可能混入了错误片段，
建议通过 manage_voiceprint.py --action get 查看详情并考虑清理。

执行脚本：

python ${SKILL_PATH}/scripts/list_voiceprints.py

9. 分配说话人

手动为某个 segment 指定说话人（用于纠正分离错误或补齐未识别片段）。

接口： PUT /api/transcriptions/{tr_id}/segments/{seg_id}/speaker

请求参数：

curl -X PUT "$VOSCRIPT_URL/api/transcriptions/tr_xxx/segments/5/speaker" \
  -H "X-API-Key: $VOSCRIPT_API_KEY" \
  -F "speaker_name=李四"

💡 当你发现某个片段的说话人识别有误，或想手动覆盖自动识别结果时使用。
手动分配不影响声纹库，仅修改该片段的显示名。

常见错误：

执行脚本：

python ${SKILL_PATH}/scripts/assign_speaker.py \
  --tr-id tr_xxx \
  --seg-id 5 \
  --speaker-name "李四"

10. 管理声纹

curl -X GET "$VOSCRIPT_URL/api/voiceprints/<SPEAKER_ID>" \
  -H "X-API-Key: $VOSCRIPT_API_KEY"

常见错误：

执行脚本：

python ${SKILL_PATH}/scripts/manage_voiceprint.py \
  --action [get|rename|delete] \
  --speaker-id xxx \
  [--name "新名字"]

11. 重建声纹 cohort

AS-norm 评分依赖 cohort（对比样本集）。

接口： POST /api/voiceprints/rebuild-cohort

curl -X POST "$VOSCRIPT_URL/api/voiceprints/rebuild-cohort" \
  -H "X-API-Key: $VOSCRIPT_API_KEY"

响应字段：

💡 何时执行重建：

• 注册满 10 个说话人后首次执行
• 每新增 10-20 个说话人后更新一次
• cohort 大小 ≥ 50 时 AS-norm 评分最为稳定

重建前无需停止服务，操作为后台非阻塞任务。

执行脚本：

python ${SKILL_PATH}/scripts/rebuild_cohort.py

声纹完整工作流与阈值说明见 ${SKILL_PATH}/references/voiceprint-guide.md。

错误响应规范

VoScript 返回标准 HTTP 状态码，代理在处理响应时应按下表做分支：

诊断检查清单

遇到问题时，按以下顺序排查：

1. 服务可达性：curl $VOSCRIPT_URL/healthz 是否 200
2. 鉴权：X-API-Key 是否与容器环境变量 VOSCRIPT_API_KEY 一致，有无多余空格
3. 任务状态：先通过 /api/jobs/{id} 确认 completed，再拉结果
4. 声纹标签：注册声纹时使用 SPEAKER_XX 原始标签，不是显示名
5. similarity 语义：不是概率，是 AS-norm z-score，阈值 ~0.5 为经验值
6. 去重响应：deduplicated: true 是正常返回，不是错误
7. 首次冷启动：模型加载耗时 2-5 分钟，轮询超时不等于失败
8. 容器日志：docker logs voscript 查看详细栈回溯

典型使用序列

1. 配置 VOSCRIPT_URL / VOSCRIPT_API_KEY。
2. submit_audio.py 上传音频，拿到 tr_id。
3. poll_job.py 轮询到 completed。
4. fetch_result.py 获取 segments，审阅 speaker 分离结果。
5. 对每个 SPEAKER_xx 调用 enroll_voiceprint.py 注册真实姓名。
6. 累计 10+ 声纹后运行 rebuild_cohort.py 刷新 AS-norm 基线。
7. 后续新音频转写会自动识别已注册说话人。
8. 需要字幕文件时使用 export_transcript.py 导出 SRT/TXT/JSON。

参考文档

• ${SKILL_PATH}/references/configuration.md —— 配置与鉴权
• ${SKILL_PATH}/references/job-lifecycle.md —— 任务状态机
• ${SKILL_PATH}/references/voiceprint-guide.md —— 声纹与 AS-norm
• ${SKILL_PATH}/references/export-formats.md —— 导出格式