多个 clientKey：额度、IP 白名单和过期时间

一个 YesCaptcha 账户最多可以有 20 个 clientKey（含原来的那个），在 yescaptcha.com 后台的「密钥与安全」页面管理。每个 clientKey 都能创建任务、查询余额，扣的都是同一个账户余额；每个可以单独设消费额度、IP 白名单和过期时间，几秒内生效。

适合这些情况：测试环境和生产环境、不同项目分开用；分给下游客户或合作伙伴，各自限额；某个 clientKey 泄露了只删掉那一个，其他程序不受影响。

主 Key 和子 Key

	主 Key	子 Key
是哪个	原来那个 clientKey，每个账户一个	在主 Key 之外新建的，最多 19 个
额度、IP 白名单、过期时间	可以设	可以设
重置	可以：旧的立即失效，余额转到新的	不能重置，删掉再建一个
删除	不能	可以：几秒内失效，不能恢复

• 格式都一样：前 40 位是密钥，后面是你的用户 ID。
• 重置主 Key 不影响子 Key。
• 用哪个 clientKey 创建任务、查询余额，接口和返回都一样，只多了额度、白名单、过期时间这几项检查。

新建 clientKey

1. 登录 yescaptcha.com，打开「密钥与安全」页面（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，不扣点，不计入 自动暂停。
• 后台的列表里能看到每个 clientKey 本周期已用多少、下次什么时候清零。
• 额度不是单独的余额：所有 clientKey 都扣同一个账户余额，账户余额不够时照常返回 ERROR_ZERO_BALANCE。

用设了额度的 clientKey 调 getBalance，balance 是账户余额和本周期剩余额度里较小的那个，另外多一个 keyQuotaRemaining（剩余额度，点）。没设额度的 clientKey 不带这个字段，返回和以前一样。

{
  "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）。

203.0.113.10
198.51.100.0/24
2001:db8::/32

• 请求的 IP 不在名单里时，createTask、getBalance 返回 ERROR_KEY_IP_NOT_ALLOWED，不扣点，不计入自动暂停。
• 出口 IP 会变的（家庭宽带、云函数、轮换的出口）不要设，或者设成整个网段。

过期时间

• 任何 clientKey（包括主 Key）都可以设一个过期时间，要在十年以内；之后可以随时修改或去掉。
• 过期以后，用它调 createTask、getBalance 返回 ERROR_KEY_EXPIRED，不扣点。已经创建的任务照常可以用 getTaskResult 取结果。
• 长时间没有使用的 clientKey，系统会为保障账户安全给它设过期时间，到期前发邮件提醒。这种过期时间不能修改：请重新生成主 Key（余额自动转到新的），或者新建一个 clientKey，再更新到程序里。

余额、并发限制和自动暂停

• 余额：所有 clientKey 扣同一个账户余额。充值、VIP 赠送、邀请奖励、开发者分成都按账户算，和用哪个 clientKey 无关。
• 并发限制：按账号算，所有 clientKey 合起来受同一个上限，见 并发限制与自动暂停。
• 自动暂停：按 clientKey 分开算，一个 clientKey 错误太多被暂停，不影响其他的。

相关错误码

错误码	什么时候返回
ERROR_KEY_QUOTA_EXCEEDED	本周期剩下的额度不够这次任务（createTask）
ERROR_KEY_IP_NOT_ALLOWED	请求的 IP 不在这个 clientKey 的 IP 白名单里（createTask、getBalance）
ERROR_KEY_EXPIRED	clientKey 已过期（createTask、getBalance）

这三个都不扣点。处理办法见 错误码。