API 密钥

概述

API 密钥可对发送至 ElevenLabs API 的请求进行身份验证，并根据工作区配额跟踪用量。分为两种类型：

• 用户 API 密钥归属于个人用户，并继承该用户对工作区资源的访问权限。适合个人开发和脚本，可设置过期时间，使其在指定期限后自动失效。由于密钥与个人绑定，若该用户的访问权限变更或离开工作区，用户 API 密钥也会受到影响。创建个人 API 密钥需要 完整席位。
• 服务账户 API 密钥归属于服务账户，而非个人，因此无论个人成员资格如何变更，密钥都可继续使用。建议将其用于后端系统、自动化和生产工作负载。服务账户面向多席位客户提供，由工作区管理员管理。

API 密钥是机密信息。 请勿与他人分享，也不要在客户端代码（浏览器、应用）中暴露。有关如何在请求中发送密钥，请参阅 API 身份验证参考文档。

两类密钥均可通过多种方式限制：

1. 范围限制： 限制密钥可访问的 API 端点。
2. 积分配额： 设置自定义积分上限以控制用量。
3. IP 允许列表： 将密钥限制为特定 IP 地址或 CIDR 范围。请参阅 IP 允许列表。

可过期的用户 API 密钥

可为用户 API 密钥设置过期时间，使其在指定期限后自动失效。这可缩短泄露或遗忘的密钥可被使用的时间窗口，也符合绑定个人的密钥短期使用的特点。

可在个人 API 密钥设置中创建或编辑密钥时设置过期时间。使用 Expire After 选择器，选择从 15 分钟到 30 天的预设期限，或保留为 Never（默认）。Expires 列会显示每个密钥的失效时间。

密钥过期后将无法再进行身份验证，使用该密钥的请求会因 401 错误被拒绝。可在密钥失效前编辑密钥以延长或清除过期时间；否则，请轮换为新密钥。

轮换 API 密钥

两种情况下的轮换流程相同：创建新密钥，将应用切换至新密钥，然后删除旧密钥。

用户 API 密钥可在控制面板中轮换。打开个人 API 密钥设置，创建新密钥，切换完成后删除旧密钥。

服务账户 API 密钥可在控制面板或通过 API 轮换：

• 在控制面板中，点击右上角的个人资料图标，选择 Workspace settings，然后打开 Service Accounts 标签页。为同一服务账户创建新密钥，切换完成后删除旧密钥。
• 通过 API，为同一服务账户创建新密钥，然后删除旧密钥。

IP 允许列表

可限制 API 密钥仅能从特定 IP 地址或 CIDR 范围使用。来自其他 IP 的请求会因 403 错误被拒绝。

支持的格式

• 单个 IPv4 地址（例如 203.0.113.10）
• 单个 IPv6 地址（例如 2001:db8::1）
• CIDR 范围（例如 203.0.113.0/24）

每个 API 密钥可添加 1 到 100 个条目。不带掩码的 IP 地址会自动规范化为 /32（IPv4）或 /128（IPv6）。

检测泄露的密钥

ElevenLabs 参与 GitHub 的密钥扫描合作伙伴计划。如果 ElevenLabs API 密钥被提交到公开的 GitHub 仓库，GitHub 会通知 ElevenLabs，系统将自动禁用该密钥，以防止未经授权的使用。

以这种方式禁用的密钥会报告 disable_reason 为 exposed_publicly。要恢复访问权限，请轮换密钥并更新应用以使用新密钥。

自行禁用密钥

如果认为密钥已泄露，密钥持有者可直接使用禁用 API 密钥端点将其禁用。调用时附加查询参数 api_key_name=self，这是明确确认你打算禁用用于验证该请求的密钥所必需的。

控制可禁用密钥的人员

third_party_disable_allowed 设置控制密钥是否可由持有者禁用，包括通过自行禁用端点，或在密钥公开泄露时自动禁用。默认情况下，非企业版套餐启用此设置，企业版套餐则禁用。

单个密钥： 在创建或更新服务账户 API 密钥时设置 third_party_disable_allowed。省略此项可使用工作区默认值，或在更新时传入 clear，将单个密钥重置为工作区默认值。

整个工作区： 工作区管理员可通过设置工作区第三方禁用策略端点，一次性覆盖所有密钥的设置：

• true 允许工作区中的每个密钥由其持有者禁用。
• false 禁止所有密钥被禁用。
• null 移除工作区范围的覆盖设置，使每个密钥自身的值和套餐默认值重新生效。