stepfun-asr

StepFun stepaudio-3-asr-max

StepFun の stepaudio-3-asr-max（StepAudio 3、2026-09-15 リリース、2026-09-16 検証済み。従来の stepaudio-2.5-asr に代わる同一エンドポイントのモデル）で音声を書き起こします。チャンク分割せず、長い音声を1回の呼び出しで処理できます。ただし、正しいエンドポイントに正しい形式のリクエストボディを送信した場合に限ります。間違ったエンドポイントに送ると、「モデルが存在しない」というエラーと見分けがつかないエラーが返ります。これがこのスキルが必要とされる最大の理由です。

関連スキル：兄弟モデルの stepaudio-3-tts で TTS を行うには、stepfun-tts スキルを使用してください。API キーは共通ですが、エンドポイントとリクエストボディの形式は異なります。

このスキルが必要な理由 — 時間を浪費する3つの落とし穴

1. エンドポイントが違うと、異なるエラーが返る。stepaudio-3-asr-max は /v1/audio/transcriptions では利用できません（このエンドポイントは旧 step-asr ファミリー用です）。利用するのは /v1/audio/asr/sse です。SSE ストリーミング、JSON ボディ、Base64 エンコードされた音声を使用します。間違ったエンドポイントに送信すると、{"error":{"message":"model stepaudio-3-asr-max not supported"}} が返ります。これは、実際に存在しないモデル名を指定した場合と同じ構造のエラーです。ホワイトリスト登録の申請に何時間も費やす人が後を絶ちません。

2. Plan キーと Normal キーの違いによる、エラーのわかりにくい失敗。StepFun の「Plan」サブスクリプションキー（安価で、テキストのみ）は音声エンドポイントを呼び出せません。しかし、失敗しても認証エラーとわかるメッセージはなく、4xx エラーが返ります。アカウントに Plan サブスクリプションがある場合は、同じコンソールから別途「Normal」キーを取得する必要があります。

3. SSE のエラーイベントも実際に届く。ASR 側でも、まれに検閲が発生することがあります。transcript.text.delta と transcript.text.done イベントだけが届くと思い込まないでください。ストリーム内の type: error イベントも処理しないと、気づかないまま破棄してしまいます。

設定と認証

API キーは次の順序で解決されます（即時失敗し、デフォルト値はありません）。

1. $STEPFUN_API_KEY 環境変数
2. {"api_key": "..."} を含む ${CLAUDE_PLUGIN_DATA}/config.json（セッションをまたいで保持）

初回セットアップ：

mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<paste Normal key here>"}
EOF

ユーザーがキーを設定していない場合は、貼り付けてもらってください。推測したり、プレースホルダーを使用したりしないでください。キーは https://platform.stepfun.com/ → API Keys から取得できます。Plan キーではなく、Normal キーを使用してください。

クイックスタート — 単一ファイル

python3 scripts/asr_transcribe.py /path/to/audio.mp3

出力：標準出力にプレーンテキストの書き起こしが表示されます。

使用量と処理時間を含む、機械可読形式の出力を取得するには：

python3 scripts/asr_transcribe.py /path/to/audio.mp3 --json

中国語以外の音声の場合：

python3 scripts/asr_transcribe.py /path/to/audio.mp3 --language en

単語ごとのタイムスタンプにフラグは不要です。--json には常に segments が含まれます。

"segments": [{"text": "Understand ", "start_ms": 228, "end_ms": 1108}, ...]

単語ごとに1エントリーがあり、タイムスタンプは単調に増加します。サーバーはブロック単位でフラッシュするため、いくつかの単語には直前の単語と同じタイムスタンプが付くことがあります。特定の時点を探すには問題ありませんが、強制アラインメントには適しません。

旧モデルを使用するには：

python3 scripts/asr_transcribe.py /path/to/audio.mp3 --model stepaudio-2.5-asr

このスクリプトは、Base64 エンコード、ネストされた {audio: {data, input: {transcription, format}}} 形式のリクエストボディ、SSE の解析、誤解を招くエンドポイントの落とし穴に対応しています。より大規模なパイプラインに組み込む場合を除き、独自に HTTP 呼び出しを実装するよりも、このスクリプトの使用をおすすめします。

判断表

