一、这篇教程能解决什么

想下面三件事里的任意一件，可以直接照着敲：

1. 把文字变成中文配音：短视频口播、有声书、课件旁白，要能挑音色、调语速、指定语气
2. 把录音变成文字稿：会议、采访、播客，要能自动分清是谁说的
3. 让模型看图、听音频、看视频，然后用语音回答：多模态语音交互 demo

三件事用同一个命令行工具 bl 完成。本文命令签名全部以 bl 1.22.0 的 --help 实际输出为准，价格以 bl model list 的实时返回为准，音色清单以 --list-voices 实测输出为准，报错原文是真实终端输出。

二、环境准备

项目	要求	检查命令
Node.js	18.17 以上（走 npm 安装时需要）	node -v
阿里云账号	需实名认证才能使用付费能力	控制台查看
API Key	模型 API Key	bl auth status
播放器	macOS 自带 afplay；Windows/Linux 装 ffmpeg 用 ffplay	ffplay -version

三、安装与登录

3.1 三种安装方式，挑一种

方式一：npm（需要 Node.js 18.17+）

npm install -g bailian-cli
bl skill init

方式二：macOS / Linux 脚本（不用预装 Node，脚本会自动装 Bailian Skills）

curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash

方式三：Windows PowerShell

irm https://bailian.aliyun.com/cli/install.ps1 | iex

如果你在用 Coding Agent，也可以把这句话发给它：请阅读：https://bailian.aliyun.com/cli/install.md 并按照说明为我安装阿里云百炼 CLI

装完验证：

bl --version

输出类似 bl 1.22.0。安装说明页：https://bailian.console.aliyun.com/cli?source_channel=cli_github&

3.2 领取 API Key 并登录

API Key 在控制台创建：https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key

注意选华北2（北京）地域，新用户免费额度只在北京地域生效。

bl auth login --api-key sk-xxxxx
bl auth status

bl auth status 会打印当前 profile、配置文件路径、凭证状态。看到 API key 那行有值就成功了。

如果还要查用量、查额度（bl usage 系列命令是 Console 认证），再补一次浏览器登录：

bl auth login --console

3.3 先把免费额度规则搞清楚

按官方文档口径，别照抄第三方汇总文（网上流传的"100 万 Tokens 永久有效"是错的）：

• 每个符合条件的模型各自一份免费额度，通常 100 万 token
• 有效期 90 天，自开通百炼、模型发布、模型申请通过三者中较晚的算起
• 仅华北2（北京）地域，其他地域没有
• 过期自动失效，不补发、不延期、不重置，同一实名主体重新注册也拿不到第二次
• 一个模型用完，不会自动去用另一个模型的剩余额度
• 已认证账号额度用尽后自动转按量付费

不想让它自动扣费，开"用完即停"：

bl usage freetier --all
bl usage free
bl usage summary

开启后额度耗尽的调用返回 HTTP 403、错误码 AllocationQuota.FreeTierOnly。单独关某个模型：

bl usage freetier --model fun-asr --off

四、语音合成：文字变配音

4.1 第一步，列出可用音色（不花额度）

bl speech synthesize --list-voices --model cosyvoice-v3-flash

终端打出 64 个音色，四列：VOICE ID / NAME / DESCRIPTION / LANGUAGE，末尾一行 Total: 64 voices。分组如下：

类别	数量	代表音色 ID
中文/英文（含童声 4、台式 1）	36	longcheng_v3 龙橙（智慧青年男）、longhua_v3 龙华（元气甜美女）、longtian_v3 龙天（磁性理智男）、longwan_v3 龙婉（细腻柔声女）、longanyang 龙安洋（阳光大男孩）、longantai_v3 龙安台（嗲甜台湾女）
童声	4	longhuhu_v3（天真烂漫女童）、longpaopao_v3（飞天泡泡音）、longshanshan_v3（戏剧化童声）、longniuniu_v3（阳光男童声）
粤语	3	longjiaxin_v3（优雅粤语女）、longjiayi_v3（知性粤语女）、longanyue_v3（欢脱粤语男）
方言	3	longlaotie_v3（东北直率男）、longshange_v3（原味陕北男）、longanmin_v3（闽南清纯萝莉女）
美式英语	10	loongabby_v3、loongandy_v3、loongdavid_v3
英式英语	4	loongemily_v3、loongeric_v3、loongluna_v3、loongluca_v3
日语	5	loongriko_v3（Riko，二次元霓虹女）、loongtomoka_v3
韩语	2	loongkyong_v3、loongjihun_v3
印尼语	1	loongindah_v3

