---
name: asr-transcribe
description: 语音转文字。把本地文件或公网 URL 的音频识别成文本（中文/英文/粤语/日语/韩语等），通过 ASR Gateway。当用户要求转写、识别、听写音频或录音时使用。
---

# ASR 语音识别

通过 ASR Gateway 把音频转成文字。

> **适用范围**：本技能是纯 curl 直传，**仅适合音频文件**（mp3/m4a/wav 等），**不做视频音频提取、也不走对象存储**。
> 因此**不要拿它处理视频**（会上传整个视频，腾讯不识别视频容器且直传文件有 30MB 上限）。
> **视频 / 大文件请改用 fastasr MCP**（`transcribe_long` 会自动用 ffmpeg 提取音频 + 直传对象存储），见 https://asr.szchuyue.cn/docs#mcp

## 前置条件

- 环境变量 `ASR_API_KEY`：用户在控制台创建的 `sk-xxx`。若未设置，请向用户索取后再继续。
- 环境变量 `ASR_BASE`：网关地址，默认 `https://asr.szchuyue.cn/api`（本地自建时改成你的地址）。

## 用法

### 短音频（<60 秒、<5MB）—— 本地文件

```bash
curl -s -X POST "${ASR_BASE:-https://asr.szchuyue.cn/api}/v1/audio/transcriptions" \
  -H "Authorization: Bearer $ASR_API_KEY" \
  -F "file=@/path/to/audio.mp3" \
  -F "engine=16k_zh"
```

返回 JSON 中的 `text` 字段即识别结果。

### 短音频 —— 公网 URL（无本地文件时）

```bash
curl -s -X POST "${ASR_BASE:-https://asr.szchuyue.cn/api}/v1/audio/transcriptions" \
  -H "Authorization: Bearer $ASR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/audio.mp3","engine":"16k_zh"}'
```

### 长音频（<100MB）—— 极速版

把路径换成 `/v1/audio/transcriptions/flash`，同样用 `-F "file=@..."` 上传，同步返回。

### 更长音频 —— 异步

1. `POST /v1/audio/transcriptions/async` 提交，拿到 `taskId`。
2. 轮询 `GET /v1/audio/transcriptions/async/<taskId>` 直到完成。

## 引擎对照

| 语言 | engine |
|---|---|
| 中文（默认） | `16k_zh` |
| 英文 | `16k_en` |
| 粤语 | `16k_yue` |
| 日语 | `16k_ja` |
| 韩语 | `16k_ko` |

## 错误处理

- `401` —— API Key 无效或未设置 `ASR_API_KEY`，向用户索取正确的 `sk-xxx`。
- `402` —— 额度/余额不足，提示用户去控制台充值。
- `413` —— 文件过大，一句话识别需 <5MB / <60s，改用 `/flash` 或 `/async`。