斯蒂芬·阿瑟
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
python3 scripts/asr_transcribe.py /path/to/audio.mp3
# StepFun stepaudio-2.5-asr
Transcribe audio with StepFun's `stepaudio-2.5-asr` (released 2026-04, verified 2026-04-23). Long audio in one call, no chunking — but **only** if the request hits the right endpoint with the right body shape. The wrong endpoint returns an error that looks identical to "model doesn't exist", which is the #1 reason this skill exists.
> Companion: for TTS with `stepaudio-2.5-tts` (the sibling model), use the `stepfun-tts` skill — they share an API key but live on different endpoints with different body shapes.
## Why this skill exists — three traps that cost hours
1. **Wrong endpoint, wrong error**. `stepaudio-2.5-asr` does **not** live on `/v1/audio/transcriptions` (that endpoint serves the older `step-asr` family). It lives on `/v1/audio/asr/sse` — SSE streaming, JSON body, base64 audio. Sending it to the wrong endpoint returns `{"error":{"message":"model stepaudio-2.5-asr not supported"}}`, which is **identical in structure** to a genuinely nonexistent model name. People waste hours filing whitelist tickets.
2. **Plan key vs Normal key, silent failure**. StepFun's "Plan" subscription keys (cheap, text-only) cannot call audio endpoints, but the failure manifests as a 4xx with no auth-shaped error message. If your account has a Plan subscription, you need a separate "Normal" key from the same console.
3. **SSE error events are real**. Censorship can fire on the ASR side too (rarely). Don't assume only `transcript.text.delta` and `transcript.text.done` events arrive — handle `type: error` events in the stream or you'll silently drop them.
## Config and auth
API key resolves in this order (fail-fast, no defaults):
1. `$STEPFUN_API_KEY` environment variable
2. `${CLAUDE_PLUGIN_DATA}/config.json` with `{"api_key": "..."}` (cross-session persistence)
First-time setup:
```bash
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<paste Normal key here>"}
EOF
```
If the user has not set a key, ask them to paste it — do not guess or use a placeholder. Get keys at https://platform.stepfun.com/ → API Keys. **Use a Normal key, not a Plan key.**
## Quick start — single file
```bash
python3 scripts/asr_transcribe.py /path/to/audio.mp3
```
Output: plain text transcription on stdout.
For machine-readable output with usage / timing:
```bash
python3 scripts/asr_transcribe.py /path/to/audio.mp3 --json
```
For non-Chinese audio:
```bash
python3 scripts/asr_transcribe.py /path/to/audio.mp3 --language en
```
The script handles base64 encoding, the nested `{audio: {data, input: {transcription, format}}}` body, SSE parsing, and the misleading-endpoint pitfall. Prefer it over hand-rolled HTTP calls unless integrating into a larger pipeline.
## Decision table
| Scenario | Action |
|---|---|
| Short clip (< 5 min), Chinese or English, mp3/wav/ogg/opus | `python3 scripts/asr_transcribe.py audio.mp3` |
| Long audio (5-30 min) | Same script — 32K context handles it in a single call, no chunking needed |
| Audio > 30 min | Split with ffmpeg before sending; the API rejects oversized payloads |
| Need usage/billing data | Add `--json` to capture `usage.input_tokens` / `usage.total_tokens` from `transcript.text.done` |
| Highly repetitive content (same phrase 5+ times, > 90s) | Cross-validate with `step-asr-1.1` — see repetition hallucination in `references/known_issues.md` |
| Hit `model stepaudio-2.5-asr not supported` | Wrong endpoint. Switch from `/v1/audio/transcriptions` to `/v1/audio/asr/sse` |
| Hit silent 4xx auth failure | Verify your key is "Normal" not "Plan" — Plan keys cannot call audio endpoints |
| Need to write raw HTTP (no Python) | Read `references/api_reference.md` for exact JSON body and SSE event shapes |
## Supported audio formats
The script auto-detects from extension; pass `--format` to override:
| Extension | Format flag | Notes |
|---|---|---|
| `.mp3` | `mp3` | Most common, default |
| `.wav` | `wav` | Lossless |
| `.ogg` | `ogg` | OGG container |
| `.opus` | `ogg` | Opus codec in OGG container — pass through unchanged |
| `.pcm` | `pcm` | Raw PCM — also requires `format.rate`, `format.channel`, `format.bits` (see API reference) |
For mp4/m4a/webm/etc., transcode to one of the above first via ffmpeg. Production pipelines often pre-transcode everything to OGG/Opus 16kHz mono to minimize base64 payload size.
## Capacity and performance (verified 2026-04-23)
- **32K context window** — single-call upper limit, no chunking needed for ≤ 30 min audio
- **~85-101× RTF** on long audio (17.4 min audio → 10.4s wall clock)
- **~5.3× speedup vs step-asr-1.1** at the 100s+ length range
- **Only ~2× speedup** at the 5-15s range — the LLM spin-up cost dominates short clips. If your workload is many short clips, the migration ROI is modest
## Common error patterns
| Error response | Actual cause | Fix |
|---|---|---|
| `"model stepaudio-2.5-asr not supported"` on `/v1/audio/transcriptions` | Wrong endpoint | Switch to `/v1/audio/asr/sse` (script does this) |
| Silent 4xx with no auth message | Using a "Plan" key on audio endpoint | Get a "Normal" key from the StepFun console |
| ASR returns 3-4× expected character count | Repetition hallucination on highly-repetitive audio | Cross-validate with `step-asr-1.1`; see `references/known_issues.md` |
| `data: {"type":"error","message":"content blocked..."}` mid-stream | Censorship fired on user-uploaded content | Handle SSE `error` event explicitly; don't assume only `delta`/`done` arrive |
More edge cases in `references/known_issues.md`.
## Design invariants (do not break)
1. **Always pass through SSE** — don't try to buffer the response with a non-streaming client. The model emits `transcript.text.delta` for long audio; `transcript.text.done` carries the authoritative full text and `usage`. Reject the SSE format entirely and you'll get nothing.
2. **Take final text from `transcript.text.done.text`** — concatenated deltas can drift on edge cases. Deltas are for progressive UI; the `done` event is the source of truth.
3. **Handle `error` events in the stream** — don't treat the SSE stream as if only success events arrive. A blocked-content event mid-stream returns `type: error` with no `done` event.
4. **Fail-fast on missing API key** — never default to a placeholder or empty string. The script does this; preserve the behavior in any wrapper.
## When to read references
- `references/api_reference.md` — exact JSON request body, all fields, all SSE event types, response examples. Read when writing raw HTTP calls instead of using the bundled script.
- `references/known_issues.md` — repetition hallucination details, the wrong-endpoint diagnostic trail, Plan-vs-Normal key gotcha, ASR-side censorship handling, pricing opacity. Read when debugging anomalous output or evaluating whether to migrate from `step-asr-1.1`.
## Pricing (verified 2026-04-23, volatile)
`stepaudio-2.5-asr` is in invitation beta as of 2026-04-23 — no public per-minute rate. The `step-asr-1.1` baseline is 2.2 元/小时. The invitation PDF mentions "成本直降 80%" implying ~0.4 元/小时, but this is not yet on the pricing page. Re-verify at https://platform.stepfun.com/docs/zh/guides/pricing/details before quoting to stakeholders.
## Next Step
ASR transcripts almost always benefit from one of two downstream steps. After producing the transcript, suggest the natural next skill:
```
Transcription complete. The output is raw text from the model — common next steps:
Options:
A) transcript-fixer — clean up ASR errors (homophones, segmentation, filler words). Recommended if the recording is a real-world conversation, podcast, or interview rather than read-aloud text
B) meeting-minutes-taker — turn the transcript into structured minutes with decisions, action items, and speaker attribution. Recommended if the recording is a meeting
C) No thanks — the raw transcript is what I needed
```
Skip the suggestion when the user has already specified the downstream tool, or when the transcription was clearly a one-off lookup (e.g., "what does this 15-second clip say?").
章节与文件索引
按说明文件中的顺序排列。
为什么存在这项技能——需要花费数小时的三个陷阱
配置和授权
快速启动——单个文件
决策表
支持的音频格式
文件/命令 -> stepaudio-2.5-asr · stepaudio-2.5-tts · stepfun-tts · /v1/audio/transcriptions · step-asr · /v1/audio/asr/sse · {"error":{"message":"model stepaudio-2.5-asr not supported"}} · transcript.text.delta
内容校验值 -> 64f77f389d3a
当前原文的自动摘译,尚未人工审校。
为什么存在这项技能——需要花费数小时的三个陷阱
错误的终点,错误的错误。
stepaudio-2.5-asr不在/v1/audio/transcriptions上(该端点服务于旧的step-asr系列)。它依赖于/v1/audio/asr/sse— SSE 流、JSON 正文、base64 音频。将其发送到错误的端点将返回{"error":{"message":"model stepaudio-2.5-asr not supported"}},其结构与真正不存在的模型名称相同。人们浪费大量时间来提交白名单票据。配置和授权
API 密钥按此顺序解析(快速失败,无默认值):
$STEPFUN_API_KEY环境变量${CLAUDE_PLUGIN_DATA}/config.json和{"api_key": "..."}(跨会话持久性) 首次设置:如果用户尚未设置密钥,请要求他们粘贴它 — 不要猜测或使用占位符。在 https://platform.stepfun.com/ 获取密钥 → API 密钥。使用普通键,而不是计划键。快速启动——单个文件
输出:标准输出上的纯文本转录。对于带有用法/计时的机器可读输出: 对于非中文音频:脚本处理 base64 编码、嵌套的
{audio: {data, input: {transcription, format}}}主体、SSE 解析和误导性端点陷阱。除非集成到更大的管道中,否则优先使用它而不是手动 HTTP 调用。决策表
场景 · 动作短片(< 5 分钟),中文或英语,mp3/wav/ogg/opus ·
python3 scripts/asr_transcribe.py audio.mp3长音频(5-30 分钟) · 相同的脚本 — 32K 上下文在一次调用中处理它,无需分块 音频 > 30 分钟 · 发送前使用 ffmpeg 进行分割; API 拒绝超大有效负载 需要使用/计费数据 · 添加--json以从transcript.text.done捕获usage.input_tokens/usage.total_tokens支持的音频格式
脚本自动检测扩展名;通过
--format覆盖:扩展名 · 格式标志 · 注释.mp3·mp3· 最常见,默认.wav·wav· 无损.ogg·ogg· OGG 容器