シナリオ	アクション
短いクリップ（< 5 min）、中国語または英語、mp3/wav/ogg/opus	python3 scripts/asr_transcribe.py audio.mp3
長い音声（5-30 min）	同じスクリプトを使用します — 32K コンテキストで1回の呼び出しで処理できるため、分割は不要です
30 min を超える音声	送信前に ffmpeg で分割します。API はサイズ超過のペイロードを拒否します
使用状況／請求データが必要	--json を追加して、transcript.text.done から usage.input_tokens ／ usage.total_tokens を取得します
各単語がいつ発話されたかを知りたい	--json を指定して、segments を読み取ります。デフォルトで有効です
話者ラベル（誰が何を言ったか）が必要	python3 scripts/asr_file.py <public-url> — 別の非同期エンドポイントです。ローカルファイルではなく URL を指定します：base64 も StepFun 独自のファイルストアも拒否されるため、取得可能な場所に音声をホストするかどうかは実行者が決めます
--model stepaudio-2-asr-pro が internal error を返す	このモデルは /v1/audio/asr/sse では使用できません（2026-09-18 に測定）。デフォルトまたは stepaudio-2.5-asr を使用してください
繰り返しの多いコンテンツ（同じフレーズを5回以上、90s 超）	step-asr-1.1 と相互検証します — references/known_issues.md の繰り返しによる幻覚を参照してください（2.5 時代の問題で、v3 では未検証です）
model stepaudio-3-asr-max not supported が表示される	エンドポイントが違います。/v1/audio/transcriptions から /v1/audio/asr/sse に切り替えてください
無言の 4xx 認証エラーが発生する	キーが「Plan」ではなく「Normal」であることを確認してください — Plan キーでは音声エンドポイントを呼び出せません
Python を使わずに生の HTTP を記述したい	正確な JSON 本文と SSE イベントの形式については、references/api_reference.md をお読みください

話者ラベル — scripts/asr_file.py

/v1/audio/asr/sse の stepaudio-3-asr-max には、話者の識別機能がまったくありません（候補となるリクエストフィールドを14個測定しましたが、どれも効果がありませんでした）。話者分離は非同期ファイルエンドポイントで行います。

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.

2026-09-18 に2人の話者のサンプルでエンドツーエンドの動作を検証しました。発話の境界は正しく、各発話内の単語ごとのタイムスタンプがあり、タスクごとに最大10人の話者を扱えます。stepaudio-2.5-asr を使用します — このエンドポイントでは v3 は提供されていません。

厳しい制約があります：URL のみを取得し、それ以外は受け付けません。 base64 も StepFun 独自の stepfile:// ファイルストアも拒否されるため、ファイルを取得可能な場所に公開しない限り、ローカルファイルを渡す方法はありません。この点は呼び出し側の判断事項としてください。references/known_issues.md に、行き止まりとなる3つの方法と、再試行／リダイレクトの動作を記載しています。

パラメーターは無料です — 1つも黙って省略しないでください

リクエストパラメーターを追加しても費用はかかりません。請求は音声の時間単位です。そのため、デフォルトでは有用なパラメーターをすべて送信し、送信しないフィールドにはすべて、scripts/asr_transcribe.py の先頭にある REQUEST_PARAMS に理由を明記する必要があります。

python3 scripts/check_params.py            # diff official field table vs REQUEST_PARAMS
python3 scripts/check_params.py --selftest # calibrate the check before trusting it

両方向に1つずつ、2つのガードがあります。

• リクエスト側 — check_params.py は公式のフィールド一覧を取得し、REQUEST_PARAMS に記載されていないフィールドがあれば失敗します。--selftest は両方向を検証します。実際のマニフェストが合格すること（誤検知がないこと）と、enable_timestamp を削除したマニフェストが検出されること（実際に起きた過去の見落としです — それまで参照していたのはレスポンスのフィールド一覧だけだったため、単語ごとのタイムスタンプが数か月にわたって欠落していました）。
• レスポンス側 — パーサーは、サーバーから送られてきても処理しないフィールドについて、unhandled_response_fields を報告します。こちら側から見たタイムスタンプの見落としも同じ状況でした。start_time ／ end_time はすべてのデルタで届いていたのに、破棄されていました。

対応する音声形式

スクリプトは拡張子から形式を自動判定します。上書きするには --format を指定してください。

拡張子	形式フラグ	備考
.mp3	mp3	最も一般的な形式で、デフォルトです
.wav	wav	可逆形式
.ogg	ogg	OGG コンテナー
.opus	ogg	OGG コンテナー内の Opus コーデック — 変更せずに渡します
.pcm	pcm	生の PCM — --rate、--bits、--channel（および --codec）も指定します