两个坑先提醒：

• longanyang 是这批里唯一不带 _v3 后缀的，别按规律给它补后缀
• 内置音色绑定模型。--model 的默认值取自你 profile 里配的 TTS 模型，没配才是 cosyvoice-v3-flash。建议每条命令都显式写 --model，原因见第十节报错 1

4.2 第二步，生成第一条配音

bl speech synthesize --model cosyvoice-v3-flash --text "欢迎收看本期节目，今天聊三个话题。" --voice longcheng_v3 --out demo.mp3

参数说明：

• --text：要合成的文字。长文本改用 --text-file script.txt
• --voice：音色 ID，从 4.1 的列表里复制
• --model：显式指定模型
• --out：输出路径。不写会自动生成到临时目录，终端会告诉你落在哪

4.3 第三步，调语速、音量、语气

bl speech synthesize --model cosyvoice-v3-flash --text-file script.txt --voice longhua_v3 --rate 0.9 --volume 60 --instruction "用温柔的语气，句尾放慢" --format wav --out chapter-01.wav

完整参数表（bl speech synthesize --help 原文口径）：

参数	取值范围	默认值	用途
--rate	0.5-2.0	1.0	语速。长文稿建议 0.9，短视频口播 1.0-1.1
--volume	0-100	50	音量
--pitch	0.5-2.0	1.0	音调
--seed	0-65535	无	固定随机种子，同输入产出同一条音频
--format	mp3/pcm/wav/opus	mp3（流式默认 pcm）	输出格式
--sample-rate	如 24000	模型默认	采样率
--language	zh/en/ja/ko/fr/de	无	语言提示，合成英文建议带上
--instruction	自然语言	无	风格指令，如"用温柔的语气"
--enable-ssml	开关	关	启用 SSML 标记解析
--concurrent	N	1	并行请求数，批量生产用
--stream	开关	关	裸 PCM 输出到 stdout

--instruction 是自由文本，同一段描述在不同音色上表现不一致，只能试听确认。

4.4 第四步，试听不落盘

挑音色时不要每条都写文件，用流式推给播放器：

bl speech synthesize --model cosyvoice-v3-flash --text "Hello, this is a test." --voice loongabby_v3 --language en --stream | afplay -

Linux / Windows（装了 ffmpeg）：

bl speech synthesize --model cosyvoice-v3-flash --text "Hello, this is a test." --voice loongabby_v3 --language en --stream | ffplay -nodisp -autoexit -f s16le -ar 24000 -ac 1 -

--stream 输出的是裸 PCM，必须接播放器或自己处理，直接重定向成 .mp3 打不开。-f s16le -ar 24000 -ac 1 要和实际采样率对齐，改了 --sample-rate 这里跟着改。

4.5 第五步，批量生产

bl speech synthesize --model cosyvoice-v3-flash --text-file chapter-02.txt --voice longcheng_v3 --rate 0.9 --seed 42 --concurrent 4 --out chapter-02.mp3

--seed 保证同一份文案两次生成结果一致，某一条不满意只重跑那一条。--concurrent 开并行，跑大批量前先查限流：

bl quota list
bl quota check

五、语音识别：录音变文字稿

5.1 基础转写

bl speech recognize --model fun-asr --url meeting.wav --out result.json

--url 这个名字有点误导，它同时接受网络 URL 和本地文件路径。--out 把完整结果写成 JSON。

