Content & Media Creation · daymade/claude-code-skills
stepfun-asr
Transcribe audio with StepFun's stepaudio-2.5-asr — an SSE endpoint (NOT /v1/audio/transcriptions) with 32K context, ~85-101x RTF on long audio, and a single-call ceiling around 30 minutes (no client-side chunking). Use when transcribing Chinese / English audio with StepFun, when long-form recordings (5-30 min) need to land in one request, when migrating from step-asr / step-asr-1.1, or when hitting the misleading `model stepaudio-2.5-asr not supported` error (which actually means wrong endpoint). Triggers on 阶跃 ASR, StepFun ASR, stepaudio-2.5-asr, 转录, 语音识别, 长音频转写, 语音转文字. For TTS with the sibling stepaudio-2.5-tts model, use the stepfun-tts skill instead.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The premise of this skill is uncovering three pitfalls that look like unrelated issues: deceptive errors from the wrong endpoint, silent failures from Plan keys, and error events delivered inside the SSE stream.
daymade-audio/stepfun-asr/SKILL.md
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.
What this is doing: Re-attributing errors shaped like 'model not found' (such as 'model stepaudio-2.5-asr not supported') back to an incorrect endpoint, preventing users from wasting time filing whitelisting support tickets. The script encapsulates the correct endpoint and request body so callers never stumble into this trap.
A single-file script encapsulates proper requests: reads the audio file → base64-encodes it → wraps it in a nested JSON body → POSTs to the SSE endpoint, fetching the Authorization Bearer token from env/config.
daymade-audio/stepfun-asr/scripts/asr_transcribe.py
audio_b64 = base64.b64encode(audio_path.read_bytes()).decode("ascii") body = json.dumps({"audio": {"data": audio_b64, "input": {"transcription": {"language": language, "model": MODEL, "enable_itn": enable_itn}, "format": {"type": audio_format}}}}).encode()
ASR_URL = "https://api.stepfun.com/v1/audio/asr/sse", MODEL = "stepaudio-2.5-asr"; built with the urllib standard library (zero external dependencies), using timeout=1200 (20 minutes) to accommodate long audio.
SSE parsing discipline: avoid buffering into non-streaming responses, collect deltas, treat the text in transcript.text.done as the authoritative full text and usage source, and explicitly handle error events.
daymade-audio/stepfun-asr/scripts/asr_transcribe.py
if t == "transcript.text.delta": deltas += 1 elif t == "transcript.text.done": text = ev.get("text", "") usage = ev.get("usage")
Directly matches SKILL.md Design invariants: '**Take final text from `transcript.text.done.text`** — concatenated deltas can drift on edge cases' and 'Always pass through SSE' — deltas are reserved strictly for progress UI, as concatenating them may drift.
Fail-fast API key resolution: prioritizes $STEPFUN_API_KEY, falling back to api_key in ${CLAUDE_PLUGIN_DATA}/config.json; aborts immediately with an error if missing, never using placeholders.
daymade-audio/stepfun-asr/scripts/asr_transcribe.py
k = os.environ.get("STEPFUN_API_KEY", "").strip() if k: return k plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA", "").strip() if plugin_data: cfg = Path(plugin_data) / "config.json"
SKILL.md explicitly dictates using a Normal key rather than a Plan key (Plan subscription keys cannot call audio endpoints and fail silently without standard auth error shapes); 'If the user has not set a key, ask them to paste it — do not guess or use a placeholder.'
Capacity and performance boundary management: the 32K context cap allows ≈30 minutes of audio per single request; split with ffmpeg prior to requests for audio exceeding 30 minutes; formats are auto-detected by extension (mp3/wav/ogg/opus/pcm).
daymade-audio/stepfun-asr/SKILL.md
| Audio > 30 min | Split with ffmpeg before sending; the API rejects oversized payloads |
The decision matrix also advises cross-verifying repetitive content (same phrase repeated 5+ times, >90s) with step-asr-1.1 to safeguard against hallucinated loops; the format table specifies .opus is passed through as ogg, while .pcm requires explicit rate/channel/bits.
Failure modes translated into an actionable remediation matrix: misleading 412s, silent 4xx errors, sudden spikes of repeating characters, and censorship events each have dedicated handling.
daymade-audio/stepfun-asr/SKILL.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 |
On the script side, responses containing censorship/blocked are classified as censored and print a dedicated notice ('content blocked by StepFun censorship. The audio likely contains sensitive content.'), distinguishing them clearly from transmission errors.
2Core Capabilities
01Single-command transcription (python3 scripts/asr_transcribe.py audio.mp3 → plaintext stdout; --json outputs usage/timing)
02Long-audio single-request capability (5-30 minutes, 32K context with zero chunking)
03Bilingual Chinese/English support with auto format detection (mp3/wav/ogg/opus/pcm, overrideable via --language/--format)
04Actionable guidance for misleading endpoint errors (not supported → switch to /v1/audio/asr/sse)
05Explicit handling of censorship and blocked content (error events are never silently discarded)
06Usage statistics reporting (usage.input_tokens / usage.total_tokens in --json mode)
07Downstream handover suggestions: prompts for transcript-fixer / meeting-minutes-taker upon transcription completion (skippable)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| network | api.stepfun.com（StepAudio ASR SSE 端点） |
| network | platform.stepfun.com（文档/定价/取 key，仅指引） |
| cli | python3（stdlib urllib，无第三方包） |
| cli | ffmpeg（仅 >30 分钟切分建议，非脚本依赖） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local script or command: daymade-audio/stepfun-asr/scripts/asr_transcribe.py
- 网络端点: Declares outbound network access: POST https://api.stepfun.com/v1/audio/asr/sse (payload contains full base64 audio + Bearer authorization)
Audit Notes: Classified under standard tiering: access to plaintext API credentials (reading $STEPFUN_API_KEY environment variable or api_key from ${CLAUDE_PLUGIN_DATA}/config.json) warrants an Orange rating, regardless of whether credentials are transmitted externally. In addition, external network transmission is present (full audio content is POSTed to the official third-party api.stepfun.com endpoint with Bearer authentication); while the destination is predictable, content sensitivity is governed by the user's audio. No file writing or shell injection surfaces exist.
5Second-Pass Verification
- [ok] 端点与 body 形状（SSE/嵌套/32K 不切片） — asr_transcribe.py ASR_URL 与嵌套 dict body 逐字存在；SKILL.md 决策表同描述。
- [ok] API key 解析顺序（env → CLAUDE_PLUGIN_DATA/config.json） — load_api_key() 先 os.environ.get('STEPFUN_API_KEY') 后读 Path(plugin_data)/config.json 的 api_key，fail-fast sys.exit(2)，无占位默认。
- [ok] SSE 事件处理（delta/done/error） — 脚本对 data: 行 json 解析后按 type 分支：delta 计数、done 取 text+usage、error 收 message；无 text 且有 errors 时返回失败。
- [ok] 无第三方 python 包依赖 — imports 仅 argparse/base64/json/os/sys/time/urllib/pathlib；SKILL.md『Prefer it over hand-rolled HTTP calls』成立。
- [ok] 凭证接触面仅 STEPFUN_API_KEY/config.json — 全目录 token 扫描无其他 key/token/secret 读取；config.json 只读 api_key 字段。
- [ok] 网络外发对象与 SKILL 描述一致 — 仅 POST api.stepfun.com/v1/audio/asr/sse + 文档站点指引（无请求）；无任何回调/遥测 URL。
- [ok] 功能声明 vs 夸大检查 — 性能/容量数字均标注『verified 2026-04-23』与价格 volatile；误导性报错解释与 known_issues 诊断轨迹一致。
- [ok] 元数据（license/stars/commit） — 仓库级 MIT、stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。
6Verdict & Scenarios
Best for: Best for: StepFun users requiring single-request transcriptions for long-form Chinese/English audio (5-30 minutes); teams migrating from step-asr/step-asr-1.1; integrators blocked by misleading 'model not supported' errors needing the correct endpoint and payload templates; and downstream pipelines feeding transcripts into transcript-fixer or meeting-minutes-taker.
Not for: Not suitable for: unsegmented audio longer than 30 minutes (API rejects oversized payloads; requires pre-splitting with ffmpeg); users without a StepFun Normal key (Plan keys fail silently); workflows demanding final publication-ready copy without post-ASR proofreading (should route to transcript-fixer); scenarios seeking generic local or third-party cloud ASR without using StepFun services.
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload stepfun-asr.tar.gz
sha256:
Option B · Copy Guide for Agent6954122ed209d0d4…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.