#601

Global Rank · of 601 Skills

byted-voice-to-text AI Agent Skill

View Source: bytedance/agentkit-samples

Medium

Installation

npx skills add bytedance/agentkit-samples --skill byted-voice-to-text

44

Installs

Voice to Text Skill

基于火山引擎 BigModel ASR 将语音转为文字。准确率和多语言能力远优于本地 whisper，且速度更快。

核心执行流

  1. 收到飞书语音消息（message_type: audio），需要自动识别语音内容
  2. 用户给音频要转文字：
    • 先跑 inspect_audio.py
    • 再按时长、大小、URL/本地路径选择 asr_flash.py（极速版）或 asr_standard.py（标准版）
  3. 缺 ffmpeg / ffprobe：先执行 ensure_ffmpeg.py --execute
  4. 用户问安装、开通、手工配置：按文末 reference map 读取对应文档

强制规则（最高优先级）

当你收到语音消息或音频文件附件时：

  • 必须且只能使用 本 Skill 的脚本来识别语音
  • 禁止使用 whisper 命令或 openai-whisper skill
  • 禁止 fallback：脚本失败时直接将错误信息告知用户，不要改用 whisper
  • 先探测后识别：统一先执行 python3 <SKILL_DIR>/scripts/inspect_audio.py "<AUDIO_INPUT>"
  • 缺 ffmpeg/ffprobe 先自治安装：先执行 python3 <SKILL_DIR>/scripts/ensure_ffmpeg.py --execute，只有失败后才向用户求助

使用步骤

  1. 确认音频来源（本地文件、URL 或飞书语音 file_key）。
  2. 运行脚本前先 cd 到本技能目录：skills/byted-voice-to-text。
  3. 执行对应命令（见下方参数说明）。
  4. 将脚本输出的文字当作用户发送的文本消息，理解其意图并正常回复。不需要额外说明"语音识别结果是xxx"，直接回答用户的问题即可。

路由速记

本地文件

条件 脚本
时长 ≤ 2h 且 大小 ≤ 100MB asr_flash.py --file "<FILE>" （极速版，同步快速返回）
2h < 时长 ≤ 5h asr_standard.py --file "<FILE>" （标准版，异步 submit+poll）
时长 > 5h 不支持，先切片后逐片走极速版
无法获取时长 且 大小 ≤ 100MB asr_flash.py --file "<FILE>" （极速版兜底）
无法获取时长 且 大小 > 100MB asr_standard.py --file "<FILE>" （标准版兜底）

公网 URL

  • 默认直接走 asr_standard.py --url "<URL>"
  • 不要先下载到本地、探测、转码再路由
  • 只有标准版真实失败时，再按错误决定是否进入本地下载/切片链

命中 URL、大文件、切片取舍时，再读 routing_strategy.md。

环境变量与鉴权

鉴权采用新版控制台方案，详见：快速入门（新版控制台）。

环境变量 用途 必需
MODEL_SPEECH_API_KEY API Key（新版控制台方案） 是
MODEL_SPEECH_APP_ID App ID（旧版鉴权时配合使用） 否
MODEL_SPEECH_ASR_API_BASE 极速版端点（有默认值） 否
MODEL_SPEECH_ASR_RESOURCE_ID 极速版资源 ID（默认 volc.bigasr.auc_turbo） 否
MODEL_SPEECH_ASR_STANDARD_SUBMIT_URL 标准版提交端点（有默认值） 否
MODEL_SPEECH_ASR_STANDARD_QUERY_URL 标准版查询端点（有默认值） 否
MODEL_SPEECH_ASR_STANDARD_RESOURCE_ID 标准版资源 ID（默认 volc.bigasr.auc） 否
FEISHU_TENANT_TOKEN 飞书 tenant_access_token（仅 --file-key 模式） 否

脚本清单

脚本 用途 对应模式
scripts/inspect_audio.py 音频元信息探测（时长、采样率、声道等） 预检
scripts/ensure_ffmpeg.py 自动检测并安装 ffmpeg/ffprobe 预检
scripts/asr_flash.py 极速版识别（≤2h/100MB，同步） Express/Flash
scripts/asr_standard.py 标准版识别（≤5h，异步 submit+poll） Standard

最小脚本示例

# 预检：探测音频元信息
python3 <SKILL_DIR>/scripts/inspect_audio.py "<AUDIO_INPUT>"