5.2 自动区分说话人

bl speech recognize --model fun-asr --url meeting.wav --diarization --speaker-count 2 --out result.json

--diarization 开启说话人分离，--speaker-count 是预期人数。

必须带 --model fun-asr（或其他异步 filetrans 模型）。同步的 Flash ASR 不支持这两个参数，不带会在本地校验阶段被拦下，见第十节报错 2。--speaker-count 也依赖 --diarization，单写不生效。

5.3 多文件与长音频

bl speech recognize --model fun-asr --url a.mp3 --url b.mp3 --url c.mp3 --out all.json

--url 可重复，单次上限 100 个文件。长音频用异步，不在终端干等：

bl speech recognize --model fun-asr --url long.wav --async --quiet
bl speech recognize --model fun-asr --url long.wav --poll-interval 5

--poll-interval 默认 2 秒。

5.4 提升专有名词准确率

产品名、人名、内部术语容易错，挂热词表：

bl speech recognize --model fun-asr --url tech-talk.mp3 --vocabulary-id vocab-abc123 --out result.json

中英混合或方言内容加语言提示 --language zh。多声道音频用 --channel-id（默认 0）。

本地文件不方便公开托管时，先推到临时存储（48 小时有效）：

bl file upload ./local-audio.wav

六、多模态语音交互：看图听声，用语音回答

6.1 图片输入 + 语音输出

bl omni --message "user:这张封面图上最抢眼的是什么？一句话回答。" --image cover.jpg --voice Tina --audio-out reply.wav

一次调用完成视觉理解和语音合成，不用自己写"先调视觉模型、再把文字喂 TTS"的胶水代码。默认模型 qwen3.5-omni-plus。

6.2 Omni 的音色是另一套

bl omni --list-voices

一共 13 个，和 speech 那 64 个不通用，ID 首字母大写：

VOICE ID	名称	描述	语言
Tina	甜妹	甜美亲切	中文/英文（默认）
Dylan	北京-晓东	胡同少年	中文/北京
Kiki	粤语-阿清	甜美港妹	中文/英文
Li	南京-老李	南京大叔	中文/英文
Sunny	四川-晴儿	甜飒川妹	中文
Marcus	陕西-秦川	陕北汉子	中文/英文
Eric	四川-程川	成都大哥	中文/英文
Rocky	粤语-阿强	幽默港仔	中文/英文
Jennifer	詹妮弗	美剧大女主	中文/英文
Ryan	甜茶	美剧张力男	中文/英文
Katerina	卡捷琳娜	御姐深情女	中文/英文
Peter	天津-李彼得	天津捧哏	中文/英文
Ethan	晨煦	北方口音男	中文/英文

想让模型直接用方言回答，把要求写进 message 再配对应音色。--help 自带的例子：

bl omni --message "Answer in Sichuan dialect: How's the weather today?" --voice Sunny

6.3 音频、视频输入与多轮对话

bl omni --message "这段音频在说什么？" --audio ./record.m4a
bl omni --message "user:这段视频讲了什么？按时间顺序说三件事。" --video ./demo.mp4 --text-only

--audio 支持 .wav/.mp3/.amr/.aac/.m4a/.ogg/.3gp/.3gpp；--video 支持视频文件、URL，或逗号分隔的抽帧 URL。

多轮对话用重复的 --message 加 role: 前缀：

bl omni --system "你是一个四川话客服" --message "user:你们营业时间几点" --message "assistant:早上九点到晚上十点" --message "user:周末也开吗" --voice Sunny --audio-out reply.wav

6.4 --text-only 是最直接的成本开关

纯文本输出 ¥40/百万 token，文本加音频输出 ¥213/百万 token（此时输出的文本不再单独计费），差 5 倍多。调 prompt 阶段一律带 --text-only，逻辑对了再摘掉去要音频。

