API 文档

每次请求都需要带上你的 API Key：

Authorization: Bearer sk-xxx

用于 60 秒以内的短音频，立即返回识别文本。

POST /v1/audio/transcriptions

# 上传文件
curl -X POST https://asr.szchuyue.cn/api/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-xxx" \
  -F file=@hello.mp3 -F engine=16k_zh

# 或传 URL
curl -X POST https://asr.szchuyue.cn/api/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://.../a.mp3","engine":"16k_zh"}'

# 响应
{ "text": "识别结果", "engine": "16k_zh", "request_id": "..." }

用于长音频。先提交任务拿到 task_id，再轮询结果。

# 1) 提交
POST /v1/audio/transcriptions/async
{ "url": "https://.../long.mp3", "engine": "16k_zh" }
=> { "task_id": "123456", "status": "processing" }

# 2) 查询
GET /v1/audio/transcriptions/async/123456
=> { "task_id": "123456", "status": "completed", "text": "..." }
# status: waiting | processing | completed | failed

回调（免轮询）：提交时带上 callback_url，识别完成后我们会把结果 POST 到你的地址，无需再轮询。

# 提交时指定回调地址
POST /v1/audio/transcriptions/async
{
  "url": "https://.../long.mp3",
  "engine": "16k_zh",
  "callback_url": "https://your.app/asr-result"
}

# 任务完成后，你的 callback_url 会收到 POST(application/json)：
{
  "task_id": "123456",
  "status": "completed",        // completed | failed
  "text": "识别出的文本",
  "audio_duration": 12.5,        // 秒
  "result_detail": [ ... ]       // 仅提交时 res_text_format 为 1/2/3 时返回（词级时间戳）
}

GET /v1/usage
=> { "calls": 12, "audio_seconds": 0 }

通过 engine 参数指定。大模型 / 多语种引擎建议配合录音文件识别使用。

通过 MCP 把语音转文字接进 Claude Desktop / Claude Code / Cursor 等 AI 助手， 配置一次后，直接对它说「把这段音频转成文字」就行，不用写代码。 下面三步走，照做即可。

第一步：拿到 API Key

在控制台注册登录 → 创建一个 API Key（形如 sk-xxxx），复制备用。新账号有免费体验额度。

第二步：接入你的 AI 助手

Claude Desktop：设置 → Developer → Edit Config，打开 claude_desktop_config.json，填入（把 key 换成你的）：

{
  "mcpServers": {
    "fastasr": {
      "command": "npx",
      "args": ["-y", "fastasr-mcp"],
      "env": {
        "ASR_API_KEY": "sk-你的key",
        "ASR_BASE": "https://asr.szchuyue.cn/api"
      }
    }
  }
}

保存后重启 Claude Desktop。

Claude Code：终端里一行命令即可：

claude mcp add fastasr \
  -e ASR_API_KEY=sk-你的key \
  -e ASR_BASE=https://asr.szchuyue.cn/api \
  -- npx -y fastasr-mcp

想所有项目都能用，加 -s user。新开一个会话后，输入 /mcp 看到 fastasr 为 connected 即接入成功。

Trae：设置 → 左侧 MCP → 点「+ 添加」进入市场 → 点市场页顶部的「手动配置」→ 粘贴上面那段相同的 JSON 并确认（MCP 是通用协议，配置格式一致）。Cursor、Windsurf 等其他客户端同理，在各自的 MCP 设置里粘同一段 JSON。

第三步：开始用

直接在对话里说要转什么，把文件的完整路径或 URL 给它，它会自动调用：

转写 /Users/你/Downloads/录音.mp3

把 ~/Desktop/会议.m4a 转成纯文字

把 ~/Downloads/采访.mp4 转成文字       # 视频，需本机装 ffmpeg

给 ~/Downloads/视频.mp4 生成 SRT 字幕   # 一步出字幕文件

识别这个音频 https://example.com/a.mp3

小技巧：把文件拖进终端会自动粘出完整路径；或在访达里选中文件， 右键按住 Option →「拷贝...为路径名称」。

提供的工具

• transcribe —— 短音频（<60s）转文字，支持本地文件或 URL
• transcribe_long —— 长音频/视频，异步自动轮询出结果；本地文件自动直传对象存储再识别（不限大小）； 可传 plain_text: true 返回纯文本（默认保留 [开始,结束] 时间戳）
• transcribe_to_subtitle —— 音视频一步生成字幕文件（SRT/VTT）并写入磁盘；format: "vtt" 切换格式，output_path 指定输出路径
• list_engines —— 列出支持的语言/引擎

说明：转视频需本机装 ffmpeg（macOS：brew install ffmpeg）， 会自动提取音频再上传；纯音频无需 ffmpeg。按识别时长计费，余额不足请到控制台充值。

Skills 是 AI 助手的「指令包」（一个 SKILL.md 文件 + 可选脚本），是 MCP 之外的另一种接入方式， 和 MCP 二选一即可。多数用户用上面的 MCP 就够了；Skills 适合两类人： ① 只想用 curl、不装 MCP server 的用户；② 想把「转写 + 自定义处理」做成固定流程的用户。

SKILL.md 是正在普及的开放标准，已被 Claude、OpenAI Codex、腾讯 CodeBuddy 等支持（Trae / 通义灵码等暂用各自的技能体系）。一份 skill 基本通用，只是放置目录不同：

• Claude → ~/.claude/skills/<名字>/
• OpenAI Codex → ~/.agents/skills/<名字>/
• 腾讯 CodeBuddy → ~/.codebuddy/skills/<名字>/

放好对应文件、重启工具后，说「转写…」会自动触发。下面以 Claude 目录为例。

Skill 一：语音转写（asr-transcribe，纯 curl，无需 MCP）

仅适合音频文件（直传，不提取、不走对象存储）。视频 / 大文件请用上面的 MCP（自动 ffmpeg 提取 + 对象存储直传）；直传文件有 30MB 上限。

1. 在控制台创建 API Key（sk-xxx）。
2. 把上面下载的 SKILL.md 放到 ~/.claude/skills/asr-transcribe/SKILL.md。
3. 设置环境变量（可写进 ~/.zshrc）：export ASR_API_KEY=sk-你的key。
4. 重启 Claude，说「转写 ~/Downloads/录音.mp3」即可。

Skill 二：生成字幕工作流（asr-subtitle，配合 MCP）

转写交给 fastasr MCP，自带脚本把时间戳转成 SRT/VTT。下载下面两个文件，分别放到~/.claude/skills/asr-subtitle/SKILL.md 与~/.claude/skills/asr-subtitle/scripts/to_subtitle.py：

提示：只是想出字幕的话，直接用上面 MCP 的 transcribe_to_subtitle 工具一步到位、更省事； 本 skill 适合需要在转写后再做自定义处理的场景。