一條命令即可在終端機呼叫阿里雲百煉語音合成與識別能力，並管理熱詞詞彙表以提升識別準確率。
任意命令追加 --help 可查看完整參數說明，例如 bl speech synthesize --help。所有接受檔案 URL 的參數也接受本地路徑——CLI 會自動上傳到臨時儲存（有效期 48 小時），無需手動托管為 URL。本頁命令明細以 bl 2.2.1 為基準核實。
語音合成
bl speech synthesize
將文字合成為語音。需要 API Key 鑑權。
語法
bl speech synthesize --text <text> [flags]
| 參數 | 類型 | 必填 | 說明 |
|---|
--text <text> | string | 否 | 要合成為語音的文字（也可使用 --text-file） |
--text-file <path> | string | 否 | 從檔案讀取文字，而非使用 --text |
--model <model> | string | 否 | 模型 ID（預設：Profile 配置的 TTS 模型，否則為 cosyvoice-v3-flash）。系統音色因模型而異 |
--voice <voice> | string | 否 | 音色 ID。使用 --list-voices 查看所選模型的內建音色（如 qwen-audio-3.0-tts-plus/flash、cosyvoice-v3-flash）；使用 v3.5-flash 時需提供複製/設計音色 ID |
--list-voices | switch | 否 | 列出所選模型的內建系統音色並退出（輸出中會顯示控制台連結） |
--format <format> | string | 否 | 音頻格式：mp3、pcm、wav、opus（預設：mp3；串流模式預設：pcm） |
--sample-rate <rate> | string | 否 | 音頻採樣率，單位為 Hz（例如 24000） |
--volume <volume> | string | 否 | 音量 0–100（預設：50） |
--rate <rate> | string | 否 | 語速 0.5–2.0（預設：1.0） |
--pitch <pitch> | string | 否 | 音高倍數 0.5–2.0（預設：1.0） |
--seed <seed> | string | 否 | 用於重現合成結果的隨機種子 0–65535 |
--language <lang> | string | 否 | 語言提示（例如 zh、en、ja、ko、fr、de） |
--instruction <text> | string | 否 | 用於控制語音風格的自然語言指令（例如「使用溫柔的語氣」） |
--enable-ssml | switch | 否 | 解析輸入文字中的 SSML 標記 |
--out <path> | string | 否 | 將音頻儲存至檔案（預設：在臨時目錄中自動產生路徑） |
--stream | switch | 否 | 將原始 PCM 音頻串流輸出至 stdout（可透過管道傳給播放器） |
--concurrent <n> | number | 否 | 平行發送 N 個請求（預設：1） |
bl speech synthesize --list-voices --model qwen-audio-3.0-tts-plus
語音識別
bl speech recognize
識別音頻檔案中的語音（FunAudio-ASR / Qwen-ASR Flash）。需要 API Key 鑑權。
語法
bl speech recognize --url <audio-url> [flags]
| 參數 | 類型 | 必填 | 說明 |
|---|
--url <url> | array | 是 | 音頻檔案 URL 或本地檔案路徑（可重複，最多 100 個） |
--model <model> | string | 否 | 模型 ID（預設：Profile 配置的 ASR 模型，否則為 fun-asr）。非同步：fun-asr / -filetrans / paraformer-；同步：qwen3-asr-flash* / fun-asr-flash* / qwen-audio-*-asr-flash |
--language <lang> | string | 否 | 語言提示（例如 zh、en、ja）。傳統非同步/input-audio：language_hints；qwen3-filetrans：language；qwen3 同步：asr_options.language |
--diarization | switch | 否 | 啟用自動說話人分離 |
--speaker-count <n> | number | 否 | 預期的說話人數量（需啟用 --diarization） |
--vocabulary-id <id> | string | 否 | 預編譯熱詞清單 ID（可用 speech vocabulary create 建立）。其 target_model 必須與 --model 完全一致，否則靜默失效且無報錯。支援模型比 --vocabulary 更廣，含 Fun-ASR 與 Paraformer 系列 |
--vocabulary <json> | string | 否 | 即時熱詞，JSON 物件「熱詞→權重」，例如 '{"奮鬥者":4}'。權重 1-5（推薦 4，過高會拖累其他詞），50 表示超級熱詞。無需預先建立熱詞表。僅 Qwen-Audio-3.0-ASR-Flash 系列模型生效 |
--context <text> | string | 否 | 上下文增強詞表，提升專有名詞準確率；須包含待識別的原詞本身（只寫主題描述效果有限），最長 400 字元。僅 Qwen-Audio-3.0-ASR-Flash 系列與 Fun-ASR-Flash 模型生效 |
--channel-id <n> | number | 否 | 音頻音道 ID（預設：0） |
--out <path> | string | 否 | 將完整轉寫結果儲存至 JSON 檔案 |
--async | switch | 否 | 直接返回非同步任務 ID，不等待任務完成 |
--poll-interval <seconds> | number | 否 | 輪詢間隔，單位為秒（預設：2） |
bl speech recognize --url https://example.com/audio.mp3
熱詞詞彙表管理
管理可重複使用的預建構熱詞詞彙表，提升 ASR 對專有名詞的識別準確率。
bl speech vocabulary create
建立用於語音識別的預編譯熱詞表。需要 API Key 鑑權。
語法
bl speech vocabulary create --model <model> --prefix <prefix> (--words <json> | --words-file <path>) [flags]
| 參數 | 類型 | 必填 | 說明 |
|---|
--model <model> | string | 是 | 此熱詞表服務的 ASR 模型（必填）。必須與後續 speech recognize 的 --model 完全一致，否則熱詞表靜默失效 |
--prefix <prefix> | string | 是 | 熱詞表自訂前綴（必填）。僅允許數字和小寫字母，最長 10 個字元 |
--words <json> | string | 否 | 熱詞，JSON 物件「熱詞→權重」，例如 '{"奮鬥者":4}'；需要逐條指定語言時可傳 API 的項目陣列。權重 1-5（推薦 4）；當熱詞表的 target_model 為 Qwen-Audio-3.0-ASR-Flash 系列時還可使用 50（超級熱詞）。也可使用 --words-file |
--words-file <path> | string | 否 | 包含熱詞的 JSON 檔案（使用 - 從 stdin 讀取） |
--lang <code> | string | 否 | 物件形態時應用至所有熱詞的語言代碼（選填；陣列形態忽略）。Paraformer 支援 zh/en/ja/yue/ko/de/fr/ru；Fun-ASR 支援 zh/en/ja |
bl speech vocabulary create --model fun-asr --prefix demo --words '{"奋斗者":4,"鲸落":4}'
- --model 必須與後續
speech recognize --vocabulary-id 使用的 --model 完全一致；不一致時熱詞表會靜默失效且無報錯。
bl speech vocabulary list
列出預編譯熱詞表。需要 API Key 鑑權。
語法
bl speech vocabulary list [--prefix <prefix>] [--page <n>] [--page-size <n>]
| 參數 | 類型 | 必填 | 說明 |
|---|
--prefix <prefix> | string | 否 | 按熱詞表前綴過濾 |
--page <n> | number | 否 | 頁碼，從 1 開始（預設：1）。映射為 API 的 page_index（從 0 開始）：page - 1 |
--page-size <n> | number | 否 | 每頁結果數（預設：10） |
bl speech vocabulary list --prefix demo
- list 回應不含 target_model；要對齊模型請使用
speech vocabulary get。
- status 為 UNDEPLOYED 的熱詞表會被 ASR 靜默忽略。
bl speech vocabulary get
檢視預編譯熱詞表詳情。需要 API Key 鑑權。
語法
bl speech vocabulary get --id <id>
| 參數 | 類型 | 必填 | 說明 |
|---|
--id <id> | string | 是 | 熱詞表 ID |
bl speech vocabulary get --id vocab-demo-xxx
- 呼叫
speech recognize --vocabulary-id 前請用本命令確認 target_model；模型不一致會導致靜默失效。
bl speech vocabulary update
完全取代預編譯熱詞表的內容。需要 API Key 鑑權。
語法
bl speech vocabulary update --id <id> (--words <json> | --words-file <path>) [flags]
| 參數 | 類型 | 必填 | 說明 |
|---|
--id <id> | string | 是 | 熱詞表 ID |
--words <json> | string | 否 | 熱詞，JSON 物件「熱詞→權重」，例如 '{"奮鬥者":4}'；需要逐條指定語言時可傳 API 的項目陣列。權重 1-5（推薦 4）；當熱詞表的 target_model 為 Qwen-Audio-3.0-ASR-Flash 系列時還可使用 50（超級熱詞）。也可使用 --words-file |
--words-file <path> | string | 否 | 包含熱詞的 JSON 檔案（使用 - 從 stdin 讀取） |
--lang <code> | string | 否 | 物件形態時應用至所有熱詞的語言代碼（選填；陣列形態忽略）。Paraformer 支援 zh/en/ja/yue/ko/de/fr/ru；Fun-ASR 支援 zh/en/ja |
--yes | switch | 否 | 確認執行此高風險操作 |
該操作會完全取代熱詞表中的全部詞條。未列出的詞將被丟棄，且無法撤銷。
bl speech vocabulary update --id vocab-demo-xxx --words '{"奋斗者":4}' --dry-run
- update 是完全取代，不是增量追加。建議先用 --dry-run 預覽將要寫入的完整詞表。
bl speech vocabulary delete
刪除預編譯熱詞表。需要 API Key 鑑權。
語法
bl speech vocabulary delete --id <id>
| 參數 | 類型 | 必填 | 說明 |
|---|
--id <id> | string | 是 | 熱詞表 ID |
--yes | switch | 否 | 確認執行此高風險操作 |
bl speech vocabulary delete --id vocab-demo-xxx --dry-run