模型自述能力：超过 10 小时音频理解、400 秒 720P 音视频（1 FPS）理解与对话、60 多种语言音频输入、30 多种语言语音输出。纯转写别用它，走第五节的 fun-asr 更划算。

七、把三步串成流水线

7.1 写工作流 YAML

version: workflow/v1
steps:
  - id: script
    type: text/chat
    input:
      message: "{{topic}}"
      system: "你是短视频口播文案作者。只输出口播稿正文，120字以内，不要标题，不要解释。"
  - id: voiceover
    type: speech/synthesize
    input:
      text: "{{steps.script.output}}"
      model: cosyvoice-v3-flash
      voice: longcheng_v3
      rate: 0.95
      out: voiceover.mp3

{{topic}} 由运行时输入提供，{{steps.script.output}} 取上游步骤的产出。步骤类型共 11 种：text/chat、vision/describe、image/generate、image/edit、video/generate、speech/synthesize、speech/recognize、script/js、logic/switch、logic/select、logic/assert。

7.2 校验、干跑、真跑

bl pipeline validate --file voice-workflow.yaml

通过返回 Pipeline definition is valid.。文件必须走 --file，写位置参数会报 Unexpected argument。

bl pipeline run --file voice-workflow.yaml --input '{"topic":"本地语音克隆工具的中文短板"}' --dry-run

输出执行计划，不调模型、不花额度：

Pipeline planned [~]

  [~] script (text/chat) — planned
  [~] voiceover (speech/synthesize) — planned

确认没问题去掉 --dry-run 真跑：

bl pipeline run --file voice-workflow.yaml --input-file inputs.json --concurrency 3 --events events.jsonl --output json

--concurrency 控制并行步骤数（默认 1），--events 输出 JSONL 生命周期事件可接日志，--step-timeout 给单步设超时。bl pipeline run 标注 No Auth，命令本身不计费，计费的是它调起的步骤。

7.3 两个 schema 限制

script/js 的 code 必须是字面字符串，校验器拒绝从上游步骤取代码，报错理由是"会把不可信文本当宿主机代码执行"；沙箱内 input/steps/params 都是 undefined，code 里的 {{text}} 也不会被插值。要做数据加工别指望它。

logic/assert 的字段是 condition（表达式字符串），支持 {{steps.X.output}} 插值；写成 that/op/value 会报 condition is required。分支判断用 logic/assert 或 logic/switch。

八、费用怎么算

8.1 语音合成（按字符）

模型	单价	200 字口播	1 万字	12 万字
cosyvoice-v3.5-flash	¥0.8/万字符	¥0.016	¥0.8	¥9.6
cosyvoice-v3-flash	¥1/万字符	¥0.02	¥1	¥12
cosyvoice-v3.5-plus	¥1.5/万字符	¥0.03	¥1.5	¥18
cosyvoice-v3-plus	¥2/万字符	¥0.04	¥2	¥24
cosyvoice-clone-v1（声音复刻）	¥2/万字符	¥0.04	¥2	¥24
cosyvoice-v2 / cosyvoice-v1	¥2/万字符	¥0.04	¥2	¥24

注意 cosyvoice-v3.5-flash 虽然最便宜，但它不吃系统音色，--help 写明要传 clone 或 design 音色 ID。图便宜之前先确认手上有这类 ID。

查价命令（No Auth，不消耗额度）：

bl model list --capability TTS
bl model list --model cosyvoice-v3-flash

8.2 语音识别（按秒）

fun-asr 系列（含 fun-asr-mtl 和各日期快照版本）统一 ¥0.00022/秒：

时长	费用
10 分钟	¥0.132
1 小时	¥0.792
8 小时	¥6.336

批量转写排吞吐时注意 QPM 限制是 10。

8.3 多模态 Omni（按 token）

计费项	标准价（每百万 token）	Batch File
输入：文本/图片/视频	¥7	¥3.5
输入：音频	¥53	¥26.5
输出：纯文本	¥40	¥20
输出：文本+音频	¥213（输出文本不另计费）	同左

