這裡提供完整的開發指南與最佳實踐，幫助您快速上手。
語音辨識
從本機音訊到 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。
把本機音訊轉成單行 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 字串，避免 shell 對特殊字元誤處理。
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 任一模式自由組合；未提供時套用預設值。前七列與文字翻譯端點共通，後三列為語音辨識專屬。
| 參數 | 型別 | 預設 | 說明 |
|---|---|---|---|
| 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 內帶 speaker 字母標識（"A" / "B" / "C"…），用於多人會議。 |
| processing_mode | "fast" | "balanced" | "balanced" | 語音辨識專屬。fast 速度較快，balanced 精度較高。長音訊或精度要求高時維持 balanced。 |
punctuation 的預設值兩端相反
搭配字庫
語音辨識端點接受兩種字庫，與文字翻譯端點相同: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 可用來確認字庫是否真的生效——這兩個欄位是語音辨識獨有，文字翻譯只有後者。
{
"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 }')"