# 缺 ffmpeg 时自动安装
python3 <SKILL_DIR>/scripts/ensure_ffmpeg.py --execute

# 极速版（短音频，≤2h/100MB）
python3 <SKILL_DIR>/scripts/asr_flash.py --file "<AUDIO_FILE>"

# 标准版（长音频或 URL）
python3 <SKILL_DIR>/scripts/asr_standard.py --url "<AUDIO_URL>"
python3 <SKILL_DIR>/scripts/asr_standard.py --file "<LONG_AUDIO_FILE>"

# 标准版：仅提交不轮询
python3 <SKILL_DIR>/scripts/asr_standard.py --url "<URL>" --no-poll

# 标准版：查询已有任务
python3 <SKILL_DIR>/scripts/asr_standard.py --query-task-id <ID> --query-logid <LOGID>

asr_flash.py (极速版) 参数

参数 必填 说明
--file 三选一 本地音频文件路径
--url 三选一 音频文件的 URL 地址
--file-key 三选一 飞书语音消息的 file_key
--feishu-token 否 飞书 tenant_access_token
--appid 否 App ID
--token 否 API Key
--language 否 语言代码

asr_standard.py (标准版) 参数

参数 必填 说明
--url 二选一 音频文件的 URL 地址
--file 二选一 本地音频文件路径
--appid 否 App ID
--token 否 API Key
--language 否 语言代码
--no-poll 否 仅提交任务，不轮询结果
--poll-interval 否 轮询间隔秒数（默认 3）
--poll-max-time 否 最大轮询时间秒数（默认 10800）
--query-task-id 否 查询已有任务 ID
--query-logid 否 查询时传入的 X-Tt-Logid

飞书语音消息处理流程

收到 audio 消息 → 音频文件已下载到 /root/.openclaw/media/inbound/ → 执行 asr_flash.py --file → 返回文字 → 当作用户消息处理

常用命令：

# 飞书语音文件（最常用，文件已被飞书插件自动下载）
python scripts/asr_flash.py --file "/root/.openclaw/media/inbound/xxxxx.ogg"

错误处理

  • PermissionError: MODEL_SPEECH_API_KEY ... → 提示用户配置 API Key
  • ASR 请求失败 → 检查 API 凭据及账号
  • 音频时长超过 5 小时 → 提示用户切分文件
  • 音频文件不存在/为空 → 检查文件路径
  • 遇到报错时直接告知用户具体错误，不要尝试用 whisper 替代。

何时继续读 references

参考文档

Installs

Installs 44
Global Rank #601 of 601

Security Audit

ath Safe
socket Safe
Alerts: 0 Score: 90
snyk Medium
EU EU-Hosted Inference API

Power your AI Agents with the best open-source models.

Drop-in OpenAI-compatible API. No data leaves Europe.

Explore Inference API

GLM

GLM 5

$1.00 / $3.20

per M tokens

Kimi

Kimi K2.5

$0.60 / $2.80

per M tokens

MiniMax

MiniMax M2.5

$0.30 / $1.20

per M tokens

Qwen

Qwen3.5 122B

$0.40 / $3.00

per M tokens

How to use this skill

1

Install byted-voice-to-text by running npx skills add bytedance/agentkit-samples --skill byted-voice-to-text in your project directory. Run the install command above in your project directory. The skill file will be downloaded from GitHub and placed in your project.

2

No configuration needed. Your AI agent (Claude Code, Cursor, Windsurf, etc.) automatically detects installed skills and uses them as context when generating code.

3

The skill enhances your agent's understanding of byted-voice-to-text, helping it follow established patterns, avoid common mistakes, and produce production-ready output.

What you get

Skills are plain-text instruction files — not executable code. They encode expert knowledge about frameworks, languages, or tools that your AI agent reads to improve its output. This means zero runtime overhead, no dependency conflicts, and full transparency: you can read and review every instruction before installing.

Compatibility

This skill works with any AI coding agent that supports the skills.sh format, including Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider, and other tools that read project-level context files. Skills are framework-agnostic at the transport level — the content inside determines which language or framework it applies to.

Data sourced from the skills.sh registry and GitHub. Install counts and security audits are updated regularly.

EU Made in Europe

Chat with 100+ AI Models in one App.

Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.

Start for free View pricing
Customer Support