离线批量走 Batch File 约五折。

8.4 与海外订阅制的对比

ElevenLabs 官方 pricing 页当前档位：Free $0、Starter $6、Creator $22（首月 $11）、Pro $99、Scale $299（含 3 席）、Business $990（含 10 席）。计费单位是 credit，TTS 约 1 credit/字符，Speech to Text 330 credits/分钟。

按 1 美元 ≈ 7.1 人民币估算：

场景	bl 侧算式	bl 成本	ElevenLabs 对照
12.1 万字符配音	121,000 ÷ 10,000 × ¥1	¥12.1 ≈ $1.70	Creator $22/月的 121,000 credits 基本吃光
同上用 v3.5-flash	¥12.1 × 0.8	¥9.68 ≈ $1.36	同上
转写 1 小时	3600 × ¥0.00022	¥0.792 ≈ $0.11	60 × 330 = 19,800 credits，约 $3.60

订阅制的成本与用量脱钩，用量高且稳定、需要席位协作时更省心；用量低或波动大、按项目结算时，按字符和按秒更容易做成本归口。

本地开源方案（如 21.9k star 的 VoiceStudio）不产生调用费，代价是自备算力、自己从 16 个 TTS 引擎里选、自己核权重许可（默认引擎是 CC-BY-NC）。

九、成本治理命令速查

命令	用途
bl usage free	查各模型免费额度余量
bl usage summary	额度 + 近期用量统一视图
bl usage stats	模型用量统计
bl usage freetier --all	全部免费额度模型开启用完即停
bl usage freetier --model <m> --off	关闭指定模型的用完即停
bl quota list / bl quota check	查看与核对 QPM/TPM 限流
bl config show / bl config list	查看当前配置与 profile 列表
bl config set --key default_speech_model --value cosyvoice-v3-flash	固定默认 TTS 模型

十、常见报错与解决方案（终端原文）

报错 1：Engine error [411]: TTS speak operation failed

[Model: qwen-audio-3.0-tts-plus] [Voice: longcheng_v3]

Error:       [cosyvoice:]Engine error [411]: TTS speak operation failed
Status:      HTTP 400 (InvalidParameter)
Exit code:   1

原因：--model 的默认值来自 profile 里配置的 TTS 模型（这里是 qwen-audio-3.0-tts-plus），而 longcheng_v3 是 cosyvoice 系的内置音色 ID，两套对不上。换别的音色名重试同样是 411，说明不是单个 ID 写错。

排查：用 --dry-run 看实际请求体，不发起调用、不花额度：

bl speech synthesize --model cosyvoice-v3-flash --text "测试" --voice longcheng_v3 --dry-run
bl config show

解决（二选一）：

bl speech synthesize --model cosyvoice-v3-flash --text "..." --voice longcheng_v3 --out a.mp3
bl config set --key default_speech_model --value cosyvoice-v3-flash

报错 2：uses sync Flash ASR and does not support: --diarization, --speaker-count

Error:       Model "qwen-audio-3.0-asr-flash" uses sync Flash ASR and does not support: --diarization, --speaker-count.
Hint:        Use an async filetrans model (e.g. fun-asr, qwen3-asr-flash-filetrans) for those flags.
Exit code:   2

原因：说话人分离必须走异步 filetrans 模型，同步 Flash ASR 不支持。这是 CLI 的本地前置校验，请求没发出去就拦下了（零点三秒返回），不产生计费。

解决：按 Hint 补上模型名。

bl speech recognize --model fun-asr --url meeting.wav --diarization --speaker-count 2 --out result.json

报错 3：Unexpected argument（pipeline validate）

原因：bl pipeline validate 只接受 --file，不接受位置参数。

bl pipeline validate voice-workflow.yaml    # 错
bl pipeline validate --file voice-workflow.yaml    # 对

报错 4：Model "cosyvoice" not found.

bl model list --model cosyvoice
# Model "cosyvoice" not found.

原因：--model 要写完整模型名，不接受系列简称。

