想把 Breeze TTS 2 接进自己的程序里出声，绕不开 Developer Console 里那个 brz_ 开头的 API Key。对普通用户来说，官网网页版点几下就能出音频，但要批量生成、写进代码或者做实时对话，就得走 API 这条路。这篇教程按官方文档的顺序，把申请密钥、配置鉴权、装 SDK 跑通第一段合成语音串成一条线，每一步都有官方页面截图对照，跟着做大概十分钟就能听到结果。
先花一段带过背景。Breeze TTS 2 是 BreezeBlue 推出的新一代文本转语音模型，主打自然语言音色设计与低延迟流式生成，在第三方盲听评测中拿下开放权重模型第一，首字节延迟低至 40ms，单模型支持中英双语（官方模型页见 breezeblue.ai/zh/breeze-tts-2）。它既放出开放权重供研究使用，也提供官方托管的 API 服务；对多数开发者，托管 API 加官方 SDK 是最省事的路径。开工前只需准备一个 BreezeBlue 账号（邮箱注册或 Google 登录均可）和一台能跑 Python 的电脑。
Developer Console 里申请 API Key：四步拿到 brz_ 密钥
登录 breezeblue.ai 之后，点右上角的 Developer Console 进入开发者控制台，也可以直接打开官方 API keys 页面。整个申请流程只有四步。
第一步，在 API keys 页面点 Create API key 按钮；第二步，给密钥起个名字，建议按用途命名，比如 realtime、batch 这类一眼能认出来的名字；第三步，确认创建，系统生成一个 brz_ 开头的明文密钥；第四步，立刻复制保存。官方文档特别提醒，明文密钥只在创建时显示一次，之后无法再查看，要把它当成密码一样对待。
如果命令行用得多，官方 CLI 还提供 breeze login 命令，走一遍浏览器授权后会生成一把设备专属密钥，保存在 ~/.breeze 目录里，和手动创建的密钥是同一套管理模型。
两种鉴权方式：xi-api-key 与 Bearer 怎么选
密钥到手，下一步是让请求带上它。官方文档写得明确：同一个密钥支持两种等价的传法，一种是放进 xi-api-key 请求头，另一种是放进 Authorization: Bearer 请求头，两种写法效果完全一样，同时出现时 xi-api-key 优先生效。官方给出的 curl 示例如下：
curl https://api.breeze.blue/v1/voices \
-H "xi-api-key: $BREEZE_API_KEY"
curl https://api.breeze.blue/v1/voices \
-H "Authorization: Bearer $BREEZE_API_KEY"
实际用下来，GET /v1/voices 这类查询接口最适合当验密探针：请求头带对了就返回音色列表，带错了立刻收到 401。完整的鉴权说明见官方 Authentication 文档。
每账号 50 个密钥上限与单密钥 credit 预算
密钥管理有几个硬性规则值得记住。数量上，每个账号最多保留 50 个 API 密钥，停用的和 CLI 设备密钥都算在内，删掉不用的才能腾出新名额；轮换现有密钥属于原地替换，不额外占名额。每把密钥有稳定的 key_id、前缀和状态，状态分为 active、expiring、disabled 三种，被停用的密钥会立即返回 401 AUTH_REQUIRED，重新启用后即可恢复。
credit 预算是单密钥层面的用量闸门。每把密钥可以设置一个 credit 上限，默认是 Unlimited 不限制；设了上限之后，控制台会跟踪这把密钥的 Used、In flight、Remaining 三个数字。预算耗尽时，付费请求会返回 402 API_KEY_CREDIT_LIMIT_EXCEEDED，调高上限或重置用量后才能继续；把上限设成 0 则直接拦住所有付费生成，非计费接口不受影响。要注意重置用量只是开启新的预算周期，并不会返还或增加账户积分，密钥预算也不从账户里预留 credit。
想确认手头这把密钥还能不能用，可以调 GET /v1/api-keys/current 接口，它会返回当前密钥的状态以及 credit_limit、credit_used、credit_remaining 等字段。这是密钥管理接口里唯一用 API 密钥而非浏览器会话鉴权的一个，集成时可以拿来在开工前自检。
装上 SDK，合成第一段语音
万事俱备，跑通第一段语音只要三步。先安装官方 Python SDK：
pip install breeze-blue（用 uv 的话执行 uv add breeze-blue）
然后把密钥写进环境变量：
export BREEZE_API_KEY="brz_..."
最后用官方 quickstart 里的最小示例，原样照抄即可：
import os
from pathlib import Path
from breeze_blue import BreezeBlue, play, save
client = BreezeBlue(api_key=os.environ["BREEZE_API_KEY"])
audio = client.text_to_speech.convert(
voice_id="voc_xeh3w54cqvnp",
text="Hello from Breeze. Your SDK is ready.",
output_format="mp3",
)
play(audio)
save(audio, Path("hello.mp3"))
跑完这十来行，当前目录会多出一个 hello.mp3，这就是你的第一段合成语音。TypeScript 开发者把包换成 @breeze.blue/sdk（npm、pnpm、yarn 均可安装），接口一一对应，只是命名风格从 snake_case 换成 camelCase。完整步骤见官方 SDK quickstart 文档。
排查问题时别漏掉日志页（breezeblue.ai/app/developer/logs）：每次调用都能看到状态和延迟，还能一键 Copy as cURL，把失败的请求原样复制出来慢慢对比。
常见问题
- 密钥明文忘了保存怎么办？找不回来，明文只在创建或轮换时显示一次，只能删掉旧密钥重建一把，或者直接轮换。
- 报 402 API_KEY_CREDIT_LIMIT_EXCEEDED 是什么意思？这把密钥的 credit 预算用完了，去控制台调高上限或重置用量，别原样重试。
- 报 401 AUTH_REQUIRED 呢？密钥缺失、格式不对、被停用或已删除都会触发，先用 GET /v1/api-keys/current 查一下密钥状态。
- 流式输出想要 mp3 怎么办？流式默认返回 pcm 格式，想要别的格式要显式传 output_format 参数指定 wav 或 mp3。
- 50 个密钥名额用满了？删掉不再使用的旧密钥腾位置，轮换不占新名额。
总结
整套流程串下来并不复杂：控制台建密钥、环境变量配鉴权、pip 装包、十行代码出声。对普通用户来说，最容易踩的坑有两处，一是明文密钥只显示一次，养成创建即入库的习惯；二是单密钥 credit 预算，给不同用途的密钥分别设上限就能兜住意外开销。跑通最小示例之后，再按官方文档往流式输出和实时对话方向扩展，路子就很顺了。
