stepfun-asr
Transcribes Chinese/English audio with StepFun's stepaudio-3-asr-max via its SSE endpoint (not /v1/audio/transcriptions) β one call handles long-form audio with no chunking
Install / Use
npx skills add daymade/claude-code-skills --skill stepfun-asrInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Customer SupportSupported Platforms
Tags
Our assessment of stepfun-asr
stepfun-asr scores 92/100 on our quality scale, 115th of 319 Customer Support skills we index (top 37%).
Its SKILL.md is 12 KB long, well organised into 16 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.
With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so stepfun-asr is actively maintained.
- Our last check on 2026-10-27 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit β read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk β read a skill before letting an agent act on it.
stepfun-asr compared with similar skills
All 4 of these similar skills score higher than stepfun-asr; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| stepfun-asr (this skill)by daymade | 92 | 1.4k | 53d ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| designby nextlevelbuilder | 100 | 149.0k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install stepfun-asr?
- Run
npx skills add daymade/claude-code-skills --skill stepfun-asr. The install tabs above show the steps for each supported agent. - Which AI agents does stepfun-asr work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is stepfun-asr safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is stepfun-asr still maintained?
- The repository was last updated about 2 months ago, so stepfun-asr is actively maintained.
Skill content
View source on GitHubname: stepfun-asr disable-model-invocation: true description: >- Transcribes Chinese/English audio with StepFun's stepaudio-3-asr-max via its SSE endpoint (not /v1/audio/transcriptions) β one call handles long-form audio with no chunking. Use when migrating from step-asr/stepaudio-2.5-asr, or hitting the misleading "model not supported" error (actually wrong endpoint). Triggers on ιΆθ· ASR, θ―ι³θ―ε«. Not for TTS with the sibling model (use stepfun-tts).
StepFun stepaudio-3-asr-max
Transcribe audio with StepFun's stepaudio-3-asr-max (StepAudio 3, released 2026-09-15, verified 2026-09-16; supersedes stepaudio-2.5-asr on the same endpoint). 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-3-tts(the sibling model), use thestepfun-ttsskill β they share an API key but live on different endpoints with different body shapes.
Why this skill exists β three traps that cost hours
-
Wrong endpoint, wrong error.
stepaudio-3-asr-maxdoes not live on/v1/audio/transcriptions(that endpoint serves the olderstep-asrfamily). It lives on/v1/audio/asr/sseβ SSE streaming, JSON body, base64 audio. Sending it to the wrong endpoint returns{"error":{"message":"model stepaudio-3-asr-max not supported"}}, which is identical in structure to a genuinely nonexistent model name. People waste hours filing whitelist tickets. -
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.
-
SSE error events are real. Censorship can fire on the ASR side too (rarely). Don't assume only
transcript.text.deltaandtranscript.text.doneevents arrive β handletype: errorevents in the stream or you'll silently drop them.
Config and auth
API key resolves in this order (fail-fast, no defaults):
$STEPFUN_API_KEYenvironment variable${CLAUDE_PLUGIN_DATA}/config.jsonwith{"api_key": "..."}(cross-session persistence)
First-time setup:
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
python3 scripts/asr_transcribe.py /path/to/audio.mp3
Output: plain text transcription on stdout.
For machine-readable output with usage / timing:
python3 scripts/asr_transcribe.py /path/to/audio.mp3 --json
For non-Chinese audio:
python3 scripts/asr_transcribe.py /path/to/audio.mp3 --language en
Per-word timestamps need no flag β --json always carries segments:
"segments": [{"text": "Understand ", "start_ms": 228, "end_ms": 1108}, ...]
One entry per word, monotonic. A few words share their predecessor's timestamp (the server flushes in blocks), which is fine for locating a moment but not for forced alignment.
To use an older model:
python3 scripts/asr_transcribe.py /path/to/audio.mp3 --model stepaudio-2.5-asr
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 |
| Need to know when each word was said | --json, read segments. On by default |
| Need speaker labels (who said what) | python3 scripts/asr_file.py <public-url> β a different, async endpoint. Takes a URL, not a local file: base64 and StepFun's own file store are both rejected, so hosting the audio somewhere fetchable is a decision for whoever runs it |
| --model stepaudio-2-asr-pro returns internal error | That model is not usable on /v1/audio/asr/sse (measured 2026-09-18); use the default or stepaudio-2.5-asr |
| Highly repetitive content (same phrase 5+ times, > 90s) | Cross-validate with step-asr-1.1 β see repetition hallucination in references/known_issues.md (2.5-era issue, unverified on v3) |
| Hit model stepaudio-3-asr-max 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 |
Speaker labels β scripts/asr_file.py
stepaudio-3-asr-max on /v1/audio/asr/sse has no speaker capability at all (14 candidate
request fields measured inert). Diarization lives on the async file endpoint:
python3 scripts/asr_file.py https://example.com/talk.mp3
# [ 6.61- 8.43] speaker_0: Hello. Hello. Oh,
# [ 8.21- 10.11] speaker_1: hello! I didn't know you were there.
Verified end-to-end 2026-09-18 on a two-speaker sample: correct turn boundaries, per-word
timestamps inside each utterance, up to 10 speakers per task. Uses stepaudio-2.5-asr β
v3 is not served on this endpoint.
The hard constraint: it fetches a URL and nothing else. Base64 is rejected and so is
StepFun's own stepfile:// file store, so there is no way to feed it a local file without
first putting that file somewhere publicly fetchable. Treat that as the caller's decision.
references/known_issues.md has the three dead ends and the retry/redirect behaviour.
Parameters are free β never omit one silently
Sending more request parameters costs nothing: billing is per audio-hour. So the default is
send everything useful, and every field we do not send has to carry a written reason in
REQUEST_PARAMS at the top of scripts/asr_transcribe.py.
python3 scripts/check_params.py # diff official field table vs REQUEST_PARAMS
python3 scripts/check_params.py --selftest # calibrate the check before trusting it
Two guards, one per direction:
- Request side β
check_params.pyfetches the official field table and fails if it lists a fieldREQUEST_PARAMSdoes not mention.--selftestcalibrates both ways: the real manifest must pass (no false alarms), and a manifest withenable_timestampremoved must be caught (the actual historical gap β per-word timestamps were missing for months because only the response field table was ever read). - Response side β the parser reports
unhandled_response_fieldsfor anything the server sends that it does not consume, because that is what the timestamp gap looked like from this side:start_time/end_timearrived on every delta and were thrown away.
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 pass --rate, --bits, --channel (and --codec) |
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
v3 spot measurements (verified 2026-09-16): 10s clip β 1.1s, 53s real-world clip β 2.6s (~20Γ RTF). v2.5-era baseline for reference (2026-04-23, same endpoint): 32K context window, ~85-101Γ RTF on 17.4 min audio, single-call ceiling β 30 min β treat 30 min as the working ceiling for v3 until re-probed, and re-measure before quoting long-audio numbers.
Common error patterns
| Error response | Actual cause | Fix |
|---|---|---|
| "model stepaudio-3-asr-max 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)
- Always pass through SSE β don't try to buffer the response with a non-streaming client. The model emits
transcript.text.deltafor long audio;transcript.text.donecarries the authoritative full text andusage. Reject the SSE format entirely and you'll get nothing. - Take final text from
transcript.text.done.textβ concatenated deltas can drift on edge cases. Deltas are for progressive UI; thedoneevent is the source of truth. - Handle
errorevents in the stream β don't treat the SSE stream as if only success events arrive. A blocked-content event mid-stream returnstype: errorwith nodoneevent.transcribe()'s return dict always carries anerrorslist of the raw error-event payloads (empty if none fired), even whenokisTrue, so a caller wanting the old strict semantics (any error event β failure) must checkerrorsitself. - 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 fromstep-asr-1.1.
Pricing (verified 2026-09-16, volatile)
stepaudio-3-asr-max: 2.8 ε
/ε°ζΆ (official model page, 2026-09-16). The older stepaudio-2.5-asr remains served on the same endpoint as a fallback. 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?").
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 β pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way β as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an emβ¦
design
149.0kComprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini, Atlas Cloud, or MuAPI AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVGβ¦
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit β see the Safety scan above for what the skill file itself contains.