解决：先按能力筛出完整名字再查详情。

bl model list --capability TTS
bl model list --capability ASR
bl model list --model cosyvoice-v3-flash

报错 5：HTTP 403 AllocationQuota.FreeTierOnly

原因：开启了"用完即停"，且该模型免费额度已耗尽。这不是代码问题。

解决：

bl usage free
bl usage freetier --model cosyvoice-v3-flash --off

不想转按量付费就换一个还有额度的模型。

报错 6：--stream 没有声音

原因：--stream 输出裸 PCM，必须管道接播放器；或者 Windows 上没有 afplay。

解决：

bl speech synthesize --model cosyvoice-v3-flash --text "test" --voice longcheng_v3 --stream | afplay -
bl speech synthesize --model cosyvoice-v3-flash --text "test" --voice longcheng_v3 --stream | ffplay -nodisp -autoexit -f s16le -ar 24000 -ac 1 -

改了 --sample-rate，ffplay 的 -ar 要跟着改。

报错 7：Profile "xxx" does not support command "omni"

完整提示：

Profile "token-plan" does not support command "omni"; API Key settings will be read from Profile "default" for this run.

原因：这是 warning 不是 error，命令会继续跑，但改用 default profile 的 API Key。

解决：确认你要用哪个 profile。

bl config list
bl config use default
bl config show

Token Plan 类型的 key（sk-sp- 开头）走的是独立网关，不承载全部模型，语音类命令需要用标准 DashScope 的 API Key。

报错 8：bl: command not found

原因：npm 全局 bin 目录不在 PATH，或安装脚本没写入 shell 配置。

解决：

npm config get prefix
echo $PATH

确认 <prefix>/bin 在 PATH 里。不在就写进 shell 配置文件（zsh 用户写 ~/.zshrc），然后 source ~/.zshrc。用脚本装的检查 ~/.local/bin 是否在 PATH 中。

十一、FAQ

Q：一定要用命令行吗？
不一定。控制台有可视化界面，同一个模型也能直接用 SDK 调。CLI 的优势是能写进脚本、进 CI、和其他命令用管道串起来，还能用 bl pipeline 做多步编排。

Q：能克隆自己的声音吗？
能。cosyvoice-clone-v1 是声音复刻模型，¥2/万字符；cosyvoice-v3.5-flash（¥0.8/万字符）也接受 clone/design 音色 ID。音色 ID 在控制台侧生成，拿到之后在 CLI 里用。

Q：想微调一个专属 TTS 模型？

bl finetune audio create
bl finetune price
bl finetune watch --follow
bl deploy audio create

分别是创建 TTS 微调任务（sft-lora）、估算训练成本、跟踪任务、部署为可调用服务。bl deploy pause 可以在非使用时段停止计费。

Q：实时字幕能用吗？
说话人分离走的是异步 filetrans 模型，是任务制的，等结果这一步绕不开。低时延需求用同步 Flash ASR，但同步侧没有 --diarization。

Q：怎么知道花了多少钱？
bl usage stats 查用量统计，bl usage summary 看汇总，bl usage free 看免费额度剩余。

Q：合成音频能商用吗？
以服务条款和所用模型的说明为准。走本地开源方案时尤其要注意权重许可，比如 VoiceStudio 默认引擎的权重是 CC-BY-NC（非商用），应用本体是 AGPL-3.0。

十二、小结

三条核心命令，记住就能开工：

bl speech synthesize --model cosyvoice-v3-flash --text "你好" --voice longcheng_v3 --out a.mp3
bl speech recognize --model fun-asr --url a.mp3 --diarization --speaker-count 2 --out r.json
bl omni --message "user:描述这张图片" --image p.jpg --voice Tina --audio-out reply.wav

其余参数查 --help，音色查 --list-voices，价格查 bl model list，额度查 bl usage free，配置查 bl config show。报错先对照第十节，两个高频坑（音色与模型不匹配、说话人分离要异步模型）都有终端原文可对照。