Stepfun Asr

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:

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

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

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 (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

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 API Reference

Exact request/response shapes for stepaudio-2.5-asr. Verified 2026-04-23 against the live StepFun API. Read this when calling the API by hand (curl, custom HTTP client) instead of using the bundled scripts/asr_transcribe.py.

Endpoint (NOT the one you'd guess)

POST https://api.stepfun.com/v1/audio/asr/sse
Content-Type: application/json
Accept: text/event-stream
Authorization: Bearer <STEPFUN_API_KEY>

Do NOT send stepaudio-2.5-asr to /v1/audio/transcriptions — that endpoint serves the older step-asr / step-asr-1.1 family and returns a misleading model stepaudio-2.5-asr not supported error which looks identical to a permission/whitelist error. See known_issues.md for the full diagnostic trail.

Request body

{
  "audio": {
    "data": "<base64-encoded audio bytes>",
    "input": {
      "transcription": {
        "language": "zh",
        "model": "stepaudio-2.5-asr",
        "enable_itn": true
      },
      "format": {
        "type": "mp3"
      }
    }
  }
}

Response — SSE stream

The response is a Server-Sent Events stream. Each line is either empty or starts with data: . Three event types:

data: {"type":"transcript.text.delta","meta":{...},"delta":"你好，"}

data: {"type":"transcript.text.delta","meta":{...},"delta":"我是蕾格。"}

data: {"type":"transcript.text.done","meta":{...},"text":"你好，我是蕾格。","usage":{"type":"tokens","input_tokens":69,"input_token_details":{"text_tokens":69,"audio_tokens":0},"output_tokens":9,"total_tokens":78}}

Capacity

• 32K context window
• Audio ≤ 30 min can be sent in a single call
• No client-side chunking needed for long audio (unlike step-asr)
• RTF 85-101× on Chinese speech verified 2026-04-23

Known error responses

{"error":{"message":"model stepaudio-2.5-asr not supported","type":"request_params_invalid"}}

→ Wrong endpoint. Switch from /v1/audio/transcriptions to /v1/audio/asr/sse.

data: {"type":"error","message":"content blocked ..."}

→ Content censorship (rare on ASR). Same triggers as TTS (death/disappearance/political terms).

Comparison with sibling and legacy endpoints

Legacy step-asr-1.1 is the fallback when stepaudio-2.5-asr hits the repetition-hallucination edge case (see known_issues.md). The endpoint and body shape are entirely different — multipart upload to /v1/audio/transcriptions, no SSE.

Auth and key handling

• Key header: Authorization: Bearer <key>
• Keys can be retrieved at https://platform.stepfun.com/ → API Keys
• "Plan" keys (cheaper subscription) are restricted to text models on api.stepfun.com/step_plan. They cannot call audio endpoints. Use a "Normal" key for ASR calls.
• Same key works for both TTS and ASR — no separate scopes

Rate / throughput notes (observed, not officially documented)

• Long audio ASR (17 min) has succeeded with timeout=1200 in the bundled script
• ~400ms sleep between sequential requests avoids 429s in batch processing
• Single TCP connection per request — SSE stream is closed after transcript.text.done

stepaudio-2.5-asr — Known Issues and Non-Obvious Behavior

Collected from end-to-end testing 2026-04-23. These are things that burned real time to discover; they are not in the official docs.

Wrong endpoint gives a misleading error (the #1 trap)

Symptom: Calling /v1/audio/transcriptions with model=stepaudio-2.5-asr:

{"error":{"message":"model stepaudio-2.5-asr not supported","type":"request_params_invalid"}}

This response is identical in structure to sending a genuinely nonexistent model name. It takes real debugging to realize the model exists but on a different endpoint.

Diagnostic sequence that wastes the least time:

1. Try step-asr on the same endpoint — if it works, endpoint access is fine 2. Check the /v1/audio/asr/sse endpoint (the actual stepaudio-2.5-asr home) 3. If both fail, THEN ask BD about whitelist

Don't assume "permission denied" on the first error.

ASR repetition hallucination (real, bounded)

Symptom: Transcribe a TTS-generated audio of highly-repetitive Chinese text (e.g., the same 60-char sentence repeated 10 times) and stepaudio-2.5-asr returns 3-4× the expected character count, with the same sentence restated many extra times in the output.

This is a genuine model hallucination, not a transport bug. Verified by:

1. MD5 diff — run1 vs run2 of the same TTS input produce different audio files (not file corruption) 2. Determinism — re-running ASR on the same audio gives the same 4× output every time (not transient noise) 3. Cross-validation — step-asr and step-asr-1.1 on the exact same audio return the correct character count (~800 chars for 800 input), so the audio itself is fine 4. ffprobe confirms audio duration is normal (~219s for 800 chars at typical speed)

Conclusion: The LLM-based ASR sees a repetitive pattern in the audio and "continues predicting" repetitions that aren't there.

When it triggers:

• Audio duration > 90s AND
• Content is highly repetitive (same phrase appearing 5+ times)

Doesn't trigger on real-world content:

• Podcasts, interviews, varied dialogue, stories — all fine
• Even 17.4-minute audio from 90 different TTS segments: returns correct 6332 chars, RTF 101×

Workaround for edge cases:

• If your domain has genuinely repetitive content (e.g., IVR transcripts, repeated sloganeering), cross-validate with step-asr-1.1 on random samples
• For most workflows: just use it; the hallucination mode is exotic

ASR speed scales non-linearly — short audio is a trap

Observation: The headline "5.9× faster than step-asr" from the marketing is true for long audio but misleading for short clips.

Why: The LLM + MTP-5 fusion overhead is amortized over longer contexts. Short requests pay the model-spin-up cost.

Practical implication: If your workload is many short (<10s) clips, the speedup over step-asr-1.1 is modest — 2× not 5×. If your workload is long audio (>2 min), the difference is dramatic and you should migrate.

"Plan key" vs "Normal key" — silent auth failure

StepFun sells a cheap "Plan" subscription for text models (step_plan endpoint). Plan keys cannot call audio endpoints. This silently manifests as 4xx errors that don't mention auth at all.

If you hit auth-shaped failures and your account has a Plan subscription, verify you're using a Normal key (different value, obtained separately in the StepFun console under the same "API Keys" page).

Censorship can fire on the ASR side too

Observed once (rare): An ASR request on a user-uploaded recording of political content returned:

data: {"type":"error","message":"content blocked ..."}

Handle the error event type in the SSE stream — don't assume only delta and done events fire. If your code only handles transcript.text.delta and transcript.text.done, a blocked-content event is silently dropped and the request appears to return empty text with no error surfaced to the caller.

The bundled scripts/asr_transcribe.py handles this correctly — see _consume_sse() for the pattern.

Pricing opacity

As of 2026-04-23, stepaudio-2.5-asr is in invitation beta. No public per-minute rate. step-asr-1.1 baseline is 2.2 元/小时. The invitation PDF mentions "成本直降 80%" implying roughly 0.4 元/小时, but this is not yet on the pricing page. Do not quote a price to a stakeholder without re-verifying at https://platform.stepfun.com/docs/zh/guides/pricing/details.

Empty transcript with no error

Symptom: SSE stream completes normally but transcript.text.done.text is empty string.

Possible causes: 1. Audio is silent / pure noise / corrupted 2. Audio language doesn't match the language parameter (e.g., sending English audio with language: zh) 3. Audio format mismatch (e.g., format.type: mp3 but actual bytes are wav)

The bundled script falls back to concatenating delta chunks if the done event has empty text — but if both are empty, the issue is upstream (the audio itself, not the API).

Long-audio timeout behavior

The default urllib/requests timeout is too short for 17+ minute audio. The bundled script uses timeout=1200 (20 minutes). If you write your own client, set the timeout to at least 2× expected wall clock time (RTF ~100× means 17 min audio takes ~10s wall clock, but TCP retries and network jitter can stretch this).