ElevenLabs CLI API Key 配置避坑

ElevenLabs 官方 CLI 的鉴权只认一样东西：API Key。把 Key 写进环境变量 ELEVENLABS_API_KEY、放进项目目录的 .env 文件，或用 --xi-api-key 临时传一次，三条路任选一条就能跑通。下面按建 Key、装 CLI、写 Key、验证四步走一遍，并把 401、403、429 这几个高频报错一起说清。

先确认你装的是官方 CLI

ElevenLabs 官方命令行工具包名是 @elevenlabs/cli，仓库在 github.com/elevenlabs/cli，由官方 OpenAPI 规格自动生成，底层是 Rust 二进制。npm 上的最新版本是 1.3.0，发布时间为 2026 年 9 月 15 日。

它主要做两件事：

1. 把 ElevenLabs 的每个 API 端点变成子命令，形式是 elevenlabs <资源> <方法>。
2. 提供 Agents as Code，把对话式 AI Agent 的配置放在本地 JSON 文件里，用 push 和 pull 与云端同步。

这里有个容易踩的坑：v1 和 v0 的命令语义变了。v0 里 agents list 显示的是本地配置，agents delete <id> 会顺手清理本地文件；到 v1，agents list 变成 API 侧的工作区列表，看本地要用 agents status，删远端要写 agents delete --agent-id <id>，而且它不会替你删本地配置文件。

还没装的话，先看ElevenLabs CLI 安装教程，装好再回来配 Key。

第 1 步：在后台新建 API Key

登录 ElevenLabs 后打开 API Keys 设置页，点新建即可。Key 分两类，先选对类型：

1. User API Key 属于个人，权限跟着人走，适合个人开发和脚本。
2. Service Account API Key 属于服务账号，适合后端系统和生产环境，多席位客户由工作区管理员管理。

创建时有三类限制可以配，建议一次配全：

1. Scope restriction，限制这把 Key 能访问哪些端点，只给需要的权限。
2. Credit quota，给这把 Key 设一个积分上限，防止脚本跑飞。
3. IP allowlisting，限定来源 IP 或 CIDR 段，非白名单 IP 的请求会被拒绝并返回 403。

个人 Key 还能设过期时间，从 15 分钟到 30 天任选，默认是永不过期。Key 一旦过期就停止鉴权，用它发出的请求会返回 401，所以在失效前改期或轮换。三类限制的官方说明见 API Keys 文档。

另外一个官方口径值得先确认：创建个人 API Key 需要 Full Seat 权限。如果你的工作区席位是受限席位，可能建不了 Key，需要找管理员调整。

第 2 步：安装 CLI

安装方式按平台挑一个，装下来的都是同一个二进制：

1. macOS 和 Linux 走 Homebrew：brew install elevenlabs/tap/elevenlabs。
2. Windows 走 Scoop：先 scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket，再 scoop install elevenlabs。
3. 跨平台走 npm：npm install -g @elevenlabs/cli，只想临时跑一次就用 npx @elevenlabs/cli <命令>。
4. 不想装包管理器也可以用官方安装脚本，macOS 和 Linux 用 curl，Windows 用 PowerShell。

装完执行 elevenlabs --help，能看到资源列表就说明装好了。想确认某个资源支持哪些方法，用 elevenlabs <资源> --help。

第 3 步：把 Key 交给 CLI，三种写法

这一步是全文重点，三种写法覆盖了绝大多数场景：

1. 环境变量：export ELEVENLABS_API_KEY=xi-...，写进 shell 配置后当前会话和后续命令都能用。
2. .env 文件：在工作目录建 .env，写入 ELEVENLABS_API_KEY=xi-...，CLI 会自动加载当前目录的 .env，适合一把 Key 只服务一个项目。
3. 单次传入：elevenlabs user get --xi-api-key xi-...，只在这一次命令里生效，适合临时排查或在 CI 里注入。

三种写法的取舍可以用一张表记住：

不管用哪种写法，请求头里带的都是 xi-api-key。所以直接用 curl 调也一样，例如 curl 'https://api.elevenlabs.io/v1/models' -H 'xi-api-key: $ELEVENLABS_API_KEY'，这个差异在API 和客户端的区别里有更细的说明。同一思路在其他语音类工具上也通用，例如Stable Audio 3.0 API Key 配置教程与调用示例。

第 4 步：验证 Key 是否生效

最省事的验证是查一下当前账号：

elevenlabs user get

返回账号信息就说明 Key 通了。更直观的办法是让 CLI 念一句话：

elevenlabs say "API Key 配置成功"

say 默认使用 eleven_v3 模型，也会调用本机播放器播放。如果机器上没有 ffplay、mpv 或 afplay，加上 --output out.mp3 直接落成音频文件即可。

对写脚本的人还有两个实用开关：加 --dry-run 只做本地校验并打印将要发出的 HTTP 请求，不真的发送；加 --format json 可以把输出交给 jq 处理，自动化检查会方便很多。

第 5 步：区域端点与网络设置

如果团队对数据落地区域有要求，CLI 支持切换区域，设置存在 ~/.elevenlabs/config.json，对所有命令生效：

切换用 elevenlabs residency eu-residency，临时覆盖可以用 --base-url 或环境变量 ELEVENLABS_BASE_URL。

网络方面，CLI 认 ELEVENLABS_PROXY、HTTPS_PROXY、HTTP_PROXY、NO_PROXY 等代理变量，也支持用 ELEVENLABS_TIMEOUT_SECS 调整超时。官方列出的区域里没有中国大陆节点，跨区域访问的延迟和稳定性建议自己用一次真实请求实测再决定。

常见报错速查

这套错误结构是统一的：响应体里带 type、code、message 和 request_id。完整列表见官方错误参考，报错时把 request_id 一起提供给客服或贴进工单，定位会快很多。想先搞清楚额度规则，可以看ElevenLabs CLI 免费额度有多少。