ASR（语音转写）

本文用于统一说明 ASR（语音转写）能力的接入方式，适用于任意后端语言（Go / Node.js / Python / Java 等）和前端框架。

服务入口

• ASR 服务 API 文档：
• ASR 服务地址：
• 转写接口：

ASR 服务地址约定

• ASR 微服子域名：asr-ai
• 标准访问地址：https://asr-ai.${LAZYCAT_BOX_DOMAIN}
• 完整转写接口：https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions

转写接口说明

POST /v1/audio/transcriptions

将音频文件转写为文本（兼容 OpenAI Audio API）。

请求格式

• Content-Type: multipart/form-data
• 必填字段：
  • file：音频文件

支持音频格式

mp3, mp4, mpeg, mpga, m4a, wav, webm, flac, ogg, amr, pcm

文件大小限制

• 默认最大：300MB（可通过 MAX_AUDIO_SIZE 配置）
• OpenAI 原生参考限制：25MB

常用请求参数

参数	类型	必填	说明
file	file	是	待转写音频
model	string	否	模型名，未传时走服务默认模型
response_format	string	否	输出格式：json / text / verbose_json / srt / vtt
enable_punctuation	bool/string	否	是否启用标点，建议 true
progress	bool/string	否	是否返回进度事件流
progress_format	string	否	进度格式，建议 ndjson

暂不生效但保留：prompt、temperature、timestamp_granularities

输出格式说明

格式	Content-Type	说明
json	application/json	简单 JSON（通常包含 text 字段）
text	text/plain	纯文本
verbose_json	application/json	详细 JSON（含分段 / 时间戳）
srt	text/plain	SRT 字幕
vtt	text/vtt	WebVTT 字幕

模型映射（服务侧）

• whisper-1 -> 默认模型（sensevoice-small）
• sensevoice-small -> 速度快，多语言混合，准确度中等
• paraformer-large -> 中文高精度，速度中等
• fun-asr-nano -> 方言 / 唱歌 / 噪声场景优化，速度慢

响应示例

200 成功（json）

{
  "text": "今天天气不错，明天可能会下雨。"
}

400 请求错误

{
  "detail": "File too large. Maximum size is 300MB"
}

401 认证失败

{
  "detail": "Invalid API key"
}

推荐调用流程（通用）

1. 准备音频文件（必要时先从视频抽音频）
2. 以 multipart/form-data 上传到 /v1/audio/transcriptions
3. 选择 response_format
   • 文本摘要：json 或 text
   • 字幕生成：srt / vtt
   • 程序处理：verbose_json
4. 若需前端进度，开启：
   • progress=true
   • progress_format=ndjson
5. 处理错误码（400 / 401 / 422）并在 UI 展示可读错误

后端环境变量（lzc-manifest.yml）

可在后端 / 转换服务中配置：

services:
  convert:
    environment:
      - ASR_URL=https://asr-ai.${LAZYCAT_BOX_DOMAIN}
      # 可选：业务文件根目录
      - HOMEDIR=/lzcapp/run/mnt/home

• ASR_URL：ASR 服务基地址（不带 /v1/audio/transcriptions 也可，业务代码拼接）
• HOMEDIR：本地文件读写根路径（可选）

前端匹配 asr-ai 域名（通用实现）

const url = computed(() => {
  const currentHost = window.location.host;
  const protocol = window.location.protocol;

  // 目标微服子域
  const serviceSubdomain = "asr-ai";
  // 当前盒子名（例如 mybox），由业务注入
  const boxName = props.boxName;
  const path = props.path || "/v1/audio/transcriptions";

  let host = "";

  if (currentHost.endsWith(".heiyu.space")) {
    // 例如 ai.mybox.heiyu.space -> asr-ai.mybox.heiyu.space
    host = currentHost.replace(/^([^.]+)/, serviceSubdomain);
  } else {
    // 非 heiyu.space 的兜底拼接
    host = `${serviceSubdomain}.${boxName}.heiyu.space`;
  }

  return `${protocol}//${host}${path}`;
});

最小可用调用示例（依赖微服）

curl -X POST "https://asr-ai.${LAZYCAT_BOX_DOMAIN}/v1/audio/transcriptions" \
  -F "file=@/path/to/demo.wav" \
  -F "response_format=json" \
  -F "enable_punctuation=true" \
  -F "progress=true" \
  -F "progress_format=ndjson"

单独部署使用

1. 将下面内容保存到一个 docker-compose.yml 文件中

services:
  asr:
    image: registry.lazycat.cloud/x/lzc-funasr-slim:79d4f3a
    ports:
      - 3000:3000
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/v1/models"]
      interval: 10s
      timeout: 300s
      retries: 100
      start_period: 30s

2. 在当前目录运行 docker-compose up -d 启动
3. 启动后访问 http://127.0.0.1:3000/docs

相关服务

• 若需要转写后自动补全标点，可配合 PUNC 服务 使用。