계정

여러 clientKey: 한도, IP 허용 목록, 만료 시각

이 페이지는 중국어 버전을 기계 번역한 것이라 부정확한 내용이 있을 수 있어요. 중국어 버전을 기준으로 해 주세요.

YesCaptcha 계정 하나에는 clientKey를 최대 20개(기존 키 포함) 만들 수 있어요. yescaptcha.com 대시보드의 “키와 보안” 페이지에서 관리해요. 모든 clientKey로 작업을 만들고 잔액을 조회할 수 있고, 포인트는 모두 같은 계정 잔액에서 차감돼요. 각 clientKey마다 한도, IP 허용 목록, 만료 시각을 따로 설정할 수 있고, 몇 초 안에 적용돼요.

이런 경우에 쓰면 좋아요. 테스트 환경과 운영 환경, 또는 프로젝트별로 키를 나눠 쓸 때. 하위 고객이나 파트너에게 키를 나눠 주고 각자 한도를 둘 때. 어떤 clientKey가 유출돼도 그 키만 삭제하면 다른 프로그램은 영향을 받지 않아요.

기본 Key와 하위 Key

	기본 Key	하위 Key
어떤 키인가요	원래 쓰던 `clientKey`예요. 계정마다 하나예요	기본 Key 외에 새로 만든 키예요. 최대 19개예요
한도, IP 허용 목록, 만료 시각	설정할 수 있어요	설정할 수 있어요
재설정	가능해요. 기존 키는 즉시 사용할 수 없게 되고 잔액이 새 키로 옮겨져요	재설정할 수 없어요. 삭제하고 새로 만드세요
삭제	할 수 없어요	할 수 있어요. 몇 초 안에 사용할 수 없게 되고 복구할 수 없어요

형식은 모두 같아요. 앞 40자는 비밀 키이고, 뒤는 내 사용자 ID예요.
기본 Key를 재설정해도 하위 Key에는 영향이 없어요.
어떤 clientKey로 작업을 만들고 잔액을 조회하든 API와 응답은 같아요. 한도, 허용 목록, 만료 시각을 추가로 확인할 뿐이에요.

clientKey 만들기

yescaptcha.com에 로그인하고 “키와 보안” 페이지(yescaptcha.com/security)를 여세요.
“전체 Key”에서 “하위 Key 만들기”를 클릭하세요. 이름(최대 40자), 한도, IP 허용 목록, 만료 시각은 모두 비워 둘 수 있고, 나중에 바꿀 수도 있어요.
안내에 따라 본인 확인을 한 번 더 하세요. 만들기, 수정, 삭제 모두 본인 확인이 필요해요.
만든 뒤 전체 clientKey를 복사해서 프로그램에 설정하세요. 나중에 목록에서 눈 아이콘을 클릭해 다시 볼 수도 있어요.

사용 한도

한도는 clientKey 하나가 한 주기 동안 최대 몇 포인트까지 쓸 수 있는지를 제한해요(1,000포인트 = ¥1). 1에서 10,000,000,000포인트까지 설정할 수 있어요. 주기는 네 가지이고, 베이징 시간(UTC+8) 기준으로 초기화돼요.

주기	초기화 시점
매일	매일 0시
매주	매주 월요일 0시
매월	매월 1일 0시
1회성 총액	초기화되지 않아요. 다 쓰면 이 `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 API를 호출하는 머신의 공인 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가 바뀌는 환경(가정용 인터넷, 클라우드 함수, 순환하는 출구 IP)에서는 설정하지 않거나, 대역 전체를 허용하세요.

만료 시각

기본 Key를 포함해 어떤 clientKey든 10년 이내로 만료 시각을 설정할 수 있어요. 이후 언제든 수정하거나 없앨 수 있어요.
만료된 뒤에는 그 키로 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`)