ElevenAPI 的 API 认证与密钥管理

API 认证用于服务验证传入请求是否有权限操作账户。例如，ElevenAPI 中，API 凭证可授权消耗计量额度、大规模生成语音和音乐，在部分场景下还可访问敏感音频。

密钥泄露会带来费用损失，还可能被用于在账户下生成内容。密钥权限过大还可能导致平台数据泄露等安全风险。早在 2020 年，超过 90% 的开发者每天至少用一次 API。如今，随着模型上下文协议（MCP）和 AI 的普及，API 已无处不在。

本文介绍如何正确进行 API 认证，以及如何在密钥全生命周期内进行管理，包括权限范围、轮换、组织管控、审计和应急响应。帮助团队规范 API 认证与密钥管理。阅读时可参考 认证参考文档 和 一次性令牌 参考文档。

要点总结

• ElevenAPI 通过唯一密钥 xi-api-key header 认证每个请求，持有密钥即可消耗额度并在账户下生成音频。
• 切勿将长期有效的 API 密钥放在浏览器、移动应用或任何用户可查看的地方。应只保存在你控制的服务器上。
• 客户端场景必须用服务器生成的短效一次性令牌认证，绝不能直接用长期密钥。
• 通过限制密钥权限、按环境分离密钥并定期轮换，可降低泄露风险和影响范围。
• 审计与异常检测有助于防止密钥泄露和意外风险。

什么是 API 认证？

API 认证用于服务在处理请求前，确认该请求是否有权限操作指定账户。请求方提交凭证，服务端验证后才会响应。

简单来说，就是判断：该请求是否有权操作此账户？注意，这与 API 授权不同，授权是指已认证请求在系统内可执行的具体操作。

什么是密钥管理？

密钥管理指的是对 API 密钥全生命周期的管理，包括创建、存储、使用、轮换和撤销等环节，确保密钥端到端的安全。

完善的密钥管理体系可防止密钥泄露，降低密钥被公开访问的风险。

API 密钥安全为何重要：威胁模型

明确认证和密钥管理后，需要具体了解密钥管理不当会带来哪些风险。先分析威胁模型，有助于后续每项实践都能有针对性地降低密钥泄露概率或影响。

ElevenAPI 仅通过 xi-api-key header 这一密钥机制认证。持有密钥即可获得全部权限，请求本身无二次验证。

持有密钥即可消耗额度。文本转语音、语音转文本、音乐、音效等均按量计费，攻击者可持续生成，直到额度或余额耗尽。

攻击者可大规模生成内容。我们的限流模型基于并发数，而非简单的每分钟请求数。某模型并发上限为 5 时，攻击者可并行滥用，实际影响远超预期。

攻击者可在账户下生成内容。用密钥生成的音频都归属你的工作区，涉及的音色和输入内容可能带来声誉甚至法律风险。

密钥泄露的方式很常见，与其他凭证泄露类似：

• 客户端代码中的 API 密钥： 密钥打包进浏览器、移动端或单页应用，实际上就是公开的。代码压缩并不能防止泄露。
• 代码仓库中的 API 密钥： 密钥硬编码进 Git，包括后续变为公开的私有仓库，或被广泛克隆的仓库，以及本不应被跟踪的 .env 等文件。
• 日志和追踪中的 API 密钥： 请求日志、错误追踪和可观测性管道常会捕获 HTTP header。xi-api-key 里的密钥可能进入日志、APM 平台，任何有读取权限的人都能看到。
• CI 和截图中的 API 密钥： 构建日志、工单、共享终端等场景。

下文每一节都对应降低上述某一风险的概率或影响。

核心原则：API 密钥只放在服务器端

本文其他内容都是降低 API 密钥认证与管理风险的建议，而这一原则是基础，必须优先落实。

由于机制简单，核心原则就是长期密钥只能存放在你控制的服务器上，绝不能出现在浏览器、移动端、桌面客户端或任何用户可下载查看的地方。若密钥出现在客户端代码，应视为已泄露。

SDK 会自动读取 ELEVENLABS_API_KEY，最简洁的做法是无需传递参数，初始化一次客户端即可。

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Reads process.env.ELEVENLABS_API_KEY when apiKey is omitted - never a literal.
const elevenlabs = new ElevenLabsClient();

const audio = await elevenlabs.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Generated entirely server-side.",
  modelId: "eleven_flash_v2_5",
  outputFormat: "mp3_44100_128",
});

生产环境应从密钥管理服务（如 AWS Secrets Manager、GCP Secret Manager、HashiCorp Vault 或平台自带服务）在进程启动时加载密钥，切勿写入镜像或提交到 .env 文件。

客户端应用的一次性令牌

核心原则必须遵守，但部分场景确实需要客户端直连 ElevenAPI：如浏览器播放流式文本转语音、移动端采集音频转写、用户标签下运行的实时智能体。长期密钥不能下发，解决方案是给客户端发放短效、一次性令牌，即使泄露也风险极低。

