byted-voice-to-text

Q: How do I install byted-voice-to-text?

Run npx skills add https://github.com/bytedance/agentkit-samples --skill byted-voice-to-text in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/byted-voice-to-text/ (personal) or .claude/skills/byted-voice-to-text/ (project).

by bytedanceMedia & Creative

语音转文字（ASR）。使用火山引擎 BigModel ASR 识别语音，包含极速版（≤2h/100MB 同步快速返回）和标准版（≤5h 异步识别）两种模式。支持飞书语音消息、本地音频文件及音频 URL。当收到语音消息或音频附件（.ogg/.mp3/.wav）时使用本技能。

Installs: 95
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/bytedance/agentkit-samples --skill byted-voice-to-text

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads byted-voice-to-text automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Voice to Text Skill

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

核心执行流

收到飞书语音消息（message_type: audio），需要自动识别语音内容
用户给音频要转文字：
- 先跑 inspect_audio.py
- 再按时长、大小、URL/本地路径选择 asr_flash.py（极速版）或 asr_standard.py（标准版）
缺 ffmpeg / ffprobe：先执行 ensure_ffmpeg.py --execute
用户问安装、开通、手工配置：按文末 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，只有失败后才向用户求助

使用步骤

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

URL / 大文件 / 切片 / 路由细节：读 routing_strategy.md

参考文档

FAQ

What does the byted-voice-to-text skill do?

How do I install byted-voice-to-text?

Run npx skills add https://github.com/bytedance/agentkit-samples --skill byted-voice-to-text in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/byted-voice-to-text/ (personal) or .claude/skills/byted-voice-to-text/ (project).

Which AI agents can use byted-voice-to-text?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is byted-voice-to-text safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains byted-voice-to-text?

It is published by bytedance in bytedance/agentkit-samples. It has 95 recorded installs.

More from bytedance/agentkit-samples

View all →

byted-web-search

bytedance/agentkit-samples

火山引擎联网搜索 API，返回网页/图片结果。联网搜索场景优先使用本 skill。触发词包括：查/搜/找、真的吗/靠谱吗/确认/核实、最近/今天/最新/近期、出处/来源/链接、有什么/有哪些/推荐、价格/政策/汇率/行情、对比/区别/哪个好、听说/据说/不太确定、热搜/热门/火、帮我看/了解一下、求证/辟谣、值不值得/该不该。任务依赖在线事实或时效性时优先使用。若回答可能依赖外部事实，优先调用本 skill 再作答。支持 API Key / AK/SK。

Productivity & Automation618 installs

byted-seedream-image-generate

bytedance/agentkit-samples

Generate high-quality images from text prompts using Volcano Engine Seedream models. Supports multiple artistic styles and aspect ratios. Use this skill when users want to create images from text descriptions, generate artwork in various styles, create visual content for creative projects, or need AI-powered image generation capabilities.

Media & Creative298 installs

byted-las-video-edit

bytedance/agentkit-samples

智能视频剪辑：用自然语言描述要保留的片段/人物/事件，自动从长视频抽取剪辑（可用参考图做人物/物体匹配）。当用户要按描述找片段、提取高光或做智能剪辑时触发。

Media & Creative209 installs

byted-text-to-speech

bytedance/agentkit-samples

将文本合成为语音（TTS）。使用火山引擎豆包语音合成 API，支持流式合成、多种音色、语速/音调/音量调节、Markdown 过滤和 LaTeX 公式播报。当用户需要把文字转成语音、生成朗读音频、配音、旁白、播报，或提到「文字转语音」「TTS」「语音合成」「朗读」「配音」时使用本技能。

Media & Creative184 installs

byted-seedance-video-generate

bytedance/agentkit-samples

Open the skill to read its SKILL.md instructions.

Media & Creative178 installs

byted-las-pdf-parse-doubao

bytedance/agentkit-samples

Open the skill to read its SKILL.md instructions.

Docs & Writing162 installs

Popular media & creative skills

View category →

hyperframes

heygen-com/hyperframes

Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.

Media & Creative1.2M installs

media-use

heygen-com/hyperframes

Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.

Media & Creative1.1M installs

hyperframes-registry

heygen-com/hyperframes

About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.

Media & Creative1M installs

hyperframes-creative

heygen-com/hyperframes

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use hyperframes-animation.

Media & Creative916.5K installs

ai-video-generation

101-skills/superpowers

Generate AI videos with Google Veo, Seedance 2.0, HappyHorse, Wan, Grok and 40+ models via inference.sh CLI. Models: Veo 3.1, Veo 3, Seedance 2.0, HappyHorse 1.0, Wan 2.5, Grok Imagine Video, OmniHuman, Fabric, HunyuanVideo. Capabilities: text-to-video, image-to-video, reference-to-video, video editing, lipsync, avatar animation, video upscaling, foley sound. Use for: social media videos, marketing content, explainer videos, product demos, AI avatars. Triggers: video generation, ai video, text to video, image to video, veo, animate image, video from image, ai animation, video generator, generate video, t2v, i2v, ai video maker, create video with ai, runway alternative, pika alternative, sora alternative, kling alternative, seedance, happyhorse

Media & Creative881.5K installs

ai-image-generation

101-skills/superpowers

Generate AI images with GPT-Image-2, FLUX, Gemini, Grok, Seedream, Reve and 50+ models via inference.sh CLI. Models: GPT-Image-2, FLUX Dev LoRA, FLUX.2 Klein LoRA, Gemini 3 Pro Image, Grok Imagine, Seedream 4.5, Reve, ImagineArt. Capabilities: text-to-image, image-to-image, inpainting, LoRA, image editing, upscaling, text rendering. Use for: AI art, product mockups, concept art, social media graphics, marketing visuals, illustrations. Triggers: flux, image generation, ai image, text to image, stable diffusion, generate image, ai art, midjourney alternative, dall-e alternative, text2img, t2i, image generator, ai picture, create image with ai, generative ai, ai illustration, grok image, gemini image, gpt image, openai image, chatgpt image

Media & Creative880.3K installs

byted-voice-to-text

Install

Install

Describe the task

Review the result

SKILL.md

Voice to Text Skill

核心执行流

强制规则（最高优先级）

使用步骤

路由速记

本地文件

公网 URL

环境变量与鉴权

脚本清单

最小脚本示例

asr_flash.py (极速版) 参数

asr_standard.py (标准版) 参数

飞书语音消息处理流程

错误处理

何时继续读 references

参考文档

FAQ

More from bytedance/agentkit-samples

Popular media & creative skills