# 多个 clientKey：额度、IP 白名单和过期时间 > 一个 YesCaptcha 账户最多 20 个 clientKey，扣同一个账户余额；每个可以单独设消费额度（每天、每周、每月或一次性，按北京时间清零）、IP 白名单和过期时间，几秒内生效。 Source: https://docs.yescaptcha.com/zh/account/client-keys/ · Last verified: 2026-10-29 一个 YesCaptcha 账户最多可以有 20 个 `clientKey`（含原来的那个），在 [yescaptcha.com](https://yescaptcha.com/security) 后台的「密钥与安全」页面管理。每个 `clientKey` 都能创建任务、查询余额，扣的都是同一个账户余额；每个可以单独设消费额度、IP 白名单和过期时间，几秒内生效。 适合这些情况：测试环境和生产环境、不同项目分开用；分给下游客户或合作伙伴，各自限额；某个 `clientKey` 泄露了只删掉那一个，其他程序不受影响。 ## 主 Key 和子 Key | | 主 Key | 子 Key | | --- | --- | --- | | 是哪个 | 原来那个 `clientKey`，每个账户一个 | 在主 Key 之外新建的，最多 19 个 | | 额度、IP 白名单、过期时间 | 可以设 | 可以设 | | 重置 | 可以：旧的立即失效，余额转到新的 | 不能重置，删掉再建一个 | | 删除 | 不能 | 可以：几秒内失效，不能恢复 | - 格式都一样：前 40 位是密钥，后面是你的用户 ID。 - 重置主 Key 不影响子 Key。 - 用哪个 `clientKey` 创建任务、查询余额，接口和返回都一样，只多了额度、白名单、过期时间这几项检查。 ## 新建 clientKey 1. 登录 [yescaptcha.com](https://yescaptcha.com/)，打开「密钥与安全」页面（[yescaptcha.com/security](https://yescaptcha.com/security)）。 2. 在“全部 Key”里点“新建子 Key”。名称（最多 40 个字）、额度、IP 白名单、过期时间都可以不填，以后也能改。 3. 按提示再验证一次身份。新建、修改、删除都要验证。 4. 创建后复制完整的 `clientKey`，配置到程序里。以后也可以在列表里点眼睛图标再查看。 > **说明:** 新建、修改、删除都在几秒内生效。刚创建就调用，可能会返回 `ERROR_KEY_DOES_NOT_EXIST`，稍等几秒再试；删除或收紧设置后的几秒内，正在发出的请求可能仍按原来的设置处理。 ## 消费额度 额度限制一个 `clientKey` 在一个周期里最多能花多少点（1 元 = 1000 点），可以设 1 到 10,000,000,000 点。周期有四种，按北京时间（UTC+8）清零： | 周期 | 什么时候清零 | | --- | --- | | 每天 | 每天 0 点 | | 每周 | 每周一 0 点 | | 每月 | 每月 1 号 0 点 | | 一次性总额 | 不清零。用完以后这个 `clientKey` 就不能再创建任务，要继续用就调高额度 | - 按实际扣的点数算：识别失败、超时退回的点数，也会退回额度。 - 本周期剩下的额度不够这次任务的扣点时，`createTask` 返回 [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/zh/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED)，不扣点，不计入 [自动暂停](https://docs.yescaptcha.com/zh/api/rate-limits.md)。 - 后台的列表里能看到每个 `clientKey` 本周期已用多少、下次什么时候清零。 - 额度不是单独的余额：所有 `clientKey` 都扣同一个账户余额，账户余额不够时照常返回 `ERROR_ZERO_BALANCE`。 用设了额度的 `clientKey` 调 [`getBalance`](https://docs.yescaptcha.com/zh/api/get-balance.md)，`balance` 是账户余额和本周期剩余额度里较小的那个，另外多一个 `keyQuotaRemaining`（剩余额度，点）。没设额度的 `clientKey` 不带这个字段，返回和以前一样。 ```json { "errorId": 0, "balance": 20000, "softBalance": 0, "inviteBalance": 0, "inviteBy": 0, "keyQuotaRemaining": 20000 } ``` ## IP 白名单 设了 IP 白名单的 `clientKey`，只有从名单里的 IP 发出的请求能用。留空表示不限。 - 填 **调用 YesCaptcha 接口的机器的公网 IP**（出口 IP），不是任务参数里的代理。从多台机器调用的，每台的公网 IP 都要加进去。 - 每行一个 IPv4 或 IPv6 地址，或者 CIDR 网段，最多 50 条。单个地址就是只允许这一个 IP。 - 网段要写成网络地址：`203.0.113.0/24` 可以，`203.0.113.5/24` 不行（主机位不是 0）。 ```text 203.0.113.10 198.51.100.0/24 2001:db8::/32 ``` - 请求的 IP 不在名单里时，`createTask`、`getBalance` 返回 [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/zh/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED)，不扣点，不计入自动暂停。 - 出口 IP 会变的（家庭宽带、云函数、轮换的出口）不要设，或者设成整个网段。 ## 过期时间 - 任何 `clientKey`（包括主 Key）都可以设一个过期时间，要在十年以内；之后可以随时修改或去掉。 - 过期以后，用它调 `createTask`、`getBalance` 返回 [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/zh/api/errors.md#ERROR_KEY_EXPIRED)，不扣点。已经创建的任务照常可以用 `getTaskResult` 取结果。 - 长时间没有使用的 `clientKey`，系统会为保障账户安全给它设过期时间，到期前发邮件提醒。这种过期时间不能修改：请重新生成主 Key（余额自动转到新的），或者新建一个 `clientKey`，再更新到程序里。 ## 余额、并发限制和自动暂停 - **余额**：所有 `clientKey` 扣同一个账户余额。充值、VIP 赠送、邀请奖励、开发者分成都按账户算，和用哪个 `clientKey` 无关。 - **并发限制**：按账号算，所有 `clientKey` 合起来受同一个上限，见 [并发限制与自动暂停](https://docs.yescaptcha.com/zh/api/rate-limits.md)。 - **自动暂停**：按 `clientKey` 分开算，一个 `clientKey` 错误太多被暂停，不影响其他的。 ## 相关错误码 | 错误码 | 什么时候返回 | | --- | --- | | [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/zh/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | 本周期剩下的额度不够这次任务（`createTask`） | | [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/zh/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | 请求的 IP 不在这个 `clientKey` 的 IP 白名单里（`createTask`、`getBalance`） | | [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/zh/api/errors.md#ERROR_KEY_EXPIRED) | `clientKey` 已过期（`createTask`、`getBalance`） | 这三个都不扣点。处理办法见 [错误码](https://docs.yescaptcha.com/zh/api/errors.md)。