Stepfun Asr

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 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-3-asr-max 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-3-asr-max not supported"}}, which is identical in structure to a genuinely nonexistent model name. People waste hours filing whitelist tickets.

1. 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.

1. 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:

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

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.py fetches the official field table and fails if it lists a field REQUEST_PARAMS does not mention. --selftest calibrates both ways: the real manifest must pass (no false alarms), and a manifest with enable_timestamp removed 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_fields for anything the server sends that it does not consume, because that is what the timestamp gap looked like from this side: start_time/end_time arrived on every delta and were thrown away.

Supported audio formats

The script auto-detects from extension; pass --format to override:

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