服务器持有长期密钥，先用自有会话逻辑认证和授权用户，再生成短效令牌，仅将该令牌下发给客户端。令牌很快过期，且仅限指定操作，泄露价值极低。具体支持的接口和请求格式见一次性令牌参考文档。

以下是代理端点的核心逻辑：用自有会话逻辑授权用户，然后向文档中的令牌端点申请令牌。请求用服务器的长期 xi-api-key，客户端只拿到短效令牌。

// ... express app and route boilerplate
app.post("/api/voice-token", async (req, res) => {
  // 1. Authorize the user with YOUR session/auth system first.
  if (!req.session?.user) return res.status(401).json({ error: "unauthorized" });

  // 2. Mint a short-lived token server-side. The long-lived key travels only
  //    in this server-to-server request, never to the browser.
  const response = await fetch("https://api.elevenlabs.io/v1/tokens", {
    method: "POST",
    headers: {
      "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}), // populate per the tokens reference
  });

  // 3. Return only the short-lived token. The API key never leaves the server.
  res.json({ token: await response.json() });
});

浏览器用该令牌连接，长期密钥不会进入页面。

最小权限原则下的密钥权限管理

最小权限原则要求每个密钥只具备完成任务所需的最小权限。ElevenAPI 支持多种基于权限的限制，可灵活控制密钥可用范围。

全权密钥风险最大，也是最常见的默认做法。更好的方式是假设任何密钥最终都会泄露，确保即使泄露也只能做本职工作。

首先限制密钥作用范围，只允许调用所需的 API。仅用于转写的密钥无需文本转语音 权限；音乐功能的密钥无需管理音色。

其次是额度限制。为每个密钥单独设置额度上限，可限制泄露带来的财务损失，也能防止代码异常导致额度耗尽。

IP 白名单进一步提升安全。可将密钥限定在指定 IP 或 CIDR 范围，非白名单 IP 的请求会被拒绝（403）。该功能为企业版预览，可联系客户经理开通。

最后，开发、测试、生产环境应分别使用不同密钥，各自独立设置权限和额度。这样即使开发环境密钥泄露，也不会影响生产额度，轮换时互不干扰，日志也能按来源区分。

API 密钥轮换

密钥轮换指定期用新密钥替换旧密钥，或在怀疑泄露时立即更换。

定期轮换可缩短密钥泄露后被滥用的窗口。只有代码支持轮换，过程才会顺畅，因此应提前设计好轮换机制。

核心做法是密钥重叠，确保无中断切换：

1. 生成新 API 密钥：新密钥与旧密钥并存，权限、额度、IP 限制一致，二者均有效。
2. 更新密钥：在密钥管理服务中更新密钥，实例自动加载（重启、重新读取或刷新密钥，视具体方案）。
3. 确认流量：确认新密钥已正常承载流量，观察旧密钥是否已无请求。
4. 移除旧密钥： 旧密钥在安全窗口内无流量后，立即撤销。

重叠期间两把密钥都有效，请求不会因凭证失效而失败。重叠还有助于发现配置错误的实例，因为它们会继续用旧密钥，便于及时排查。

为让轮换无感，建议将密钥读取逻辑集中，支持热更新，仅需切换配置即可，无需改代码。

// Rotation is driven by configuration, not code edits. The secret manager (or
// the deploy that injects env vars) is the single point of change.
// ELEVENLABS_KEY_ACTIVE selects which slot is live, enabling overlap.
let client: ElevenLabsClient | undefined;

function activeKey(): string {
  const slot = process.env.ELEVENLABS_KEY_ACTIVE ?? "primary";
  const name = slot === "primary" ? "ELEVENLABS_API_KEY_PRIMARY" : "ELEVENLABS_API_KEY_SECONDARY";
  return process.env[name] as string;
}

function getClient(): ElevenLabsClient {
  return (client ??= new ElevenLabsClient({ apiKey: activeKey() }));
}

// Call after a secret refresh to pick up the rotated key without a deploy.
function resetClient(): void {
  client = undefined;
}

重叠期间同时配置 PRIMARY 和 SECONDARY，切换 ELEVENLABS_KEY_ACTIVE 即可，应用代码无需变动。

建议后端密钥每 90 天常规轮换一次，高价值或高频密钥可更频繁，任何泄露时应立即轮换。可用定时任务自动完成生成、切换、验证和撤销，将轮换变为后台流程。

工作区访问控制与权限管理

权限范围和轮换保障单个密钥安全，工作区控制则决定谁有权生成密钥。可在此制定并执行组织级安全策略，影响后续所有密钥管理实践。

首先区分人和机器的凭证。人员用个人账户和权限登录控制台，服务用密钥或更优的服务账号认证。不要用个人密钥让服务运行，也不要多人共用同一机器密钥。这样便于人员离职或服务下线时，精准撤销对应凭证，避免误伤。

服务账号同样实现这一目标。它为机器任务分配独立身份和权限，确保审计记录真实可靠。

其次，建议按角色分配权限，而非逐个分配。工作区支持分组和成员权限。只授予每组完成工作所需的最小权限，定期检查成员，确保任何凭证（无论人还是机器）都不会超出职责范围。

审计与检测

前文介绍了如何降低泄露带来的损失，这一节介绍如何检测密钥是否已泄露。良好的检测依赖三项习惯：

第一，记录每个密钥（用标识符，不记录密钥值）服务的请求类型、来源和流量。务必在所有日志和追踪层面去除 xi-api-key header。HTTP 中间件和 APM 配置的脱敏规则可杜绝密钥进入日志。

第二，监控额度消耗异常。跟踪每个密钥的额度消耗，发现异常波动（如突增、异常时段生成、原本闲置的密钥突然活跃）及时告警。

第三，关注并发 header。每次响应都会返回当前和最大并发请求数（current-concurrent-requests 和 maximum-concurrent-requests）。可据此判断剩余空间，若长时间打满且非主动操作，极可能被滥用。直接用 HTTP 接口可查看这些 header：

const resp = await fetch("https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb", {
  method: "POST",
  headers: {
    "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Monitoring headroom.", model_id: "eleven_flash_v2_5" }),
});