mp4/m4a/webm などの場合は、事前に ffmpeg で上記のいずれかの形式に変換してください。本番環境のパイプラインでは、base64 ペイロードのサイズを最小限に抑えるため、すべてのファイルを事前に OGG/Opus 16kHz モノラルに変換することがよくあります。

容量とパフォーマンス

v3 のスポット測定値（2026-09-16 確認済み）：10 秒のクリップ → 1.1 秒、実環境の 53 秒のクリップ → 2.6 秒（約 20 倍の RTF）。参考として、v2.5 時代のベースライン（2026-04-23、同じエンドポイント）：コンテキストウィンドウ 32K、17.4 分の音声で約 85～101 倍の RTF、1 回の呼び出しの上限は約 30 分です。v3 について再測定するまでは、実用上の上限を 30 分とし、長時間音声の数値を提示する前に再測定してください。

よくあるエラーパターン

エラーレスポンス	実際の原因	修正方法
/v1/audio/transcriptions で "model stepaudio-3-asr-max not supported"	エンドポイントが間違っています	/v1/audio/asr/sse に切り替えます（スクリプトが切り替えます）
認証に関するメッセージのない無言の 4xx	音声エンドポイントで「Plan」キーを使用しています	StepFun コンソールで「Normal」キーを取得します
ASR が予想の 3～4 倍の文字数を返す	繰り返しの多い音声で反復の幻覚が発生しています	step-asr-1.1 で相互検証します。references/known_issues.md を参照してください
ストリームの途中で data: {"type":"error","message":"content blocked..."}	ユーザーがアップロードしたコンテンツに対して検閲が作動しました	SSE の error イベントを明示的に処理します。delta／done だけが届くとは限りません

その他のエッジケースについては、references/known_issues.md を参照してください。

設計上の不変条件（変更しないでください）

1. 必ず SSE をそのまま通します — 非ストリーミングクライアントでレスポンスをバッファリングしようとしないでください。長い音声ではモデルが transcript.text.delta を出力し、transcript.text.done に確定した全文と usage が含まれます。SSE 形式を完全に拒否すると、何も取得できません。
2. 最終テキストは transcript.text.done.text から取得します — デルタを連結したテキストは、エッジケースでずれることがあります。デルタは UI の段階的な更新に使用し、正しい値としては done イベントを参照してください。
3. ストリーム内の error イベントを処理します — SSE ストリームには成功イベントしか届かないものとして扱わないでください。コンテンツブロックイベントがストリームの途中で発生すると、type: error が返され、done イベントは届きません。transcribe() の戻り値の辞書には、ok が True の場合も常に、エラーイベントの生のペイロードを格納した errors リストが含まれます（エラーが発生しなかった場合は空です）。従来の厳格な動作（エラーイベントがあれば失敗）を求める呼び出し元は、自身で errors を確認する必要があります。
4. API キーがない場合は即座に失敗させます — プレースホルダーや空文字列をデフォルト値として使用しないでください。スクリプトはこの動作を実装しているため、ラッパーでも維持してください。

リファレンスを読むタイミング

• references/api_reference.md — 正確な JSON リクエスト本文、すべてのフィールド、SSE イベントの全種類、レスポンス例を確認できます。付属のスクリプトを使わずに生の HTTP 呼び出しを記述する場合に読んでください。
• references/known_issues.md — 反復の幻覚の詳細、誤ったエンドポイントを特定する手順、Plan キーと Normal キーの注意点、ASR 側の検閲処理、価格の不透明さについて確認できます。異常な出力のデバッグや、step-asr-1.1 から移行すべきかの評価時に読んでください。

料金（2026-09-16 確認済み、変動あり）

stepaudio-3-asr-max：2.8 元／時間（公式モデルページ、2026-09-16）。旧版の stepaudio-2.5-asr も、フォールバックとして同じエンドポイントで引き続き提供されています。関係者に提示する前に、https://platform.stepfun.com/docs/zh/guides/pricing/details で再確認してください。

次のステップ

ASR の文字起こしには、ほとんどの場合、後続処理として 2 つのステップのいずれかが役立ちます。文字起こしの作成後、自然な次のスキルを提案してください。

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

ユーザーがすでに後続のツールを指定している場合や、文字起こしが明らかに単発の検索（例：「この 15 秒のクリップでは何と言っていますか？」）の場合は、提案を省略してください。