包括的な開発者ガイドとベストプラクティスで、すばやく開発を始められます。
音声認識
ローカル音声の Base64 エンコードから JSON 一括結果取得、タイムスタンプと字幕、SSE 逐次配信まで、音声認識の実戦フローをまとめます。
本チュートリアルは POST /api/v1/audio/transcriptions を軸に進めます。本エンドポイントは Base64 エンコード済み音声バイトを受け取り、プレーンテキストと任意のタイムスタンプを返します。SSE による逐次配信にも対応します。
ステップ 1:音声データを準備する
音声を読み込み Base64 へエンコードします。data:audio/...;base64, プレフィックスは必ず除去してください。エンドポイントは生の Base64 文字列のみを受け付けます。サーバは音声の実際の内容から形式を自動検出するため拡張子は無関係ですが、内容は対応形式のいずれかである必要があります。
- 対応形式：MP3、WAV、M4A、FLAC、OGG、WEBM。
- JSON（Base64）経路は raw 音声 ≤ 1 MB。超過時は 413 audio_too_long。
- 1 MB を超える音声は multipart/form-data で元ファイルをアップロード（≤ 15 MB）：`params` JSON フィールド（本チュートリアルのパラメータから audio_data を除いたもの）は `audio` ファイルフィールドより先に送信必須。詳細は API リファレンスの ASR エンドポイントを参照。
- 形式検出失敗は 422 unsupported_audio_format、デコード失敗は 422 asr_audio_decode_error。
ローカル音声を 1 行の Base64 文字列に変換します。base64 -w 0 で改行を抑止します。
# Encode a local audio file (no line wrapping)
AUDIO_B64=$(base64 -w 0 ./meeting.mp3)
echo "$AUDIO_B64" | head -c 80
# Output (truncated): SUQzBAAAAAACSlBNTAAA...ステップ 2：JSON モードでリクエストを送る
既定の stream=false では認識完了を待って結果を一括返却します。language には言語コードまたは "auto"（モデル自動検出）を指定。punctuation は既定 true で、認識結果に句読点を自動補完します。
JSON モード curl：jq で Base64 文字列を注入し、シェルによる特殊文字の取り違えを防ぎます。
curl -X POST "https://abemono.abestar.com.tw/api/v1/audio/transcriptions" \ -H "X-API-Key: $ABESTAR_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg a "$AUDIO_B64" '{ audio_data: $a, language: "zh-TW", timestamp_format: "json", diarization: true }')"
成功応答例（HTTP 200）。timestamp_format="json" では segments、srt / webvtt では timestamps 文字列に充填されます。
{
"text": "今天的會議改到下午三點。",
"detected_language": "zh-TW",
"segments": [
{
"id": 0,
"start": 0.0,
"end": 2.4,
"text": "今天的會議改到下午三點。",
"speaker": "A"
}
],
"timestamps": null,
"usage": {
"quota_percent": {
"used": 35
}
},
"forced_replacement_count": 0,
"vocabulary_used": false
}追加機能パラメータ
以下のパラメータはすべて任意で、JSON / SSE いずれのモードとも自由に組み合わせられます。省略時は既定値が適用されます。上位 7 行はテキスト翻訳エンドポイントと共通、下位 3 行は音声認識専用です。
| パラメータ | 型 | 既定値 | 説明 |
|---|---|---|---|
| model | string | "tranc-std-v1" | 認識モデルコード。利用可能な一覧は GET /audio/models で取得できます。 |
| domain | string | "general" | 内容領域のヒント（"medical" / "legal" / "finance" など）。専門用語の認識を補助します。 |
| context | { speech: string }[] | [] | 場面背景や先行対話の補足を時系列順で渡します。 |
| harm_content_filter | boolean | false | 有害コンテンツフィルタを有効化します。拒否時は 400 asr_content_policy_violation。 |
| punctuation | boolean | true | 認識テキストの句読点を自動補完します。既定は true で、テキスト翻訳エンドポイントの false とは逆です。 |
| number_format | "spoken" | "arabic" | "spoken" | 数字の書き起こし方式：spoken は口語表記、arabic はアラビア数字（1234）。 |
| date_format | "natural" | "yyyy-MM-dd" | "yyyy/MM/dd" | "MM/dd/yyyy" | "dd-MM-yyyy" | "natural" | 日付の表現方式：natural は言語慣例に従い、その他は固定テンプレートです。 |
| timestamp_format | "json" | "srt" | "webvtt" | 省略時は出力しない | 音声認識専用。"json" は構造化された segments、"srt" / "webvtt" は字幕文字列をそのまま返します。 |
| diarization | boolean | false | 音声認識専用。true で segments に話者ラベル（"A" / "B" / "C"…）が付き、複数話者の会議に使えます。 |
| processing_mode | "fast" | "balanced" | "balanced" | 音声認識専用。fast は高速、balanced は高精度。長尺音声や精度重視の場面では balanced を維持します。 |
punctuation の既定値は両エンドポイントで逆
辞書を併用する
音声認識エンドポイントはテキスト翻訳と同じ 2 種類の辞書を受け付けます。vocabulary はソフトヒントで、一致した語彙が好適語としてモデルに渡されるため、人名・製品名・専門用語に適します。forced_replacement は後処理置換で、認識完了後に出力へ文字列置換を適用します。どちらも UUID を vocabulary_dictionary_id / forced_replacement_dictionary_id に指定します。
JSON モードでは両方の辞書を同時に指定できます。language は明示的な言語コードである必要があり、auto は使用できません。
curl -X POST "https://abemono.abestar.com.tw/api/v1/audio/transcriptions" \ -H "X-API-Key: $ABESTAR_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg a "$AUDIO_B64" '{ audio_data: $a, language: "zh-TW", vocabulary_dictionary_id: "f3c1e9a2-9c2b-4f7a-9d3a-7e2b8a1c4d5e", forced_replacement_dictionary_id: "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a" }')"
応答の vocabulary_used と forced_replacement_count で辞書が実際に効いたか確認できます。この 2 つは音声認識固有で、テキスト翻訳には後者のみがあります。
{
"text": "請把這份合約交給法務組長確認。",
"detected_language": "zh-TW",
"segments": null,
"timestamps": null,
"usage": {
"quota_percent": {
"used": 35
}
},
"forced_replacement_count": 2,
"vocabulary_used": true
}vocabulary 辞書は language: "auto" と併用不可
辞書の作成と詳細
SSE モード：逐次出力
リアルタイム字幕や逐次表示が必要な場合は stream=true を指定し、応答を text/event-stream へ切り替えます。イベント順序は head（detected_language）→ chunk*（テキスト片、0〜複数件）→ tail（任意で segments）→ meta（usage / vocabulary_used / forced_replacement_count）。失敗時は任意の時点で error イベントが残りを置換し、ストリームを終了します。
SSE モードの curl 例。-N で curl のバッファリングを無効化し、イベントを逐次出力します。
curl -N -X POST "https://abemono.abestar.com.tw/api/v1/audio/transcriptions" \ -H "X-API-Key: $ABESTAR_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg a "$AUDIO_B64" '{ audio_data: $a, language: "auto", stream: true }')"