const current = resp.headers.get("current-concurrent-requests");
const maximum = resp.headers.get("maximum-concurrent-requests");
// Emit these to your metrics pipeline; alert on sustained saturation you did not cause.

这些情况应触发告警。无人关注的看板无法实现检测。请将额度突增和并发打满的告警接入现有故障告警通道，并明确负责人。

应急响应

即使安全和监控措施做到极致，也要假设密钥最终可能泄露。提前制定应急步骤，可快速响应、降低损失。

API 密钥泄露应急流程如下：

1. 立即撤销泄露密钥： 不必等到完全查明情况。撤销密钥后无法再生成内容，且可随时补发新密钥。这是最关键的第一步。
2. 轮换新密钥： 若泄露密钥用于生产流量，按轮换流程反向操作：生成新密钥、切换流量、确认旧密钥失效。因代码从配置读取密钥，只需切换配置，无需改代码。
3. 分析日志评估影响范围： 泄露控制后，量化影响。密钥有效和暴露时长、期间消耗额度、流量是否异常、涉及哪些接口等。
4. 轮换相关密钥：密钥很少单独泄露。若是在仓库、日志或 CI 泄露，假设同位置的其他密钥也已暴露，一并轮换。
5. 修复泄露路径： 查明密钥如何泄露并彻底修复，否则还会重现：如将文件加入 .gitignore 并清理历史、日志加 header 脱敏、密钥移出构建产物、收紧 CI 权限等。
6. 撰写事后总结：记录时间线、影响范围、根本原因和已采取的具体措施（如收紧权限、IP 白名单、CI 密钥扫描、加快轮换等）。

按以上流程操作，可为 API 密钥泄露场景建立标准应急方案。

合规性：SOC 2、HIPAA 与数据保留

认证只是合规评估的一部分，具体能否满足合规要求需谨慎判断。以下内容仅供参考，具体适用性请结合自身场景确认。

ElevenLabs 已通过 SOC 2 认证。部分套餐和场景支持 HIPAA 合规和零数据保留模式。零保留即处理后不存储请求内容，适用于敏感输入或生成音频。

具体模式是否适用，取决于套餐、配置和处理内容。请在依赖前确认账户资格和具体条款，并结合上述访问控制措施。合规认证规范平台如何处理数据，密钥管理决定谁能代表你操作，后者需你自行负责。

良好的 API 密钥安全实践

仅服务器端存储密钥可最大限度减少泄露面。一次性令牌让真正需要访问 API 的客户端也能安全接入。权限和环境隔离可限制单次泄露的影响。配置化轮换让恢复变为日常操作。工作区权限区分人机身份。审计可将滥用变为告警而非账单意外。书面流程让应急响应有章可循。

这些做法与保护其他高价值凭证一致，区别在于此密钥直接关联费用和大规模音频生成。

准备实际接入时，可参考认证参考文档和一次性令牌参考文档，了解当前支持的接口。监控并发模型可参考模型参考文档和 API 快速入门。

保护 ElevenAPI 集成安全

强大的 API 认证是其他安全措施的基础。采用仅服务器端密钥、客户端一次性令牌、最小权限和内建轮换等措施，可大幅降低大规模风险。

更多支持接口和 header 格式说明，请参考 ElevenAPI 文档。如需开始集成，可申请 ElevenLabs API 密钥，立即开发。

API 认证与密钥管理常见问题