> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# API 密钥

## 概览

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

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

**API 密钥是机密信息。** 请勿与他人分享，也不要在客户端代码（浏览器、应用）中暴露。有关如何在请求中发送密钥，请参阅 [API 认证](/docs/zh/api-reference/authentication)参考文档。

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

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

## 可过期的用户 API 密钥

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

可在[个人 API 密钥设置](https://elevenlabs.io/app/settings/api-keys)中创建或编辑密钥时设置过期时间。使用 **Expire After** 选择器，选择从 15 分钟到 30 天的预设期限，或保留为 **Never**（默认）。**Expires** 列会显示每个密钥的失效时间。

密钥过期后将无法再进行认证，使用该密钥的请求会因 [`401` 错误](/docs/zh/eleven-api/resources/errors)被拒绝。可在密钥失效前编辑密钥以延长或清除过期时间；否则，请[轮换](#rotating-api-keys)为新密钥。

> **Note**
>
> 过期时间仅适用于用户 API 密钥。服务账户 API 密钥面向长期运行的后端
> 和生产工作负载，因此不会过期。

## 轮换 API 密钥

> **Info**
>
> 创建新 API 密钥来替换正在轮换的旧密钥时，请将旧密钥的权限复制到
> 新密钥，以免丢失访问权限。对于服务账户密钥，请确保为同一服务账户
> 创建新密钥。

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

**用户 API 密钥**可在控制面板中轮换。打开[个人 API 密钥设置](https://elevenlabs.io/app/settings/api-keys)，创建新密钥，切换完成后删除旧密钥。

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

* 在控制面板中，点击右上角的个人资料图标，选择 **Workspace settings**，然后打开 **Service Accounts** 标签页。为同一服务账户创建新密钥，切换完成后删除旧密钥。
* 通过 API，为同一服务账户[创建新密钥](/docs/zh/api-reference/service-accounts/api-keys/create)，然后[删除旧密钥](/docs/zh/api-reference/service-accounts/api-keys/delete)。

## IP 允许列表

可限制 API 密钥仅能从特定 IP 地址或 CIDR 范围使用。来自其他 IP 的请求会因 [`403` 错误](/docs/zh/eleven-api/resources/errors)被拒绝。

### 支持的格式

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

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

> **Note**
>
> 不接受私有 IP 范围（例如 `10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`）。仅
> 可将公共 IP 地址加入允许列表。

## 检测泄露的密钥

ElevenLabs 参与 [GitHub 的密钥扫描合作伙伴计划](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-partner-program)。如果 ElevenLabs API 密钥被提交到公开的 GitHub 仓库，GitHub 会通知 ElevenLabs，系统将自动禁用该密钥，以防止未经授权的使用。

以这种方式禁用的密钥会报告 `disable_reason` 为 `exposed_publicly`。要恢复访问权限，请[轮换密钥](#rotating-api-keys)并更新应用以使用新密钥。

> **Note**
>
> 仅当密钥允许第三方禁用时，才会自动禁用泄露的密钥。
> 请参阅[控制可禁用密钥的人员](#controlling-who-can-disable-keys)。

## 自行禁用密钥

如果认为密钥已泄露，密钥持有者可直接使用[禁用 API 密钥](/docs/zh/api-reference/api-keys/disable)端点将其禁用。调用时附加查询参数 `api_key_name=self`，为了安全起见，系统需要你明确确认：你是否真的要禁用掉当前用来证明你身份的这把密钥。

## 控制可禁用密钥的人员

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

> **Note**
>
> 当密钥由第三方禁用时，系统会向工作区所有者和密钥所有者发送通知邮件，
> 无论是通过 GitHub 密钥扫描自动禁用，还是通过自行禁用端点。自行在网页 UI 中
> 禁用密钥不会发送通知。

**单个密钥：** 在[创建](/docs/zh/api-reference/service-accounts/api-keys/create)或[更新](/docs/zh/api-reference/service-accounts/api-keys/update)服务账户 API 密钥时设置 `third_party_disable_allowed`。省略此项可使用工作区默认值，或在更新时传入 `clear`，将单个密钥重置为工作区默认值。

**整个工作区：** 工作区管理员可通过[设置工作区第三方禁用策略](/docs/zh/api-reference/api-keys/set-third-party-disabling-policy)端点，一次性覆盖所有密钥的设置：

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