# YesCaptcha Docs (full text)
> YesCaptcha는 캡차 인식 API예요. JSON 인터페이스 하나로 reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF, 이미지 캡차를 인식하고, 작업별로 포인트를 차감해요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.
---
# JSON 인터페이스 하나로 캡차를 인식하세요
> YesCaptcha는 캡차 인식 API예요. JSON 인터페이스 하나로 reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF, 이미지 캡차를 인식하고, 작업별로 포인트를 차감해요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.
Source: https://docs.yescaptcha.com/ko/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/
[캡차 인식 API서비스 상태](https://status.yescaptcha.com/?lang=en)
reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF, 이미지 영숫자 캡차를 인식해요. 작업별로 포인트를 차감하며, 1,000 포인트 = ¥1이에요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.
[빠른 시작](https://docs.yescaptcha.com/ko/getting-started/quickstart.md)[API 레퍼런스](https://docs.yescaptcha.com/ko/api/overview.md)
AI와 프로그램을 위한 버전:[llms.txt](https://docs.yescaptcha.com/ko/llms.txt)[llms-full.txt](https://docs.yescaptcha.com/ko/llms-full.txt)[OpenAPI](https://docs.yescaptcha.com/openapi.json)[Markdown](https://docs.yescaptcha.com/ko/index.md)
YesCaptcha는 합법적인 용도로만 사용할 수 있어요. 불법적인 용도로 사용하는 것은 금지돼요.
POSTapi.yescaptcha.com/createTask
```
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
1. /createTasktaskId 61138bb6-19fb-11ec-a9c8-0242ac110006
2. /getTaskResultprocessing
3. /getTaskResultprocessing
4. /getTaskResultready
5. gRecaptchaResponse03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU...
1. 1작업 생성
2. 2결과 가져오기
3. 3제출
예시: reCAPTCHA v2, 5초마다 결과를 폴링해요
$0.30 / 1k부터
작업당 최저 단가
1,000 포인트 = ¥1
실패하거나 시간 초과된 작업은 포인트가 환불돼요
엔드포인트 2개
글로벌 엔드포인트와 중국 엔드포인트
9:00–21:00
상담원 지원 (UTC+8)
[빠른 시작회원가입 후 clientKey를 받아 5분 안에 첫 요청을 보내요](https://docs.yescaptcha.com/ko/getting-started/quickstart.md)[API 레퍼런스createTask, getTaskResult, 오류 코드, 동시 작업 수 제한](https://docs.yescaptcha.com/ko/api/overview.md)[작업 유형과 가격공개된 모든 유형의 가격, 반환 방식, 파라미터](https://docs.yescaptcha.com/ko/tasks.md)[브라우저 확장 프로그램코드 없이 웹 페이지에서 자동으로 인증을 완료해요](https://docs.yescaptcha.com/ko/extension.md)
## 지원하는 캡차
[01reCAPTCHAv2, v3, 엔터프라이즈 버전, v2 이미지 인식$0.90 / 1k부터](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md)[02hCaptcha토큰을 반환하거나, 이미지를 인식한 뒤 직접 클릭해요$1.20 / 1k부터](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md)[03Cloudflare TurnstileTurnstile 인증 토큰$3.75 / 1k부터](https://docs.yescaptcha.com/ko/tasks/turnstile.md)[04FunCaptchaArkose Labs의 이미지 문제 인식, 모든 문제 유형 지원$0.45 / 1k부터](https://docs.yescaptcha.com/ko/tasks/funcaptcha-classification.md)[05AWS WAF / bCaptcha3×3 그리드 이미지 인식$1.20 / 1k부터](https://docs.yescaptcha.com/ko/tasks/aws-bcaptcha-classification.md)[06이미지 영숫자일반 문자 캡차, 동기 방식으로 반환$0.30 / 1k부터](https://docs.yescaptcha.com/ko/tasks/image-to-text.md)
## 세 단계로 연동
1. 01
**작업 만들기**
`createTask`로 작업 유형과 사이트 파라미터를 제출하면 `taskId`를 받아요. 이미지 인식, 이미지 영숫자 같은 동기 유형은 결과를 바로 반환해요.
2. 02
**결과 받기**
5초마다 `getTaskResult`를 호출하세요. `status`가 `ready`가 되면 결과는 `solution`에 들어 있어요.
3. 03
**대상 사이트에 제출하기**
받은 토큰을 웹 페이지의 폼이나 요청에 넣으세요. 토큰은 한 번만 사용할 수 있으니 60초 안에 사용하는 것을 권장해요.
POST /createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
POST /getTaskResult
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
## 자주 찾는 페이지
- [**오류 코드**각 오류 코드의 의미와 처리 방법](https://docs.yescaptcha.com/ko/api/errors.md)
- [**동시 작업 수 제한과 자동 일시 중지**한도를 넘거나 오류가 너무 많을 때 일어나는 일](https://docs.yescaptcha.com/ko/api/rate-limits.md)
- [**과금과 포인트 환불**포인트, 선차감, 포인트 환불, 신고 후 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)
- [**문의하기**WeChat, QQ, Telegram, 이메일, 서비스 시간 9:00–21:00(UTC+8)](https://docs.yescaptcha.com/ko/help/contact.md)
- [**대시보드**회원가입, clientKey 확인, 충전](https://yescaptcha.com/)
---
# 소개
> YesCaptcha가 무엇인지 설명해요. API나 브라우저 확장 프로그램으로 reCAPTCHA, hCaptcha, Turnstile, FunCaptcha, 이미지 캡차를 인식하고, 작업마다 포인트를 차감하며, 실패한 작업은 자동으로 포인트를 환불해요.
Source: https://docs.yescaptcha.com/ko/getting-started/introduction/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/getting-started/introduction/
YesCaptcha는 캡차 인식 서비스예요. 캡차 정보를 YesCaptcha API로 보내면 대상 웹사이트에 바로 제출할 수 있는 토큰이나 이미지 인식 결과를 돌려받아요. reCAPTCHA(v2, v3, Enterprise), hCaptcha, Cloudflare Turnstile, Cloudflare 챌린지 페이지, FunCaptcha, AWS WAF, bCaptcha, 이미지 영숫자 캡차를 지원해요. 작업마다 포인트가 차감되며, 1,000 포인트 = ¥1이에요. 인식에 실패하거나 시간이 초과된 작업은 자동으로 포인트가 환불돼요.
YesCaptcha는 합법적인 용도로만 사용할 수 있어요. 불법적인 용도로 사용하는 것은 금지돼요.
## 두 가지 사용 방법
| | API | 브라우저 확장 프로그램(YesCaptcha Assistant) |
| --- | --- | --- |
| 적합한 사용자 | 코드를 작성할 수 있고 프로그램에서 대량으로 처리하려는 개발자 | 코드를 작성하지 않고 브라우저에서 사용하려는 사용자 |
| 사용 방법 | `clientKey`로 `createTask`, `getTaskResult`를 호출해요 | 확장 프로그램을 설치하고 `clientKey`를 입력하면 캡차를 만났을 때 자동으로 인식하고 클릭해요 |
| 지원 범위 | 이 사이트에 나열된 모든 작업 유형 | reCAPTCHA v2, hCaptcha, FunCaptcha, AWS WAF, bCaptcha의 이미지 문제와 문자 캡차 |
| 비용 | 작업 유형별로 포인트 차감 | 확장 프로그램은 무료이고, 인식에 사용한 API 기준으로 포인트가 차감돼요 |
두 방법은 같은 계정, 같은 `clientKey`, 같은 잔액을 사용해요.
## 인식 결과는 세 가지예요
- **토큰**: reCAPTCHA, hCaptcha, Turnstile, FunCaptcha의 대부분의 작업 유형이에요. 문자열 하나를 반환하며, 이를 웹페이지의 폼이나 요청에 넣으면 이미지를 클릭하지 않고도 검증을 통과해요. 모두 비동기예요. 먼저 작업을 생성하고, 5초마다 한 번씩 결과를 조회해요.
- **이미지 인식 결과**: 이름이 `Classification`으로 끝나는 유형이에요. 캡차 이미지를 보내면 어떤 이미지나 어느 위치를 클릭해야 하는지 반환하고, 프로그램이 브라우저에서 직접 클릭해요. 동기로 반환되므로 요청 한 번으로 결과를 받아요.
- **텍스트 또는 쿠키**: 이미지 영숫자 인식은 이미지 속 문자를 반환하고, Cloudflare 챌린지 페이지는 검증을 통과한 뒤의 쿠키를 반환해요.
전체 유형과 가격은 [작업 유형 및 가격](https://docs.yescaptcha.com/ko/tasks.md)에서 확인하세요.
## 여기서 시작하세요
[빠른 시작](https://docs.yescaptcha.com/ko/getting-started/quickstart.md)회원가입, clientKey 확인, 첫 요청 보내기
[엔드포인트](https://docs.yescaptcha.com/ko/getting-started/endpoints.md)글로벌 엔드포인트와 중국 엔드포인트
[요금과 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)포인트, 선차감, 포인트 환불, 신고 후 포인트 환불
[브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)코드 없이 브라우저에서 자동으로 인식해요
## 커뮤니티 SDK
사용자가 제공한 SDK이며 공식 SDK가 아니에요. 사용하기 전에 직접 검토하세요. [예제 코드 및 SDK](https://docs.yescaptcha.com/ko/samples.md)를 참고하세요.
---
# 빠른 시작
> 5분 만에 첫 YesCaptcha 요청을 보내요. 회원가입, clientKey 복사, 충전을 마친 뒤 curl, Python, Node.js로 이미지 캡차를 인식해요(ImageToTextTaskOcrBase, 동기 반환, 건당 2포인트).
Source: https://docs.yescaptcha.com/ko/getting-started/quickstart/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/getting-started/quickstart/
이 페이지에서는 가장 간단한 작업 유형인 `ImageToTextTaskOcrBase`(이미지 속 영문과 숫자를 인식해요)로 첫 요청을 보내요. 동기 방식이라 `createTask` 요청 한 번으로 결과가 반환되고, 건당 2 포인트 (≈ $0.30 / 1k)가 차감돼요. 서드파티 사이트에 의존하지 않아서 계정과 코드가 문제없는지 확인하기 좋아요.
1. **회원가입**
[yescaptcha.com](https://yescaptcha.com/)에서 회원가입하고 로그인하세요.
2. **clientKey 복사**
로그인한 뒤 대시보드([yescaptcha.com/dashboard.html](https://yescaptcha.com/dashboard.html))에서 “내 ClientKey”를 찾아 복사를 눌러요. 값 전체를 빠짐없이 복사하세요.
> **주의:** 모든 API 요청은 clientKey로 인증해요. 다른 사람이 clientKey를 알면 내 잔액을 사용할 수 있어요. 다른 사람에게 보내거나 공개 코드에 넣지 마세요. 유출됐다면 같은 위치에서 재설정할 수 있어요.
3. **충전**
작업을 만들려면 잔액이 10포인트보다 많아야 해요. 충전 방법과 VIP 보너스는 [충전 및 VIP](https://docs.yescaptcha.com/ko/account/recharge.md)를 참고하세요.
4. **clientKey가 작동하는지 확인**
`getBalance`로 잔액을 조회해요. 포인트는 차감되지 않아요.
```bash
curl -s https://api.yescaptcha.com/getBalance \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY"}'
```
`{"errorId": 0, "balance": 12345, ...}`가 반환되면 사용할 수 있어요. `balance`는 남은 포인트예요. `ERROR_KEY_DOES_NOT_EXIST`가 반환되면 키를 잘못 복사한 거예요.
5. **이미지 인식**
예제 이미지 [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg)를 내려받으세요(가지고 있는 캡차 이미지를 써도 돼요). clientKey를 환경 변수에 넣은 뒤 실행하세요.
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
**curl**
quickstart.sh
```bash
#!/usr/bin/env bash
# First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image)
# Usage: YESCAPTCHA_CLIENT_KEY=your_client_key bash quickstart.sh captcha.png
set -euo pipefail
IMAGE="${1:-captcha.png}"
BODY=$(base64 < "$IMAGE" | tr -d '\n') # no "data:" prefix, no line breaks
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\", \"task\": {\"type\": \"ImageToTextTaskOcrBase\", \"body\": \"${BODY}\"}}"
echo
```
**Python**
quickstart.py
```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).
Usage:
export YESCAPTCHA_CLIENT_KEY=your_client_key
python quickstart.py captcha.png
"""
import base64
import os
import sys
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
with open(image_path, "rb") as f:
body = base64.b64encode(f.read()).decode() # no "data:" prefix
r = requests.post(
"https://api.yescaptcha.com/createTask",
json={
"clientKey": CLIENT_KEY,
"task": {"type": "ImageToTextTaskOcrBase", "body": body},
},
timeout=30,
)
data = r.json()
if data.get("errorId"):
raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```
**Node.js**
quickstart.mjs
```js
// First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
// Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
import { readFileSync } from 'node:fs';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
const res = await fetch('https://api.yescaptcha.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
console.log('text:', data.solution.text);
```
실행: `bash quickstart.sh captcha.jpg`, `python quickstart.py captcha.jpg` 또는 `node quickstart.mjs captcha.jpg`. Python은 먼저 `pip install requests`가 필요하고, Node.js는 18 이상 버전이 필요해요.
6. **결과 확인**
성공하면 다음과 같이 반환돼요.
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"text": "LMResm"
},
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
}
```
`errorId`가 0이면 성공이고, 인식된 텍스트는 `solution.text`에 있어요. `errorId`가 1이면 `errorCode`를 확인하세요. 의미는 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.
## 다음 단계
- reCAPTCHA, hCaptcha처럼 토큰을 반환하는 작업은 **비동기**예요. `createTask`가 먼저 `taskId`를 반환하고, 그다음 5초마다 `getTaskResult`를 호출해요. 전체 흐름은 [요청과 응답](https://docs.yescaptcha.com/ko/api/overview.md)을, 예시는 [reCAPTCHA v2](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md)를 참고하세요.
- 작업 유형 선택: [작업 유형과 가격](https://docs.yescaptcha.com/ko/tasks.md).
- 프로젝트에 바로 복사해 쓸 수 있는 클라이언트: [Python](https://docs.yescaptcha.com/ko/samples/python.md), [Node.js](https://docs.yescaptcha.com/ko/samples/nodejs.md).
- 코드 없이 사용하기: [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md).
---
# 엔드포인트
> YesCaptcha API의 두 엔드포인트인 글로벌 엔드포인트 api.yescaptcha.com과 중국 엔드포인트 cn.yescaptcha.com이에요. HTTPS POST JSON만 받으며, 작업 생성과 조회는 같은 엔드포인트에서 해야 해요.
Source: https://docs.yescaptcha.com/ko/getting-started/endpoints/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/getting-started/endpoints/
YesCaptcha API에는 엔드포인트가 두 개 있고, 메서드와 파라미터는 완전히 같아요. 서버 위치에 맞는 쪽을 고르세요.
| 엔드포인트 | 주소 | 적합한 경우 |
| --- | --- | --- |
| 글로벌 엔드포인트 | `https://api.yescaptcha.com` | 중국 본토 밖의 서버 |
| 중국 엔드포인트 | `https://cn.yescaptcha.com` | 중국 본토의 서버 |
메서드 URL은 엔드포인트 주소 + 메서드 이름이에요. 예를 들어 작업을 생성하는 URL은 다음과 같아요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
## 규칙
- HTTPS만 사용하세요.
- [/useragent](https://docs.yescaptcha.com/ko/api/useragent.md)를 제외한 모든 메서드는 `POST`를 사용하고, 요청 본문은 JSON이며 요청 헤더 `Content-Type: application/json`을 포함해야 해요. 요청 본문은 6 MB를 넘을 수 없어요.
- 요청 본문의 `clientKey`로 인증하며, 다른 요청 헤더는 필요 없어요.
> **참고:** 작업을 생성한 엔드포인트에서 `getTaskResult`로 조회하세요. 두 엔드포인트를 섞어 쓰면 안 돼요.
## 전체 메서드
| 메서드 | 기능 | 설명 |
| --- | --- | --- |
| [createTask](https://docs.yescaptcha.com/ko/api/create-task.md) | 작업 생성 | 동기 유형은 결과를 바로 반환해요 |
| [getTaskResult](https://docs.yescaptcha.com/ko/api/get-task-result.md) | 작업 결과 조회 | 비동기 유형은 5초마다 조회하세요 |
| [getBalance](https://docs.yescaptcha.com/ko/api/get-balance.md) | 잔액 조회 | 포인트가 차감되지 않아요 |
| [getSoftID](https://docs.yescaptcha.com/ko/api/get-soft-id.md) | 개발자 ID 조회 | 개발자 수익 배분에 사용해요 |
| [report](https://docs.yescaptcha.com/ko/api/report.md) | 인식 결과 신고 | 이미지 인식 유형은 포인트 환불을 신청할 수 있어요 |
| [useragent](https://docs.yescaptcha.com/ko/api/useragent.md) | 권장 User-Agent 가져오기 | `GET`, hCaptcha에서 사용해요 |
연결이 안 될 때는 [연결 및 네트워크 문제](https://docs.yescaptcha.com/ko/help/troubleshooting.md)를 참고하세요.
---
# 과금과 포인트 환불
> YesCaptcha의 포인트 차감 방식이에요. 1위안 = 1,000포인트이고 작업 유형별로 차감해요. 인식 실패와 타임아웃은 자동으로 포인트가 환불되고, 오류를 반환한 요청은 차감하지 않아요. 잔액은 10포인트보다 많아야 해요. 이미지 인식 신고 후 포인트 환불은 약 24시간 뒤에 처리돼요.
Source: https://docs.yescaptcha.com/ko/getting-started/billing/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/getting-started/billing/
YesCaptcha는 작업 단위로 포인트를 차감해요. 작업 유형마다 고정 가격이 있고 1위안 = 1,000포인트예요. 예를 들어 `NoCaptchaTaskProxyless`는 작업당 15 포인트 (≈ $2.25 / 1k)이에요. 유형별 가격은 [작업 유형과 가격](https://docs.yescaptcha.com/ko/tasks.md)에서 확인하세요.
> **팁:** 성공한 작업에 대해서만 비용을 내요. 인식에 실패하거나 타임아웃된 작업은 자동으로 포인트가 환불되고, 오류를 반환한 요청은 포인트를 차감하지 않아요.
## 포인트가 차감되는 시점
- **비동기 유형**(토큰을 반환하는 작업 유형 대부분): 작업이 생성될 때 포인트를 차감해요. 이후 인식에 실패하거나(`ERROR_CAPTCHA_UNSOLVABLE` 등) 타임아웃되면(`ERROR_TASK_TIMEOUT`, 보통 110초) 포인트가 자동으로 환불돼요.
- **동기 유형**(이미지 인식, `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle`): 인식에 성공해 결과를 반환할 때 포인트를 차감해요.
- 작업을 생성하는 시점에 오류가 반환된 경우(잘못된 파라미터, 잔액 부족, 동시 작업 수 제한 초과 등)에는 포인트를 차감하지 않아요.
## 잔액
- 작업을 생성하려면 잔액이 **10포인트보다 많아야** 해요. 그렇지 않으면 `ERROR_ZERO_BALANCE`가 반환돼요.
- 잔액은 [getBalance](https://docs.yescaptcha.com/ko/api/get-balance.md)로 조회해요. 포인트가 차감되지 않아요.
- 충전과 VIP 보너스는 [충전과 VIP](https://docs.yescaptcha.com/ko/account/recharge.md)를 참고하세요. 누적 충전액이 VIP 등급에 도달하면, 이후 충전할 때마다 비율에 따라 포인트를 보너스로 지급해요.
## 경우에 따라 가격이 달라지는 유형
- **reCAPTCHA v2 이미지 인식**(`ReCaptchaV2Classification`): 1x1 작은 이미지와 3x3, 4x4 큰 이미지의 가격이 달라요. [reCAPTCHA v2 이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)을 참고하세요.
- **hCaptcha 이미지 인식**(`HCaptchaClassification`): 대상을 찾지 못해 결과가 비어 있으면 포인트를 차감하지 않아요.
## 인식 오류 신고 후 포인트 환불
이미지 인식 결과가 틀렸다면 [report](https://docs.yescaptcha.com/ko/api/report.md)로 신고할 수 있어요. 조건에 맞으면 포인트가 환불돼요.
- 이미지 인식 유형 5가지만 해당돼요: `FunCaptchaClassification`, `HCaptchaClassification`, `ReCaptchaV2Classification`, `AwsClassification`, `bCaptchaClassification`.
- 작업을 생성하고 **1시간 이내**에 신고해야 하고, 같은 작업은 한 번만 계산해요.
- 바로 환불되지 않고 **약 24시간 뒤**에 일괄 정산해요.
- 정산할 때 같은 기간에 같은 질문을 푼 다른 사용자와 비교해요. 신고한 실패율이 같은 기간 수준보다 뚜렷하게 높으면 같은 기간의 실패율에 맞춰 환불해요.
- 성공과 실패를 모두 사실대로 신고해 주세요. 실패만 신고한 내역은 같은 기간의 참고 자료로 쓰지 않으며, 실패율은 생성한 전체 작업을 기준으로 계산해요.
- 정산 결과에 이의가 있으면 [고객 지원](https://docs.yescaptcha.com/ko/help/contact.md)에 문의해 이의를 제기할 수 있어요.
토큰을 반환하는 작업 유형(reCAPTCHA, hCaptcha, Turnstile 등)은 토큰이 통과되는지를 대상 사이트가 판단하므로, 신고해도 포인트가 환불되지 않아요.
## 포인트를 차감하지 않는 경우
| 상황 | 반환 |
| --- | --- |
| 잘못된 파라미터, 존재하지 않는 유형, 잘못된 `clientKey` | 해당 오류 코드 |
| 잔액이 10포인트 이하 | `ERROR_ZERO_BALANCE` |
| 동시 작업 수 제한 초과 | `ERROR_THREADS_MAXIMUM`, [동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md) 참고 |
| 자동 일시 중지 중 | `ERROR_IP_BLOCKED_5MIN` |
| 유효하지 않다고 판정된 sitekey 또는 도메인(캐시 기간 중) | 기존 오류 코드, `cached: true` 포함 |
| 인식 실패, 타임아웃 | 이미 차감된 포인트가 자동으로 환불돼요 |
## 수익 배분과 보상
- 다른 사람의 소프트웨어나 확장 프로그램을 사용하면 작업에 개발자 ID가 포함될 수 있어요. 개발자는 수익을 배분받지만 내가 내는 포인트에는 영향이 없어요. 직접 소프트웨어를 개발한다면 [개발자 수익 배분](https://docs.yescaptcha.com/ko/account/developer.md)을 참고하세요.
- 다른 사람을 추천해 가입시키는 방법은 [추천 보상](https://docs.yescaptcha.com/ko/account/referral.md)을 참고하세요.
---
# 요청과 응답
> YesCaptcha API의 공통 규칙: POST JSON, clientKey 인증, errorId 응답 형식, 동기·비동기 작업, 5초마다 폴링, 110초 타임아웃, 결과 약 10분 보관, Accept-Language에 따른 안내 문구 언어.
Source: https://docs.yescaptcha.com/ko/api/overview/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/overview/
모든 메서드는 HTTPS `POST`로 JSON을 보내고(`/useragent`만 `GET`), 요청 본문의 `clientKey`로 인증하며, 응답은 모두 JSON이에요. `errorId`가 0이면 성공이고, 1이면 실패이며 `errorCode`가 함께 와요. 캡차 하나를 인식하는 데는 두 단계가 필요해요. `createTask`로 작업을 만들고, `getTaskResult`로 5초마다 결과를 조회해요. 동기 유형은 `createTask`에서 바로 결과를 반환해요.
## 요청
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```
- 엔드포인트: `https://api.yescaptcha.com`(글로벌) 또는 `https://cn.yescaptcha.com`(중국). [접속 주소](https://docs.yescaptcha.com/ko/getting-started/endpoints.md)를 참고하세요.
- 요청 본문은 JSON이며 `Content-Type: application/json` 헤더를 붙이고, 6 MB를 넘지 않아야 해요. JSON에는 주석을 쓸 수 없어요.
- 모든 요청에 `clientKey`를 넣어야 하며, 대시보드에 표시된 값을 그대로 복사하세요.
> **주의:** Python requests에서는 `json=data`를 사용하고 `data=data`는 사용하지 마세요. 후자는 폼으로 전송되어 `ERROR_TASK_ABSENT` 또는 `ERROR_REQUIRED_FIELDS`가 반환돼요.
## 응답
성공:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
실패:
```json
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "帐户余额不足"
}
```
| 필드 | 설명 |
| --- | --- |
| `errorId` | 0은 성공, 1은 실패 |
| `errorCode` | 실패 시의 오류 코드. 의미와 해결 방법은 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요 |
| `errorDescription` | 실패 원인을 설명하는 문구 |
| `taskId` | 작업 ID |
| `status` | `processing`(처리 중) 또는 `ready`(완료) |
| `solution` | 인식 결과. 필드는 작업 유형마다 달라요. 각 작업 유형 페이지를 참고하세요 |
결과를 판단할 때는 `errorId`와 `errorCode`를 기준으로 하세요. `errorDescription`의 문구는 바뀔 수 있으니 파싱하지 마세요.
## 동기와 비동기
| | 비동기 | 동기 |
| --- | --- | --- |
| 해당 유형 | 토큰을 반환하는 작업 유형(reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), Cloudflare 챌린지 페이지, `ImageToTextTask`, `ImageToTextTaskM1` | 이미지 인식(이름이 `Classification`으로 끝나는 유형), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` 반환값 | `taskId` | `status: "ready"`와 `solution` |
| 결과 받는 방법 | 5초마다 `getTaskResult` 호출 | 따로 조회할 필요 없음 |
각 유형이 어느 쪽인지는 [작업 유형과 가격](https://docs.yescaptcha.com/ko/tasks.md)의 “반환 방식” 열에서 확인하세요.
## 폴링
1. `createTask`가 `taskId`를 반환하면 5초 기다린 뒤 `getTaskResult`를 호출하세요.
2. `status: "processing"`이 반환되면 5초 더 기다렸다가 다시 시도하세요. `status: "ready"`가 반환되면 결과는 `solution`에 있어요.
3. `errorId: 1`이 반환되면 이 작업의 폴링을 멈추고 `errorCode`에 따라 처리하세요.
- 같은 `taskId`를 5초 안에 다시 조회하면 바로 `processing`이 반환돼요. 더 자주 조회해도 결과를 더 빨리 받지는 못해요.
- 작업은 보통 최대 110초까지 처리돼요(일부 유형은 180~220초). 시간이 초과되면 `ERROR_TASK_TIMEOUT`이 반환되고 포인트가 자동으로 환불돼요.
- 결과는 서버에 약 10분 동안 보관돼요. 그 후에는 `taskId`가 만료되어 조회하면 `ERROR_TASKID_INVALID`가 반환돼요.
- 결과 조회는 포인트를 차감하지 않아요. 작업을 만들 때만 포인트가 차감돼요.
## 안내 문구의 언어
자동 일시 중지, 잘못된 파라미터 캐시, 폴링 중단 안내의 `errorDescription`은 요청 헤더 `Accept-Language`에 따라 언어가 정해져요. `zh`로 시작하면 중국어, 그 밖의 언어는 영어로 반환하고, 이 헤더가 없으면 중국어와 영어를 모두 반환해요. 다른 오류 코드의 설명은 영향을 받지 않아요.
## 다음 단계
- [createTask 작업 만들기](https://docs.yescaptcha.com/ko/api/create-task.md)
- [getTaskResult 결과 가져오기](https://docs.yescaptcha.com/ko/api/get-task-result.md)
- [동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md): 오류가 너무 많으면 몇 분 동안 일시 중지돼요
---
# createTask 작업 생성
> POST /createTask로 캡차 인식 작업을 생성해요. 요청 파라미터(clientKey, task, softID), 검증 순서, 비동기 유형은 taskId 반환, 동기 유형은 solution 직접 반환, 잔액은 10 포인트보다 많아야 해요.
Source: https://docs.yescaptcha.com/ko/api/create-task/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/create-task/
`createTask`는 인식 작업을 생성해요. `task.type`에 어떤 캡차를 인식할지 지정해요. 비동기 유형은 `taskId`를 반환하며, 이후 [getTaskResult](https://docs.yescaptcha.com/ko/api/get-task-result.md)로 결과를 가져와요. 동기 유형은 결과를 바로 반환해요.
> **참고:** 작업이 성공적으로 생성되면 포인트가 차감되며, 작업을 생성하려면 잔액이 10 포인트보다 많아야 해요. 인식에 실패하거나 시간이 초과된 작업은 포인트가 자동으로 환불돼요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
## 요청 파라미터
| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `clientKey` | string | 예 | ClientKey. [yescaptcha.com](https://yescaptcha.com/) 대시보드에서 복사해요 |
| `task` | object | 예 | 작업 객체. 반드시 `type`이 있어야 하고, 나머지 필드는 작업 유형에 따라 채워요. 각 작업 유형 페이지를 참고하세요 |
| `softID` | integer | 아니요 | 개발자 ID. 직접 개발한 소프트웨어를 다른 사람이 사용할 때 이 값을 함께 보내면 수익을 배분받을 수 있어요. [개발자 수익 배분](https://docs.yescaptcha.com/ko/account/developer.md)을 참고하세요 |
## 요청 예시
이미지 캡차 인식(동기):
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}
```
reCAPTCHA v2 토큰 가져오기(비동기):
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
각 작업 유형의 `task` 필드는 [작업 유형과 가격](https://docs.yescaptcha.com/ko/tasks.md) 아래의 각 페이지에 있어요.
## 반환 결과
비동기 유형:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
`taskId`를 기록해 두고, 5초 후부터 `getTaskResult`로 조회하세요.
동기 유형:
```json
{
"errorId": 0,
"status": "ready",
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b",
"solution": {
"text": "LMResm"
}
}
```
실패:
```json
{
"errorId": 1,
"errorCode": "ERROR_TASK_NOT_SUPPORTED",
"errorDescription": "任务类型不正确或不受支持"
}
```
## 검증 순서
서버는 다음 순서로 요청을 검사하고, 처음 발견한 문제에 해당하는 오류 코드를 반환해요. 이 경우 포인트는 차감되지 않아요.
1. 요청 본문이 올바른 JSON인지: `ERROR_REQUEST_FORMATS`
2. `clientKey`가 있는지: `ERROR_REQUIRED_FIELDS`
3. `clientKey`가 존재하는지: `ERROR_KEY_DOES_NOT_EXIST`
4. 자동 일시 중지 상태가 아닌지: `ERROR_IP_BLOCKED_5MIN` ([동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md) 참고)
5. 잔액이 10 포인트보다 많은지: `ERROR_ZERO_BALANCE`
6. `task`가 있는지: `ERROR_TASK_ABSENT`
7. `task.type`이 존재하는지: `ERROR_TASK_NOT_SUPPORTED`
8. 필수 필드가 모두 있는지: `ERROR_REQUIRED_FIELDS` (`errorDescription`에 누락된 필드가 적혀 있어요)
9. 이미지 작업의 이미지가 올바른지: `ERROR_ZERO_CAPTCHA_FILESIZE`, `ERROR_IMAGE_TYPE_NOT_SUPPORTED` 등
## 전체 예시
작업을 생성하고 결과를 폴링해요(비동기 유형):
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
import requests
API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"] # Read the clientKey from an environment variable
def call(method, payload):
r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
data = r.json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def solve(task):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable
async function call(method, payload) {
const res = await fetch(`${API}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
return data;
}
async function solve(task) {
const { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "NoCaptchaTaskProxyless",
websiteURL: "https://www.google.com/recaptcha/api2/demo",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```
---
# getTaskResult 결과 조회
> POST /getTaskResult로 비동기 작업의 결과를 조회해요. 5초마다 조회하고, processing이면 계속 기다리고, ready이면 solution을 가져오고, 오류가 나면 폴링을 멈추세요. 작업은 최대 약 110초 걸리고, 결과는 약 10분 동안 보관되며, 조회는 포인트를 차감하지 않아요.
Source: https://docs.yescaptcha.com/ko/api/get-task-result/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/get-task-result/
`getTaskResult`는 비동기 작업의 결과를 조회해요. 작업을 만든 뒤 5초마다 호출하세요. `processing`이 반환되면 계속 기다리고, `ready`가 반환되면 결과는 `solution`에 들어 있어요. 오류가 반환되면 멈추세요. 조회는 포인트를 차감하지 않으니 몇 번을 조회해도 같아요.
- POST `https://api.yescaptcha.com/getTaskResult` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/getTaskResult` (중국 엔드포인트)
## 요청 파라미터
| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `clientKey` | string | 예 | 계정 ClientKey예요. 작업을 만들 때 사용한 값과 같아야 해요 |
| `taskId` | string | 예 | [createTask](https://docs.yescaptcha.com/ko/api/create-task.md)가 반환한 작업 ID |
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
## 반환 결과
| 상황 | 반환 | 대응 방법 |
| --- | --- | --- |
| 처리 중 | `errorId`가 0, `status`가 `processing` | 5초 뒤에 다시 조회하세요 |
| 완료 | `errorId`가 0, `status`가 `ready`, 결과는 `solution`에 있음 | `solution`을 가져오세요. 필드는 각 작업 유형 페이지에 있어요 |
| 인식 실패 | `errorId`가 1, `errorCode`가 `ERROR_CAPTCHA_UNSOLVABLE` | 포인트가 자동으로 환불됐어요. 작업을 다시 만들 수 있어요 |
| 시간 초과 | `errorId`가 1, `errorCode`가 `ERROR_TASK_TIMEOUT` | 포인트가 자동으로 환불됐어요. 작업을 다시 만들 수 있어요 |
| 작업이 없거나 만료됨 | `errorId`가 1, `errorCode`가 `ERROR_TASKID_INVALID` | 이 `taskId`의 조회를 멈추세요 |
완료됐을 때의 예시(reCAPTCHA v2):
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
## 규칙
- **5초마다 조회하세요.** 같은 `taskId`를 5초 안에 다시 조회하면 바로 `processing`이 반환돼요. 더 자주 조회해도 빨라지지 않아요.
- **작업은 최대 약 110초 동안 처리돼요**(일부 유형은 180~220초). 시간이 초과되면 `ERROR_TASK_TIMEOUT`이 반환되고 포인트가 자동으로 환불돼요. 코드의 대기 한도는 3분 정도로 설정하는 것을 권장해요.
- **결과는 약 10분 동안 보관돼요.** 그 후에는 `taskId`가 만료되어 `ERROR_TASKID_INVALID`가 반환돼요. 결과를 받으면 가능한 한 빨리 사용하세요. 토큰 자체의 유효 기간은 더 짧아요(reCAPTCHA는 약 120초).
- **오류가 나면 멈추세요.** `errorId: 1`이 반환된 뒤에 같은 `taskId`를 계속 조회해도 결과는 바뀌지 않아요. 이미 종료된 같은 작업을 3번째 조회하는 시점부터 `errorDescription` 끝에 폴링을 멈추라는 안내가 붙어요. `ERROR_TASKID_INVALID`는 [자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)의 오류 횟수에 포함돼요(같은 ID는 처음 한 번만 계산해요).
- 작업을 만든 엔드포인트에서 조회해야 해요.
- `getTaskResult`는 자동 일시 중지의 영향을 받지 않아요. 일시 중지되기 전에 만든 작업은 평소처럼 조회할 수 있어요.
---
# getBalance 잔액 조회
> POST /getBalance로 계정 잔액(포인트, 1,000포인트 = ¥1)과 개발자 수익 배분·추천 보상 잔액을 조회해요. 포인트가 차감되지 않아 clientKey를 확인하는 데 쓸 수 있어요.
Source: https://docs.yescaptcha.com/ko/api/get-balance/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/get-balance/
`getBalance`는 계정의 남은 포인트(1,000포인트 = ¥1)와 개발자 수익 배분 및 추천 보상 잔액(위안)을 반환해요. 포인트가 차감되지 않아서 `clientKey`가 올바른지 확인할 때 자주 써요.
- POST `https://api.yescaptcha.com/getBalance` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/getBalance` (중국 엔드포인트)
## 요청 파라미터
| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `clientKey` | string | 예 | 계정의 ClientKey |
```json
{
"clientKey": "YOUR_CLIENT_KEY"
}
```
## 반환 결과
```json
{
"errorId": 0,
"balance": 1071810,
"softBalance": 36.0098,
"inviteBalance": 0,
"inviteBy": 0
}
```
| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `balance` | integer | 계정 잔액이며 단위는 포인트(1,000포인트 = ¥1)예요. 작업을 만들려면 10포인트보다 커야 해요 |
| `softBalance` | number | 개발자 수익 배분 잔액이며 단위는 위안이에요. [개발자 수익 배분](https://docs.yescaptcha.com/ko/account/developer.md)을 참고하세요 |
| `inviteBalance` | number | 추천 보상 잔액이며 단위는 위안이에요. [추천 보상](https://docs.yescaptcha.com/ko/account/referral.md)을 참고하세요 |
| `inviteBy` | integer | 나를 추천해 가입시킨 사용자의 ID이며, 없으면 0이에요 |
| `keyQuotaRemaining` | integer | 이 `clientKey`의 현재 주기에 남은 사용 한도이며 단위는 포인트예요. 한도를 설정한 `clientKey`에만 이 필드가 있고, 이때 `balance`는 계정 잔액과 남은 한도 중 작은 값이에요. 한도를 설정하지 않았다면 이 필드는 없어요 |
`clientKey`가 올바르지 않으면 `ERROR_KEY_DOES_NOT_EXIST`를 반환해요. `clientKey`에 IP 화이트리스트가 설정되어 있는데 요청을 보낸 IP가 목록에 없으면 `ERROR_KEY_IP_NOT_ALLOWED`를 반환해요. `getBalance`는 [자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)의 영향을 받아요. 일시 중지 중에는 `ERROR_IP_BLOCKED_5MIN`을 반환해요.
## 예시
**curl**
get-balance.sh
```bash
#!/usr/bin/env bash
# Check the balance. getBalance is free and is a quick way to verify your clientKey
set -euo pipefail
curl -s https://api.yescaptcha.com/getBalance \
-H 'Content-Type: application/json' \
-d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\"}"
echo
```
**Python**
get_balance.py
```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
r = requests.post(
"https://api.yescaptcha.com/getBalance",
json={"clientKey": CLIENT_KEY},
timeout=30,
)
data = r.json()
if data.get("errorId"):
# e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
print("balance (points):", data["balance"])
```
**Node.js**
get-balance.mjs
```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const res = await fetch('https://api.yescaptcha.com/getBalance', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
// e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
console.log('error:', data.errorCode, data.errorDescription);
} else {
console.log('balance (points):', data.balance);
}
```
---
# getSoftID 개발자 ID 조회
> POST /getSoftID로 개발자 ID(softID)와 누적 개발자 수익 배분 금액을 조회해요. 다른 사용자가 내 소프트웨어를 쓸 때 보내는 createTask 요청에 softID를 넣으면 수익을 배분받을 수 있어요.
Source: https://docs.yescaptcha.com/ko/api/get-soft-id/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/get-soft-id/
`getSoftID`는 개발자 ID(`softID`)와 누적 개발자 수익 배분 금액(위안)을 반환해요. 직접 개발한 소프트웨어나 확장 프로그램을 다른 사람이 사용할 때 그 사용자의 `createTask` 요청에 이 ID를 넣으면, 사용자의 소비 금액에 따라 수익을 배분받을 수 있어요. 배분 규칙과 출금은 [개발자 수익 배분](https://docs.yescaptcha.com/ko/account/developer.md)을 참고하세요.
- POST `https://api.yescaptcha.com/getSoftID` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/getSoftID` (중국 엔드포인트)
## 요청 파라미터
| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `clientKey` | string | 예 | 개발자 본인의 ClientKey |
```json
{
"clientKey": "YOUR_CLIENT_KEY"
}
```
## 반환 결과
```json
{
"errorId": 0,
"softID": 3,
"balance": 0.004
}
```
| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `softID` | integer | 개발자 ID |
| `balance` | number | 누적 개발자 수익 배분 잔액이에요. 단위는 위안이에요 |
## 사용 방법
내 소프트웨어를 사용하는 사용자가 보내는 `createTask` 요청에 최상위 필드 `softID`를 추가하세요.
```json
{
"clientKey": "THE_USERS_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
},
"softID": 3
}
```
> **주의:** `softID`는 요청 본문의 최상위에 `clientKey`, `task`와 같은 위치로 넣어야 하고, 필드명의 대소문자도 정확히 맞춰야 해요. `task` 안에 넣으면 적용되지 않아요.
`clientKey`는 사용자 본인의 키이고 포인트도 사용자에게서 차감돼요. `softID`는 개발자 본인의 개발자 ID예요.
---
# report 결과 신고
> POST /report로 작업의 인식 결과가 맞았는지 신고해요. 성공과 실패 모두 사실대로 신고해 주세요. 이미지 인식 유형은 작업 생성 후 1시간 이내에 실패를 신고하면 약 24시간 뒤에 포인트 환불이 정산돼요.
Source: https://docs.yescaptcha.com/ko/api/report/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/report/
`report`는 작업 묶음의 인식 결과가 맞았는지 알려 주는 API예요. **성공과 실패 모두 신고해 주세요.** 이미지 인식 유형에서 “오류”로 신고하면 조건에 맞는 경우 약 24시간 뒤에 포인트가 환불돼요. 신고한 결과는 인식 품질을 평가하고 개선하는 데도 쓰여요.
- POST `https://api.yescaptcha.com/report` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/report` (중국 엔드포인트)
## 요청 파라미터
| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `id` | array of string | 예 | 작업 ID 목록이에요. 한 번에 여러 개를 신고할 수 있어요 |
| `isSuccess` | boolean | 예 | `true`는 인식 성공, `false`는 인식 오류예요 |
`clientKey`는 필요 없어요. 작업 ID만으로 작업을 찾을 수 있어요.
```json
{
"id": ["610ff5e0-68eb-11ef-95a6-22e70a0b794d", "65b88c06-68eb-11ef-8e9a-52540023ccb3"],
"isSuccess": false
}
```
## 응답
```json
{
"errorId": 0,
"status": "success"
}
```
## 사실대로 신고해 주세요
신고는 포인트 환불 정산에도, 인식 품질을 평가하고 개선하는 데도 쓰여요. 실제 결과대로 신고해 주세요.
- 인식이 맞은 작업은 `isSuccess: true`로, 틀린 작업은 `false`로 신고해요. 실패만 신고하거나 맞고 틀림과 상관없이 모두 실패로 신고하면 통계와 정산에서 참고하지 않아요.
- 실패율은 이 기간에 만든 전체 작업을 기준으로 계산해요. 신고한 작업만 계산하지 않아요. 실패를 더 많이 신고해도 환불이 늘지 않아요. 실패율이 같은 기간의 수준보다 뚜렷하게 높으면 같은 기간의 실패율만큼만 환불해요.
- 한 번의 인증에 이미지를 여러 장 쓰고(예: FunCaptcha는 5라운드를 풀어야 해요) 어느 것이 틀렸는지 모를 때는 해당 작업 묶음을 모두 실패로 신고하면 돼요. 인증을 통과했을 때도 같은 묶음을 모두 성공으로 신고해 주세요.
## 신고 후 포인트 환불
- 포인트 환불이 되는 유형은 이미지 인식 5가지뿐이에요: `FunCaptchaClassification`, `HCaptchaClassification`, `ReCaptchaV2Classification`, `AwsClassification`, `bCaptchaClassification`.
- 작업을 만든 뒤 **1시간 이내**에 한 신고만 인정해요. 같은 작업은 한 번만 환불해요.
- 바로 환불되지 않고 **약 24시간 뒤**에 한꺼번에 정산해요.
- 정산할 때 같은 기간에 같은 질문을 푼 다른 사용자와 비교해요. 신고한 실패율이 같은 기간의 수준보다 뚜렷하게 높으면 같은 기간의 실패율만큼 환불해요.
- 정산에 이의가 있으면 [고객 지원에 문의](https://docs.yescaptcha.com/ko/help/contact.md)해 이의를 제기할 수 있어요.
토큰을 반환하는 작업 유형(reCAPTCHA, hCaptcha, Turnstile, FunCaptcha 등)은 토큰이 통과하는지를 대상 사이트가 판단하므로 신고해도 포인트가 환불되지 않아요. 과금 규칙은 [과금과 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)에서 한눈에 볼 수 있어요.
---
# useragent로 UA 가져오기
> GET https://api.yescaptcha.com/useragent는 현재 권장하는 브라우저 User-Agent를 일반 텍스트로 반환해요. hCaptcha 작업의 userAgent는 이 값만 허용해요.
Source: https://docs.yescaptcha.com/ko/api/useragent/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/useragent/
`/useragent`는 현재 권장하는 브라우저 User-Agent를 일반 텍스트로 반환해요. `clientKey`가 필요 없고 포인트도 차감되지 않아요. [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md) 작업의 `userAgent` 필드는 이 값만 허용해요. 대상 웹사이트에 접속할 때도 이 값을 사용하면 토큰이 더 쉽게 통과돼요.
- GET `https://api.yescaptcha.com/useragent` (글로벌 엔드포인트)
- GET `https://cn.yescaptcha.com/useragent` (중국 엔드포인트)
## 예시
```bash
curl -s https://api.yescaptcha.com/useragent
```
응답 (2026-10-15 기준 값이며, 브라우저 버전에 따라 바뀌어요):
```text
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36
```
> **참고:** 반환값은 수시로 바뀌므로 코드에 고정하지 말고, 프로그램을 시작할 때마다 한 번 가져오세요.
- 인식 결과에 `userAgent`가 포함되어 있으면, 토큰을 제출할 때 결과에 있는 값을 사용하세요.
---
# 오류 코드
> YesCaptcha API의 모든 오류 코드의 의미와 처리 방법을 요청 형식, 계정 잔액, 동시 작업과 일시 중지, 작업 결과, 사이트 파라미터, 이미지, 프록시, 서버별로 정리했어요. 오류를 반환한 요청은 포인트를 차감하지 않아요.
Source: https://docs.yescaptcha.com/ko/api/errors/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/
API 호출이 실패하면 `errorId: 1`이 반환되고, `errorCode`에 오류 코드가, `errorDescription`에 설명 문구가 담겨요. 오류를 반환한 요청은 포인트를 차감하지 않아요. 작업을 만드는 단계에서 난 오류는 차감하지 않고, 작업 생성 후 인식에 실패하거나 시간이 초과된 경우에는 포인트가 자동으로 환불돼요.
> **팁:** 코드에서는 `errorDescription`의 문구가 아니라 `errorCode`로 판단하세요. 설명 문구는 바뀔 수 있어요.
```json
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "帐户余额不足"
}
```
## 처리 원칙
1. **파라미터 오류**(요청 형식, 키, 작업 유형, 사이트 파라미터, 이미지)는 다시 보내도 결과가 같아요. 먼저 요청을 고치세요.
2. **인식 실패와 시간 초과**(`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`)는 작업을 새로 만들어서 다시 시도할 수 있어요.
3. 오류가 나면 해당 `taskId`의 **폴링을 멈추세요**. 같은 요청을 그대로 빠르게 반복해서 보내지 마세요.
4. “자동 일시 중지에 포함”으로 표시된 오류는 같은 `clientKey`에서 1분 안에 100번 발생하면 작업 생성이 5분 동안 일시 중지돼요. “캐시”로 표시된 오류는 횟수에 포함되지 않지만, 캐시 기간에는 같은 요청에 원래 오류가 그대로 반환돼요. 자세한 내용은 [동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)를 참고하세요.
## 전체 오류 코드
### 요청 형식
| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | 필수 필드가 없거나(예: `clientKey`, 또는 작업 유형에 필요한 `websiteURL`, `websiteKey`) 요청 본문이 JSON이 아니에요 | 작업 유형 페이지의 파라미터 표를 보고 빠진 필드를 추가하세요. `POST`로 JSON을 보내고 `Content-Type: application/json`을 포함하세요 |
| `ERROR_REQUEST_FORMATS` (자동 일시 중지에 포함) | 요청 본문이 올바른 JSON이 아니에요 | 문자열을 직접 이어 붙이지 말고 JSON 라이브러리로 요청 본문을 만드세요. JSON에는 `//` 주석을 넣을 수 없어요 |
| `ERROR_TASK_ABSENT` (자동 일시 중지에 포함) | `createTask`를 호출할 때 `task` 필드가 없어요 | 작업 파라미터를 `task` 객체에 넣으세요. Python requests에서는 `data=data`가 아니라 `json=data`를 사용하세요 |
| `ERROR_TASK_NOT_SUPPORTED` (자동 일시 중지에 포함) | `task.type`의 철자가 틀렸거나 해당 유형이 종료되었어요 | "작업 유형 및 가격"에서 유형 이름을 복사하세요. 대소문자를 구분해요 |
| `ERROR_PAGE_NOT_FOUND` | 요청한 경로가 존재하지 않아요 | 엔드포인트 주소를 확인하세요. 예: `https://api.yescaptcha.com/createTask`. 메서드 이름은 대소문자를 구분해요 |
| `ERROR_BAD_REQUEST` | 요청을 처리할 수 없어요. 주로 HTTP 메서드가 잘못되었거나(POST 대신 GET 사용) 파라미터 값이 올바르지 않을 때 발생해요 | `POST`로 JSON을 보내고, 파라미터의 타입과 값을 확인하세요 |
| `ERROR_ILLEGAL_PARAMETERS` | 파라미터 값이 올바르지 않아요. Cloudflare 챌린지 페이지에서 흔히 발생해요. `websiteURL`이 `http://` / `https://`로 시작하는 공개 URL이 아니거나, `postData`가 객체가 아니거나, `requiredCookies`가 문자열 배열이 아닌 경우예요(createTask에서 반환되며 포인트는 차감되지 않아요). 또는 프록시를 통해 대상 도메인을 확인할 수 없는 경우예요(getTaskResult에서 반환되며 포인트는 자동으로 환불돼요) | 작업 유형 페이지의 파라미터 표를 보고 값을 수정하세요. 도메인을 확인할 수 없다면 URL 철자와 프록시가 해당 사이트에 접속할 수 있는지 확인하세요 |
### 계정 및 잔액
| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (자동 일시 중지에 포함) | `clientKey`가 존재하지 않아요. 복사할 때 문자가 추가되거나 빠졌거나, 대시보드에서 키를 재설정했을 수 있어요 | yescaptcha.com 대시보드에서 키를 다시 복사하세요. 공백이나 줄바꿈이 없어야 해요 |
| `ERROR_KEY_EXPIRED` (자동 일시 중지에 포함) | `clientKey`가 만료되었어요(createTask와 getBalance에서 반환되며, 포인트는 차감되지 않아요). 두 가지 경우가 있어요. 오랫동안 사용하지 않아 계정 보안을 위해 시스템이 만료 시간을 설정한 경우(만료 전에 이메일로 알려 드려요), 또는 이 `clientKey`에 설정한 만료 시간이 지난 경우예요 | yescaptcha.com 대시보드에 로그인하세요. 오랫동안 사용하지 않아 만료된 경우 새 `clientKey`를 생성하세요. 잔액은 새 `clientKey`로 자동 이동해요. 만료 시간을 설정한 경우에는 만료 시간을 변경하거나 다른 `clientKey`를 사용하세요. 그런 다음 프로그램의 `clientKey`를 새 값으로 업데이트하세요 |
| `ERROR_KEY_IP_NOT_ALLOWED` | 이 `clientKey`에는 IP 허용 목록이 설정되어 있는데, 요청을 보낸 IP가 목록에 없어요 (createTask와 getBalance에서 반환돼요. 포인트는 차감되지 않으며, 자동 일시 중지 횟수에도 포함되지 않아요) | yescaptcha.com 대시보드에 로그인해서 요청을 보내는 기기의 공인 IP를 이 `clientKey`의 허용 목록에 추가하거나, 다른 `clientKey`를 사용하세요. 여러 기기에서 API를 호출한다면 각 기기의 공인 IP를 모두 추가해야 해요 (여기서 말하는 IP는 YesCaptcha API를 호출하는 IP이며, 작업 파라미터의 프록시와는 관계없어요) |
| `ERROR_KEY_QUOTA_EXCEEDED` | 이 `clientKey`에는 사용 한도가 설정되어 있는데, 현재 기간에 남은 한도가 이번 작업의 포인트 차감액보다 적어요 (createTask에서 반환돼요. 포인트는 차감되지 않으며, 자동 일시 중지 횟수에도 포함되지 않아요). 한도는 실제로 차감된 포인트를 기준으로 계산하며, 인식 실패나 시간 초과로 환불된 포인트는 한도에도 다시 반영돼요 | yescaptcha.com 대시보드에 로그인해서 이 `clientKey`의 한도를 늘리거나, 다음 기간까지 기다리거나(베이징 시간 기준으로 매일, 매주 월요일 또는 매월 1일에 초기화돼요. 일회성 한도는 초기화되지 않아요), 다른 `clientKey`를 사용하세요. `getBalance`로 이 `clientKey`의 남은 한도(`keyQuotaRemaining`)를 확인할 수 있어요 |
| `ERROR_ZERO_BALANCE` | 잔액이 부족해요. 작업을 만들려면 잔액이 10포인트보다 많아야 해요 | 충전한 뒤 다시 시도하세요. `getBalance`로 잔액을 확인할 수 있어요 |
### 동시 작업 및 일시 중지
| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (경우에 따라 자동 일시 중지에 포함) | 이 계정에서 이 유형의 작업이 동시에 너무 많이 처리 중이에요. 응답의 `limit`은 현재 한도예요. 이 요청은 처리되지 않았고 포인트도 차감되지 않았어요 | 이미 보낸 요청이 반환될 때까지 기다린 뒤 새 요청을 보내거나, 1~2초 기다렸다가 다시 시도하세요. 프로그램에서 동시에 결과를 기다리는 요청 수를 제한하세요 |
| `ERROR_IP_BLOCKED_5MIN` | 이 `clientKey`에서 짧은 시간에 오류가 너무 많이 발생해 작업 생성이 자동으로 일시 중지되었어요. 응답의 `retryAfter`는 남은 시간(초)이고 `blockReason`은 일시 중지를 일으킨 오류 코드예요 | `blockReason`에 따라 요청을 수정하고 `retryAfter`초 동안 기다리세요. 일시 중지 중에 요청을 보내도 시간이 늘어나지 않아요 |
| `ERROR_NO_SLOT_AVAILABLE` | 인식 서비스가 일시적으로 과부하 상태예요. `createTask`에서 반환된 경우 포인트가 차감되지 않아요. 대기열에서 너무 오래 기다린 작업은 `getTaskResult`에서도 이 오류가 반환되며, 포인트가 자동으로 환불돼요 | 몇 초 기다린 뒤 작업을 다시 생성하세요 |
### 작업 및 결과
| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (자동 일시 중지에 포함) | `taskId`가 존재하지 않거나, 만료되었거나(결과는 약 10분간 보관돼요), 다른 `clientKey`로 생성되었거나, 다른 엔드포인트에서 생성되었어요 | 이 작업의 폴링을 중단하세요. 작업을 생성한 것과 같은 엔드포인트와 같은 `clientKey`로 조회하세요 |
| `ERROR_TASK_TIMEOUT` | 작업이 제한 시간(보통 110초) 안에 완료되지 않았어요. 포인트는 자동으로 환불됐어요 | 작업을 새로 생성하세요. 계속 시간 초과가 발생하면 같은 캡차에 대한 다른 작업 유형을 사용해 보세요 |
| `ERROR_CAPTCHA_UNSOLVABLE` | 이번에는 캡차를 인식하지 못했어요. 포인트는 환불됐어요. 자동 일시 중지 횟수에는 포함되지 않아요 | 작업을 새로 생성하세요. 계속 실패하면 `websiteURL`, `websiteKey` 등의 파라미터를 확인하거나 같은 캡차에 대한 다른 작업 유형을 사용해 보세요 |
| `ERROR_SETTLEMENT_FAILED` (자동 일시 중지에 포함) | 정산 시점에 잔액이 부족해서 결과가 반환되지 않았어요 | 충전한 뒤 작업을 새로 생성하세요 |
| `ERROR_NO_SUCH_CAPCHA_ID` | 작업이 더 이상 유효하지 않아요 | 이 작업의 폴링을 중단하고 새로 생성하세요 |
| `ERROR_RECAPTCHA_TIMEOUT` | 캡차 인식 시간이 초과되었어요. 포인트는 환불됐어요 | 작업을 새로 생성하세요 |
### 대상 웹사이트 파라미터
| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (캐시됨, 일시 중지에 포함되지 않음) | `websiteKey`가 유효하지 않아요 | 페이지에서 sitekey를 다시 찾으세요(파라미터 찾기 가이드 참고). 동일한 요청은 캐시 기간 동안 이 오류를 바로 반환하며, 응답에 `cached: true`가 포함돼요 |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (캐시됨, 일시 중지에 포함되지 않음) | `websiteURL`의 도메인이 `websiteKey`와 일치하지 않아요 | `websiteURL`에는 캡차가 표시되는 페이지의 주소를 입력하세요 |
| `ERROR_INVALID_KEY_TYPE` (캐시됨, 일시 중지에 포함되지 않음) | sitekey가 다른 종류의 캡차에 속해요. 예를 들어 v3 키를 v2 작업 유형에 사용한 경우예요 | 먼저 캡차 유형을 확인한 뒤("캡차 유형 판별" 참고) 알맞은 작업 유형을 선택하세요. 보이지 않는 v2는 `isInvisible`을 설정하세요 |
| `ERROR_DOMAIN_NOT_ALLOWED` (캐시됨, 일시 중지에 포함되지 않음) | 이 사이트는 지원되지 않아요 | 같은 캡차에 대한 다른 작업 유형을 사용해 보거나 고객 지원에 문의하세요 |
| `ERROR_HIGH_DEMAND_DOMAIN` (자동 일시 중지에 포함) | 이 사이트는 지원되지 않아요 | 이 사이트의 작업 전송을 중단하고 고객 지원에 문의하세요 |
| `ERROR_FAILED_LOADING_WIDGET` | 입력한 파라미터로 캡차를 불러올 수 없어요 | `websiteURL`과 `websiteKey`를 확인하세요. 자체 프록시를 사용하는 작업 유형은 프록시가 대상 사이트에 접속할 수 있는지 확인하세요 |
### 이미지
| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (자동 일시 중지에 포함) | 이미지가 비어 있거나 너무 작아요 | Base64 데이터가 완전한지, `data:image/...;base64,` 접두사가 없는지 확인하세요 |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (자동 일시 중지에 포함) | 이미지가 너무 커요 | 이미지를 압축하거나 크기를 줄이세요. 전체 요청 본문은 6 MB를 넘을 수 없어요 |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (자동 일시 중지에 포함) | 이미지 형식이 지원되지 않거나, 이 작업 유형에서 처리할 수 없는 이미지예요. 한 번만 발생해도 키가 30분 동안 일시 중지돼요 | JPG 또는 PNG를 사용하고 이미지가 작업 유형과 맞는지 확인하세요. 예를 들어 reCAPTCHA 이미지 인식은 100x100, 300x300 또는 450x450 크기가 필요해요 |
| `ERROR_ILLEGAL_IMAGE` (자동 일시 중지에 포함) | 이미지 크기가 이 작업 유형의 요구 사항에 맞지 않아요 | 작업 유형 페이지의 설명에 따라 이미지 크기를 조정하세요 |
| `ERROR_PARSE_IMAGE_FAIL` | 이미지를 디코딩할 수 없어요. Base64가 잘렸거나 접두사가 붙어 있는 경우가 많아요 | Base64 인코딩을 확인하고 `data:` 접두사와 줄바꿈을 제거하세요 |
| `ERROR_UNKNOWN_QUESTION` | `question`이 잘못되었거나, 이 질문이 아직 지원되지 않아요 | 작업 유형 페이지의 질문 목록과 대조해 확인하세요. 지원되지 않는 질문은 고객 지원에 문의하세요. 새로운 질문은 보통 영업일 기준 3일 이내에 지원돼요 |
| `ERROR_UNKNOW_450x450_QUESTION` | 이 질문은 아직 4x4(450x450) 이미지를 지원하지 않아요 | 페이지에서 챌린지를 새로 고쳐 다른 질문을 받으세요 |
### 프록시
| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | 프록시가 연결을 거부했어요 | 프록시 주소, 포트, 프로토콜을 확인하고 외부 연결을 허용하는지 확인하세요(127.0.0.1 같은 로컬 주소는 사용할 수 없어요) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | 프록시 연결 시간이 초과되었어요 | 더 안정적인 프록시를 사용하세요 |
| `ERROR_PROXY_READ_TIMEOUT` | 프록시를 통한 데이터 읽기 시간이 초과되었어요 | 더 빠른 프록시를 사용하세요 |
| `ERROR_PROXY_BANNED` | 프록시를 사용할 수 없거나, 프록시 IP가 대상 사이트에서 차단되었어요 | 다른 프록시를 사용하세요 |
| `ERROR_PROXY_INCORRECT` | 프록시 파라미터 형식이 올바르지 않아요 | `proxyType`, `proxyAddress`, `proxyPort`(또는 `proxy` 문자열)의 형식을 확인하세요 |
| `ERROR_PROXY_TRANSPARENT` | 프록시가 투명 프록시라서 실제 IP가 노출돼요 | 익명(엘리트) 프록시로 바꾸세요 |
| `ERROR_PROXY_NOT_AUTHORISED` | 프록시 사용자 이름 또는 비밀번호가 올바르지 않아요 | `proxyLogin`과 `proxyPassword`(또는 `proxy` 문자열에 포함된 인증 정보)를 확인하세요 |
| `ERROR_PROXY_TLS_ERROR` | 프록시와의 TLS 핸드셰이크에 실패했어요. `proxyType`이 잘못된 경우가 많아요(예: http 프록시에 https를 설정한 경우) | 프록시 프로토콜을 확인하세요 |
| `ERROR_PROXY_CONNECTION_FAILED` | 프록시 서버에 연결할 수 없어요 | 프록시 주소와 포트를 확인하고 프록시가 정상 작동하는지 확인하세요 |
### 서버
| 오류 코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | 서비스를 일시적으로 사용할 수 없어요(코드 철자는 `UNAVALIABLE`이에요) | 잠시 후 다시 시도하세요. 계속 발생하면 고객 지원에 문의하세요 |
| `ERROR_INTERNAL_SERVER_ERROR` | 서버 내부 오류가 발생했어요 | 잠시 후 다시 시도하세요. 계속 발생하면 `taskId`와 함께 고객 지원에 문의하세요 |
| `ERROR_UNKNOWN` | 분류되지 않은 오류예요 | 잠시 후 다시 시도하세요. 계속 발생하면 `taskId`와 함께 고객 지원에 문의하세요 |
## 추가 필드
일부 오류의 응답에는 추가 필드가 포함돼요.
| 필드 | 나타나는 곳 | 설명 |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, 캐시된 오류 | 더 기다려야 하는 시간(초) |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | 일시 중지를 일으킨 오류 코드 |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | 일시 중지를 일으킨 요청의 유형, URL, sitekey. 원인을 찾을 때 활용하세요 |
| `cached` | 캐시된 오류 | `true`이면 캐시된 결과이고 실제로 인식하지 않았다는 뜻이에요 |
| `badRequest` | 캐시된 오류 | 캐시에 걸린 파라미터 |
| `limit` | `ERROR_THREADS_MAXIMUM` | 현재 동시 작업 수 상한 |
`errorDescription`의 언어 규칙은 [요청과 응답](https://docs.yescaptcha.com/ko/api/overview.md)을 참고하세요.
---
# 동시 작업 수 제한과 자동 일시 중지
> YesCaptcha의 동시 작업 수 제한(ERROR_THREADS_MAXIMUM, 포인트 차감 없음, 일시 중지에 포함되지 않음), 오류가 너무 많을 때의 자동 일시 중지(1분에 100회 발생하면 5분간 일시 중지, ERROR_IP_BLOCKED_5MIN), 잘못된 파라미터 캐시(cached)를 설명해요.
Source: https://docs.yescaptcha.com/ko/api/rate-limits/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/rate-limits/
모든 사용자의 캡차 인식 속도를 유지하기 위해 YesCaptcha에는 세 가지 보호 규칙이 있어요. 계정별로 **동시에 처리 중인 작업 수**를 제한하고(동시 작업 수 제한), 같은 `clientKey`에서 짧은 시간 안에 **오류가 너무 많이 발생하면 몇 분간 일시 중지**하고(자동 일시 중지), **이미 잘못된 것으로 판정된 파라미터**는 일정 시간 동안 원래 오류를 그대로 반환해요(잘못된 파라미터 캐시). 이 세 경우 모두 포인트가 차감되지 않아요.
## 동시 작업 수 제한
계정별, 작업 유형별로 같은 시각에 처리 중인 작업 수를 제한해요. 제한하는 것은 동시 작업 수이며, 분당 요청 수가 아니에요.
- `createTask`를 호출한 시점부터 그 호출이 반환될 때까지 작업은 “처리 중”으로 계산돼요. 이미지 인식 유형은 `createTask`에서 바로 결과를 반환하므로 **동시 작업 수 ≈ 초당 전송한 작업 수 × 작업 하나당 소요 시간**이에요. 예를 들어 작업당 0.5초, 초당 40개를 보내면 동시 작업 수는 약 20이에요.
- 같은 계정의 요청은 합산해서 계산해요. 작업 유형은 각각 따로 계산해요.
- 한도를 초과한 요청은 즉시 `ERROR_THREADS_MAXIMUM`을 반환하고, 응답의 `limit`은 현재 상한이에요. **포인트는 차감되지 않으며 자동 일시 중지에도 포함되지 않아요.**
- 인식 서버가 바쁠 때는 인식 시간을 가장 많이 사용한 계정의 해당 작업 유형 상한이 **일시적으로 절반으로 줄었다가 10분 후 자동으로 복구돼요.** 속도만 제한할 뿐 계정을 일시 중지하지는 않아요.
- 더 높은 한도가 필요하면 [고객 지원](https://docs.yescaptcha.com/ko/help/contact.md)에 문의하세요. 유형별 기본 한도가 확정되면 이 페이지와 [서비스 업데이트 기록](https://docs.yescaptcha.com/ko/changelog.md)에 공개할 예정이에요.
```json
{
"errorId": 1,
"errorCode": "ERROR_THREADS_MAXIMUM",
"errorDescription": "This account already has 30 tasks of this type in progress, which is the limit. Lower the concurrency and wait for pending requests to return before sending more; rejected requests are not charged and do not lead to a block.",
"limit": 30
}
```
(예시의 숫자는 참고용이에요.)
### 권장 방법
1. 초당 몇 개를 보낼지만 제어하지 말고, 세마포어(Semaphore)나 고정 크기 스레드 풀 등으로 “결과를 기다리는 동시 요청 수”를 프로그램에서 제한하세요.
2. `ERROR_THREADS_MAXIMUM`을 받으면 이미 보낸 요청이 반환될 때까지 기다린 후 새 요청을 보내거나, 1~2초 기다렸다가 다시 시도하세요. 즉시 반복해서 재시도하지 마세요.
3. 일괄 작업은 고르게 나눠서 보내고, 수천수만 개의 작업을 한꺼번에 보내지 마세요.
Python(asyncio) 예시예요.
```python
import asyncio
import os
import aiohttp
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15 # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)
async def solve(session, task):
async with sem: # at most LIMIT requests in progress at a time
result = {}
for attempt in range(5):
async with session.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
) as resp:
result = await resp.json()
if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
return result
await asyncio.sleep(1 + attempt) # over the limit: wait and retry
return result
```
## 자동 일시 중지
같은 `clientKey`에서 짧은 시간 안에 오류 요청이 대량으로 발생하면 작업 생성이 자동으로 일시 중지돼요.
| 발동 조건 | 일시 중지 시간 |
| --- | --- |
| 같은 1분(자연 분) 안에 아래에 나열된 오류가 누적 100회 발생 | 5분 |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` 1회 발생 | 30분 |
| 같은 1분(자연 분) 안에 “잘못된 파라미터 캐시”에 1,000회 적중 | 5분 |
일시 중지에 포함되는 오류:
- [`ERROR_REQUEST_FORMATS`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_REQUEST_FORMATS)
- [`ERROR_TASK_ABSENT`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_TASK_ABSENT)
- [`ERROR_TASK_NOT_SUPPORTED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_TASK_NOT_SUPPORTED)
- [`ERROR_KEY_DOES_NOT_EXIST`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_DOES_NOT_EXIST)
- [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_EXPIRED)
- [`ERROR_TASKID_INVALID`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_TASKID_INVALID)
- [`ERROR_SETTLEMENT_FAILED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_SETTLEMENT_FAILED)
- [`ERROR_HIGH_DEMAND_DOMAIN`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_HIGH_DEMAND_DOMAIN)
- [`ERROR_ZERO_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_ZERO_CAPTCHA_FILESIZE)
- [`ERROR_TOO_BIG_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_TOO_BIG_CAPTCHA_FILESIZE)
- [`ERROR_IMAGE_TYPE_NOT_SUPPORTED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_IMAGE_TYPE_NOT_SUPPORTED)
- [`ERROR_ILLEGAL_IMAGE`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_ILLEGAL_IMAGE)
계정의 동시 작업 수 초과로 반환되는 `ERROR_THREADS_MAXIMUM`(`limit` 필드 포함)은 포함되지 않아요. 인식 서비스가 바쁠 때 반환되는 같은 이름의 오류(`limit` 없음)는 포함돼요. 인식 실패(`ERROR_CAPTCHA_UNSOLVABLE`), 잔액 부족(`ERROR_ZERO_BALANCE`), 필수 필드 누락(`ERROR_REQUIRED_FIELDS`), 지원하지 않는 질문(`ERROR_UNKNOWN_QUESTION`) 등은 포함되지 않아요.
일시 중지 중에는 다음과 같아요.
- `createTask`와 `getBalance`에만 영향을 주며 `ERROR_IP_BLOCKED_5MIN`을 반환해요. `getTaskResult`는 영향을 받지 않아서, 일시 중지 전에 만든 작업의 결과는 평소처럼 조회할 수 있어요.
- 응답에 `retryAfter`(남은 시간, 초), `blockReason`(일시 중지를 일으킨 오류 코드), `blockDetail`(해당 요청의 유형, URL, sitekey)이 포함돼요. 이를 보고 프로그램을 수정하세요.
- 요청을 계속 보내도 일시 중지 시간이 늘어나지 않아요. 시간이 지나면 자동으로 복구되므로 고객 지원에 문의할 필요가 없어요.
- [yescaptcha.com](https://yescaptcha.com/) 대시보드에서 최근 24시간의 일시 중지 기록을 확인할 수 있어요.
```json
{
"errorId": 1,
"errorCode": "ERROR_IP_BLOCKED_5MIN",
"errorDescription": "...",
"retryAfter": 182,
"blockReason": "ERROR_TASK_NOT_SUPPORTED"
}
```
## 잘못된 파라미터 캐시
일부 오류는 요청 파라미터에 의해 결정되므로, 같은 파라미터로 다시 보내도 결과가 바뀌지 않아요.
- [`ERROR_RECAPTCHA_INVALID_SITEKEY`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_RECAPTCHA_INVALID_SITEKEY)
- [`ERROR_RECAPTCHA_INVALID_DOMAIN`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_RECAPTCHA_INVALID_DOMAIN)
- [`ERROR_INVALID_KEY_TYPE`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_INVALID_KEY_TYPE)
- [`ERROR_DOMAIN_NOT_ALLOWED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_DOMAIN_NOT_ALLOWED)
이런 오류는 자동 일시 중지에 포함되지 않고, 대신 사이트 전체에서 캐시돼요. 처음 판정된 후 2분간 캐시되고, 1시간 안에 다시 확인되면 10분간 캐시돼요. 캐시 기간 중에 같은 요청(같은 작업 유형과 `websiteKey`, 또는 같은 웹사이트 도메인)을 보내면 원래 오류를 바로 반환하고 포인트는 차감되지 않으며, 응답에 `"cached": true`, `retryAfter`(캐시 남은 시간, 초), `badRequest`(적중한 파라미터)가 포함돼요. `websiteKey`를 바로잡거나 작업 유형을 바꾸면 즉시 적용돼요.
## 동시 작업 수 제한과 자동 일시 중지의 차이
| | 동시 작업 수 제한 | 자동 일시 중지 |
| --- | --- | --- |
| 원인 | 동시에 처리 중인 작업이 너무 많음 | 짧은 시간 안에 오류 요청이 너무 많음 |
| 증상 | 초과한 요청만 거부, `ERROR_THREADS_MAXIMUM` | 해당 `clientKey`의 작업 생성이 일시 중지, `ERROR_IP_BLOCKED_5MIN` |
| 복구 | 처리가 끝난 요청이 있으면 바로 새 요청을 보낼 수 있음. 일시적으로 절반이 된 상한은 10분 후 복구 | 시간이 지나면 자동 복구 |
| 포인트 차감 | 없음 | 없음 |
---
# 작업 유형과 가격
> YesCaptcha의 모든 공개 작업 유형의 가격(포인트, 1,000포인트 = ¥1)과 반환 방식을 안내해요. reCAPTCHA, hCaptcha, Turnstile은 토큰을, Cloudflare 챌린지 페이지는 Cookie를, 이미지 영문·숫자 인식과 이미지 인식은 인식 결과를 반환해요.
Source: https://docs.yescaptcha.com/ko/tasks/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/
작업마다 유형별로 정해진 포인트가 차감돼요. 1,000포인트 = ¥1이고, 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요. 아래 표는 공개된 모든 작업 유형이며, 이름으로 검색할 수 있어요. 기계가 읽을 수 있는 버전: [/data/task-types.json](https://docs.yescaptcha.com/data/task-types.json).
| 캡차 | 작업 유형 | 가격 | 반환 방식 |
| --- | --- | --- | --- |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md) | `NoCaptchaTaskProxyless` | $2.25 / 1k; 15 포인트/작업 · ¥15 / 1k | 비동기 |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md) | `RecaptchaV2TaskProxyless` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md) | `NoCaptchaTask` 자체 프록시 | $2.25 / 1k; 15 포인트/작업 · ¥15 / 1k | 비동기 |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md) | `RecaptchaV2EnterpriseTaskProxyless` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 |
| [reCAPTCHA v2](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md) | `RecaptchaV2EnterpriseTask` 자체 프록시 | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxyless` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1S7` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1S9` | $5.25 / 1k; 35 포인트/작업 · ¥35 / 1k | 비동기 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md) | `RecaptchaV3EnterpriseTask` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 |
| [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md) | `RecaptchaV3EnterpriseTaskM1` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 |
| [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md) | `HCaptchaTaskProxyless` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 |
| [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md) | `HCaptchaTaskProxylessM1` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 |
| [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md) | `HCaptchaTask` 자체 프록시 | $2.25 / 1k; 15 포인트/작업 · ¥15 / 1k | 비동기 |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md) | `TurnstileTaskProxyless` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md) | `TurnstileTaskProxylessM1` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md) | `TurnstileTask` 자체 프록시 | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 |
| [Cloudflare 챌린지 페이지](https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge.md) | `CloudFlareTaskS2` 자체 프록시 | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 |
| [Cloudflare 챌린지 페이지](https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge.md) | `CloudFlareTaskS3` 자체 프록시 | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 |
| [이미지 텍스트 인식](https://docs.yescaptcha.com/ko/tasks/image-to-text.md) | `ImageToTextTaskOcrBase` | $0.30 / 1k; 2 포인트/작업 · ¥2 / 1k | 동기 |
| [이미지 텍스트 인식](https://docs.yescaptcha.com/ko/tasks/image-to-text.md) | `ImageToTextTaskMuggle` | $0.30 / 1k; 2 포인트/작업 · ¥2 / 1k | 동기 |
| [이미지 텍스트 인식](https://docs.yescaptcha.com/ko/tasks/image-to-text.md) | `ImageToTextTask` | $0.60 / 1k; 4 포인트/작업 · ¥4 / 1k | 비동기 |
| [이미지 텍스트 인식](https://docs.yescaptcha.com/ko/tasks/image-to-text.md) | `ImageToTextTaskM1` | $2.25 / 1k; 15 포인트/작업 · ¥15 / 1k | 비동기 |
| [reCAPTCHA v2 이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md) | `ReCaptchaV2Classification` | $0.90 / 1k; 6 포인트/작업 · ¥6 / 1k | 동기 |
| [hCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification.md) | `HCaptchaClassification` | $1.20 / 1k; 8 포인트/작업 · ¥8 / 1k | 동기 |
| [FunCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/funcaptcha-classification.md) | `FunCaptchaClassification` | $0.45 / 1k; 3 포인트/작업 · ¥3 / 1k | 동기 |
| [AWS WAF / bCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/aws-bcaptcha-classification.md) | `AwsClassification` | $1.20 / 1k; 8 포인트/작업 · ¥8 / 1k | 동기 |
| [AWS WAF / bCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/aws-bcaptcha-classification.md) | `bCaptchaClassification` | $1.20 / 1k; 8 포인트/작업 · ¥8 / 1k | 동기 |
미국 달러 가격은 US$1 ≈ ¥6.67(2026-10-27) 기준의 추정치예요. 작업은 포인트로 차감돼요. 위안화(CNY)로 충전하면 1,000포인트 = ¥1이고, 미국 달러(PayPal, 암호화폐)로 충전하면 결제 시점의 환율로 위안화로 환산한 뒤 포인트로 변환해요.
## 어떤 유형을 써야 할까요?
| 하려는 일 | 사용할 유형 | 반환 값 |
| --- | --- | --- |
| 이미지를 클릭하지 않고 토큰을 받아 바로 제출 | [reCAPTCHA v2](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md), [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md), [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md), [Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md) | 토큰, 비동기 |
| Cloudflare의 “잠시만 기다리십시오” 검사 페이지 통과 | [Cloudflare 챌린지 페이지](https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge.md) | Cookie, User-Agent, 페이지 내용, 비동기 |
| 브라우저에서 직접 이미지 클릭 | [reCAPTCHA v2 이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md), [hCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification.md), [FunCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/funcaptcha-classification.md), [AWS WAF / bCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/aws-bcaptcha-classification.md) | 클릭할 이미지 또는 위치, 동기 |
| 이미지 속 문자 인식 | [이미지 영문·숫자 인식](https://docs.yescaptcha.com/ko/tasks/image-to-text.md) | 텍스트, 대부분 동기 |
어떤 캡차인지 모르겠다면 [캡차 유형 판별하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)를 참고하세요.
## 이름 규칙
- **`Proxyless`**: YesCaptcha의 네트워크로 캡차를 불러오므로 프록시가 필요 없어요. 이름에 `Proxyless`가 없는 유형(예: `NoCaptchaTask`, `HCaptchaTask`)은 직접 준비한 프록시를 사용하며 프록시 필드를 전달해야 해요. 대상 웹사이트가 접속 IP를 검사하는 경우에 적합해요.
- **`M1` 같은 접미사**: 같은 캡차의 다른 경로예요. 파라미터는 같고 가격이 달라요. 하나의 통과율이 만족스럽지 않으면 다른 쪽으로 바꿔 보세요. 서로의 백업으로 쓸 수도 있어요.
- **`Classification`**: 이미지 인식이에요. 토큰이 아니라 클릭할 위치를 반환해요.
- **`Enterprise`**: reCAPTCHA Enterprise예요.
## 참고
- reCAPTCHA v2 이미지 인식은 이미지 크기에 따라 가격이 정해지고, hCaptcha 이미지 인식은 대상을 찾지 못하면 포인트가 차감되지 않아요. 자세한 내용은 각 페이지를 참고하세요.
- 가격은 이 페이지를 기준으로 해요. 작업을 생성할 때만 포인트가 차감되고, 결과 조회는 차감되지 않아요. 과금 규칙은 [과금과 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.
---
# reCAPTCHA v2
> YesCaptcha로 reCAPTCHA v2(일반, 인비저블, Enterprise)의 토큰을 받아요. 작업 유형과 가격, 요청 파라미터, curl/Python/Node.js 예제와 반환 결과를 안내해요.
Source: https://docs.yescaptcha.com/ko/tasks/recaptcha-v2/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/recaptcha-v2/
reCAPTCHA v2 작업은 토큰(`gRecaptchaResponse`)을 반환해요. 이 토큰을 대상 웹사이트에 제출하면 이미지를 클릭하지 않고도 검증을 통과할 수 있어요. 가장 많이 쓰는 `NoCaptchaTaskProxyless`는 작업당 15 포인트 (≈ $2.25 / 1k)이고 비동기로 결과를 반환해요. 먼저 `createTask`로 작업을 만들고, 5초마다 `getTaskResult`를 호출해 결과를 가져와요. 인식에 실패하거나 시간이 초과된 작업은 포인트가 자동으로 환불돼요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
요청 본문은 JSON이고, `clientKey`로 인증해요. `clientKey`는 [yescaptcha.com](https://yescaptcha.com/) 대시보드에서 복사하세요. 작업을 만든 엔드포인트와 같은 엔드포인트에서 결과를 조회해야 해요.
## 사용 시기
- 웹페이지에 “로봇이 아닙니다”(I’m not a robot) 체크박스가 있어요: 일반 버전이에요.
- 체크박스가 없고, 제출 버튼을 클릭한 뒤에야 이미지 문제가 나타나요: 인비저블 버전이에요. `"isInvisible": true`를 추가하세요.
- 웹페이지가 `recaptcha/enterprise.js`를 불러오거나 요청 주소에 `enterprise`가 들어 있어요: Enterprise 버전이에요. 이름에 `Enterprise`가 들어간 유형을 사용하세요.
어떤 버전인지 확실하지 않다면 [캡차 유형 확인하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)를 참고하세요. 토큰 방식의 통과율이 만족스럽지 않다면 [reCAPTCHA v2 이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)을 사용할 수 있어요. API가 어떤 이미지를 클릭해야 하는지 알려 주면, 브라우저에서 직접 클릭해요.
## 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `NoCaptchaTaskProxyless` | $2.25 / 1k; 15 포인트/작업 · ¥15 / 1k | 비동기 | |
| `RecaptchaV2TaskProxyless` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 | NoCaptchaTaskProxyless와 파라미터는 같고 경로만 달라요. 서로 대체용으로 사용할 수 있어요 |
| `NoCaptchaTask` | $2.25 / 1k; 15 포인트/작업 · ¥15 / 1k | 비동기 | 자체 프록시 |
| `RecaptchaV2EnterpriseTaskProxyless` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 | |
| `RecaptchaV2EnterpriseTask` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 | 자체 프록시 |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
- `NoCaptchaTaskProxyless`와 `RecaptchaV2TaskProxyless`는 파라미터가 같고 경로만 달라요. 하나의 통과율이 만족스럽지 않다면 다른 하나를 사용해 보세요.
- 이름에 `Proxyless`가 없는 유형(`NoCaptchaTask`, `RecaptchaV2EnterpriseTask`)은 직접 준비한 프록시로 캡차를 불러와요. `proxyType`, `proxyAddress`, `proxyPort` 등의 필드를 전달해야 해요. 대상 웹사이트가 접속 IP를 확인할 때 사용하세요.
## 요청 파라미터
`createTask`의 `task` 객체:
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `websiteURL` | string | 예 | 캡차가 표시되는 페이지의 전체 URL이에요. 캡차 제공업체의 도메인이 아니라 캡차가 보이는 사이트를 입력하세요 |
| `websiteKey` | string | 예 | 사이트 키(sitekey)예요. 페이지 소스나 네트워크 요청에서 찾을 수 있고, 보통 바뀌지 않아요 |
| `isInvisible` | boolean | 아니요 | 보이지 않는(invisible) 버전이면 true로 설정하세요. 그렇지 않으면 생략하세요 |
| `proxyType` | string | 일부 유형 | 프록시 프로토콜이에요: `http`, `https`, `socks4`, `socks5` (NoCaptchaTask, RecaptchaV2EnterpriseTask에서 필수) |
| `proxyAddress` | string | 일부 유형 | 프록시 IP 주소 또는 호스트 이름이에요. 127.0.0.1이나 192.168.x.x 같은 로컬 또는 사설 주소는 저희 서버가 접근할 수 없어서 사용할 수 없어요 (NoCaptchaTask, RecaptchaV2EnterpriseTask에서 필수) |
| `proxyPort` | integer | 일부 유형 | 프록시 포트 (NoCaptchaTask, RecaptchaV2EnterpriseTask에서 필수) |
| `proxyLogin` | string | 아니요 | 프록시 사용자 이름(프록시에 인증이 필요한 경우) (NoCaptchaTask, RecaptchaV2EnterpriseTask 전용) |
| `proxyPassword` | string | 아니요 | 프록시 비밀번호(프록시에 인증이 필요한 경우) (NoCaptchaTask, RecaptchaV2EnterpriseTask 전용) |
| `userAgent` | string | 아니요 | 브라우저 User-Agent예요. 결과에 `userAgent`가 있으면 토큰을 제출할 때 그 값을 사용하세요 (NoCaptchaTask, RecaptchaV2EnterpriseTask 전용) |
| `enterprisePayload` | object | 아니요 | Enterprise 버전의 추가 파라미터예요. 예를 들어 reCAPTCHA Enterprise의 `s` 값은 `{"s": "..."}` 형식이에요. 페이지에서 사용하지 않으면 생략하세요 (RecaptchaV2EnterpriseTaskProxyless, RecaptchaV2EnterpriseTask 전용) |
`websiteURL`과 `websiteKey`를 찾는 방법은 [reCAPTCHA 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md)를 참고하세요.
## 요청 예제
Google 공식 데모 페이지를 예로 들어요:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
작업 생성, 5초마다 조회, 토큰 출력까지 포함한 전체 코드예요. 실행하기 전에 ClientKey를 환경 변수 `YESCAPTCHA_CLIENT_KEY`에 넣으세요:
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
import requests
API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"] # Read the clientKey from an environment variable
def call(method, payload):
r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
data = r.json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def solve(task):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable
async function call(method, payload) {
const res = await fetch(`${API}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
return data;
}
async function solve(task) {
const { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "NoCaptchaTaskProxyless",
websiteURL: "https://www.google.com/recaptcha/api2/demo",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```
Enterprise 버전이고 웹페이지가 reCAPTCHA에 `s` 값을 전달한다면 `enterprisePayload`에 넣으세요:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"enterprisePayload": {
"s": "S_VALUE_FROM_THE_PAGE"
}
}
}
```
직접 준비한 프록시를 사용하는 경우:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTask",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"proxyType": "http",
"proxyAddress": "proxy.example.com",
"proxyPort": 8080,
"proxyLogin": "user",
"proxyPassword": "pass"
}
}
```
## 반환 결과
`createTask`는 작업 ID를 반환해요:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
이 ID로 `getTaskResult`를 호출하세요. 아직 처리 중이면 `{"errorId": 0, "status": "processing"}`가 반환되니 5초 후에 다시 조회하세요. 완료되면 다음과 같이 반환돼요:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `gRecaptchaResponse` | string | 대상 웹사이트에 제출할 토큰이에요. 1회만 사용할 수 있고 약 120초 동안 유효하며, 60초 안에 사용하는 것을 권장해요 |
작업 하나는 최대 약 110초 동안 처리되고, 시간이 초과되면 `ERROR_TASK_TIMEOUT`이 반환되며 포인트가 환불돼요. 오류가 발생하면 `errorId`가 1이 되니 `errorCode`에 따라 처리하세요. 자세한 내용은 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요. 토큰을 받은 뒤 제출하는 방법은 [토큰으로 reCAPTCHA 통과하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md)를 참고하세요.
> **팁:** 토큰은 일회용이고 약 120초 동안 유효해요. 받은 뒤 60초 안에 제출하는 것을 권장해요.
## 자주 묻는 질문
### 같은 웹사이트인데 토큰이 통과될 때도 있고 안 될 때도 있는 이유가 뭔가요?
통과 여부는 대상 웹사이트가 판단해요. 웹사이트는 검증할 때마다 점수를 매기고 기준을 설정하는데, 이 기준은 언제든 바뀔 수 있어요. 그래서 통과율은 웹사이트마다 다르고, 모든 토큰이 통과되는 것은 아니에요. 같은 종류의 다른 작업 유형으로 통과율을 비교해 보거나 [이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)으로 바꿔 보세요.
### 토큰은 얼마 동안 유효한가요?
일회용이고 약 120초 동안 유효해요. 받은 뒤 60초 안에 제출하는 것을 권장해요. 유효 기간은 Google이 정해요.
### 인식에 실패하면 포인트가 차감되나요?
차감되지 않아요. `ERROR_CAPTCHA_UNSOLVABLE`을 반환하거나 시간이 초과된 작업은 포인트가 자동으로 환불돼요. 자세한 내용은 [과금과 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.
## 관련 튜토리얼
- [캡차 유형 확인하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)
- [reCAPTCHA 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md)
- [토큰으로 reCAPTCHA 통과하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md)
- [reCAPTCHA v2 이미지 인식으로 클릭 시뮬레이션하기(Selenium)](https://docs.yescaptcha.com/ko/guides/recaptcha-click-selenium.md)
---
# reCAPTCHA v3
> YesCaptcha로 reCAPTCHA v3(엔터프라이즈 포함) 토큰을 받는 방법이에요. pageAction 입력 방법, 고정 점수 0.7·0.9 유형, 작업 유형과 가격, 파라미터, 예시, 반환 결과를 설명해요.
Source: https://docs.yescaptcha.com/ko/tasks/recaptcha-v3/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/recaptcha-v3/
reCAPTCHA v3에는 체크박스도 이미지도 없고, 웹 페이지가 백그라운드에서 방문자에게 점수를 매겨요. YesCaptcha는 대상 사이트에 제출할 수 있는 토큰(`gRecaptchaResponse`)을 반환해요. `RecaptchaV3TaskProxyless`는 작업당 20 포인트 (≈ $3.00 / 1k)이며 비동기로 결과를 반환해요. 먼저 `createTask`를 호출하고, 이후 5초마다 `getTaskResult`를 호출하세요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
요청 본문은 JSON이며 `clientKey`로 인증해요. 작업을 만든 엔드포인트와 같은 엔드포인트에서 결과를 조회하세요.
## 사용 시점
- 페이지 소스에 `grecaptcha.execute(...)`가 있거나 `recaptcha/api.js?render=사이트 키`를 로드하는 경우: 일반 v3예요.
- `grecaptcha.enterprise.execute(...)`를 호출하거나 `recaptcha/enterprise.js`를 로드하는 경우: 엔터프라이즈 v3예요. `RecaptchaV3EnterpriseTask` 또는 `RecaptchaV3EnterpriseTaskM1`을 사용하세요.
판별 방법은 [캡차 유형 판별하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)를 참고하세요.
## 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `RecaptchaV3TaskProxyless` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 | |
| `RecaptchaV3TaskProxylessM1` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 | |
| `RecaptchaV3TaskProxylessM1S7` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 | 점수 0.7을 요청해요. 추가 파라미터는 필요 없어요 |
| `RecaptchaV3TaskProxylessM1S9` | $5.25 / 1k; 35 포인트/작업 · ¥35 / 1k | 비동기 | 점수 0.9를 요청해요. 추가 파라미터는 필요 없어요 |
| `RecaptchaV3EnterpriseTask` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 | |
| `RecaptchaV3EnterpriseTaskM1` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 | |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
- `RecaptchaV3TaskProxyless`와 `RecaptchaV3TaskProxylessM1`은 파라미터가 같고 경로만 달라서, 서로 예비로 쓸 수 있어요.
- 대상 사이트가 높은 점수를 요구하면 고정 점수인 `RecaptchaV3TaskProxylessM1S7`(0.7) 또는 `RecaptchaV3TaskProxylessM1S9`(0.9)를 사용하세요. 추가 파라미터는 필요 없어요.
## 요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `websiteURL` | string | 예 | 캡차가 표시되는 페이지의 전체 URL이에요. 캡차 제공업체의 도메인이 아니라 캡차가 보이는 사이트를 입력하세요 |
| `websiteKey` | string | 예 | 사이트 키(sitekey)예요. 페이지 소스나 네트워크 요청에서 찾을 수 있고, 보통 바뀌지 않아요 |
| `pageAction` | string | 아니요 | reCAPTCHA v3의 action 값이에요. 페이지가 `grecaptcha.execute`에 전달하는 값과 같아야 해요. 다르면 토큰이 거부될 수 있어요 |
`pageAction`은 페이지가 `grecaptcha.execute(사이트 키, {action: '...'})`를 호출할 때 전달하는 `action`과 같아야 해요. 잘못 입력하면 사이트가 토큰을 거부할 수 있어요. 찾는 방법은 [reCAPTCHA 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md)를 참고하세요.
## 요청 예시
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
import requests
API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"] # Read the clientKey from an environment variable
def call(method, payload):
r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
data = r.json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def solve(task):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable
async function call(method, payload) {
const res = await fetch(`${API}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
return data;
}
async function solve(task) {
const { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "RecaptchaV3TaskProxyless",
websiteURL: "https://example.com/login",
websiteKey: "SITE_KEY_OF_THE_PAGE",
pageAction: "login",
});
console.log(solution.gRecaptchaResponse);
```
`websiteURL`, `websiteKey`, `pageAction`을 대상 사이트의 값으로 바꾸세요.
## 반환 결과
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `gRecaptchaResponse` | string | 대상 웹사이트에 제출할 토큰이에요. 1회만 사용할 수 있고 약 120초 동안 유효하며, 60초 안에 사용하는 것을 권장해요 |
처리 중에는 `{"errorId": 0, "status": "processing"}`이 반환돼요. 5초 후에 다시 조회하세요. 오류가 발생하면 `errorCode`에 따라 처리하세요. 자세한 내용은 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요. 토큰을 받은 뒤 제출하는 방법은 [토큰으로 reCAPTCHA 통과하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md)를 참고하세요.
## 자주 묻는 질문
### 왜 토큰이 사이트에서 거부될 때가 있나요?
v3는 대상 사이트가 점수를 보고 판단하며, 사이트가 설정한 기준은 언제든 바뀔 수 있어서 모든 토큰이 통과하는 것은 아니에요. `pageAction`이 올바른지 확인하세요. 사이트가 높은 점수를 요구하면 `M1S7`, `M1S9`를 사용해 보세요. 같은 계열의 다른 유형과 비교해 볼 수도 있어요.
### 엔터프라이즈 v3는 어떻게 입력하나요?
일반 버전과 똑같이 `websiteURL`, `websiteKey`, `pageAction`을 입력하고, 유형만 `RecaptchaV3EnterpriseTask` 또는 `RecaptchaV3EnterpriseTaskM1`로 바꾸세요.
### 토큰은 얼마나 오래 유효한가요?
일회용이며 약 120초 동안 유효해요. 60초 이내에 제출하는 것을 권장해요.
## 관련 가이드
- [캡차 유형 판별하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)
- [reCAPTCHA 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md) (`pageAction` 찾는 방법 포함)
- [토큰으로 reCAPTCHA 통과하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md)
---
# hCaptcha
> YesCaptcha로 hCaptcha 토큰을 받는 방법이에요. HCaptchaTaskProxyless, HCaptchaTaskProxylessM1, 자체 프록시를 쓰는 HCaptchaTask, userAgent와 rqdata 입력 방법, 반환된 respKey 사용법을 설명해요.
Source: https://docs.yescaptcha.com/ko/tasks/hcaptcha/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/hcaptcha/
hCaptcha 작업은 토큰(`gRecaptchaResponse`)을 반환해요. 이 토큰을 반환된 `userAgent`(경우에 따라 `respKey`도 함께)와 같이 대상 웹사이트에 제출하면 검증을 통과할 수 있어요. `HCaptchaTaskProxyless`는 작업당 30 포인트 (≈ $4.50 / 1k), 자체 프록시를 쓰는 `HCaptchaTask`는 작업당 15 포인트 (≈ $2.25 / 1k)이고, 둘 다 비동기예요. 먼저 `createTask`를 호출한 뒤 5초마다 `getTaskResult`를 호출하세요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
요청 본문은 JSON이고, `clientKey`로 인증해요. 작업을 만든 엔드포인트와 같은 엔드포인트에서 결과를 조회하세요.
## 사용 상황
웹페이지에 hCaptcha의 “사람입니다” 체크박스가 있거나 hCaptcha 이미지 문제가 나타나는 경우예요. 토큰을 받아 바로 제출하려면 이 페이지의 작업 유형을 사용하세요. 브라우저에서 직접 이미지를 클릭하려면 [hCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification.md)을 사용하세요.
> **참고:** hCaptcha 통과율은 웹사이트마다 크게 달라요. 먼저 소량으로 테스트하는 것을 권장해요.
## 작업 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `HCaptchaTaskProxyless` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 | |
| `HCaptchaTaskProxylessM1` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 | HCaptchaTaskProxyless와 파라미터는 같고 경로만 달라요. 서로 대체용으로 사용할 수 있어요 |
| `HCaptchaTask` | $2.25 / 1k; 15 포인트/작업 · ¥15 / 1k | 비동기 | 자체 프록시 |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
- `HCaptchaTaskProxyless`와 `HCaptchaTaskProxylessM1`은 파라미터가 같고 경로만 달라요. 서로 대체용으로 쓸 수 있어요.
- `HCaptchaTask`는 직접 준비한 프록시로 캡차를 불러와요. 프록시 필드를 전달해야 하며, 대상 웹사이트가 접속 IP를 검사할 때 사용하세요.
## 요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `websiteURL` | string | 예 | 캡차가 표시되는 페이지의 전체 URL이에요. 캡차 제공업체의 도메인이 아니라 캡차가 보이는 사이트를 입력하세요 |
| `websiteKey` | string | 예 | hCaptcha 사이트 키(sitekey)예요. 보통 UUID 형식이에요 |
| `userAgent` | string | 아니요 | 브라우저 User-Agent예요. 입력하는 것을 권장하지만 `GET https://api.yescaptcha.com/useragent`가 반환한 값만 사용할 수 있어요. 토큰을 제출할 때는 결과의 `userAgent`를 사용하세요 |
| `isInvisible` | boolean | 아니요 | 보이지 않는(invisible) 버전이면 true로 설정하세요. 그렇지 않으면 생략하세요 |
| `rqdata` | string | 아니요 | Enterprise hCaptcha의 rqdata예요. 일부 사이트에서 필요하고, 보통 캡차를 불러오는 요청에서 찾을 수 있어요 |
| `proxyType` | string | 일부 유형 | 프록시 프로토콜이에요: `http`, `https`, `socks4`, `socks5` (HCaptchaTask에서 필수) |
| `proxyAddress` | string | 일부 유형 | 프록시 IP 주소 또는 호스트 이름이에요. 127.0.0.1이나 192.168.x.x 같은 로컬 또는 사설 주소는 저희 서버가 접근할 수 없어서 사용할 수 없어요 (HCaptchaTask에서 필수) |
| `proxyPort` | integer | 일부 유형 | 프록시 포트 (HCaptchaTask에서 필수) |
| `proxyLogin` | string | 아니요 | 프록시 사용자 이름(프록시에 인증이 필요한 경우) (HCaptchaTask 전용) |
| `proxyPassword` | string | 아니요 | 프록시 비밀번호(프록시에 인증이 필요한 경우) (HCaptchaTask 전용) |
- `websiteURL`에는 캡차가 나타나는 웹페이지를 입력하세요. hcaptcha.com이 **아니에요**.
- `userAgent`는 입력하는 것을 권장해요. [/useragent](https://docs.yescaptcha.com/ko/api/useragent.md)가 반환한 값만 사용할 수 있어요.
- `rqdata`: 엔터프라이즈 버전 hCaptcha(예: 일부 소셜, 채팅 웹사이트)에서 요구해요. 보통 캡차를 불러오는 요청에서 찾을 수 있어요. 일반 웹사이트에서는 전달하지 않아요.
파라미터를 찾는 방법은 [hCaptcha 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-hcaptcha-parameters.md)를 참고하세요.
## 요청 예시
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
import requests
API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"] # Read the clientKey from an environment variable
def call(method, payload):
r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
data = r.json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def solve(task):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable
async function call(method, payload) {
const res = await fetch(`${API}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
return data;
}
async function solve(task) {
const { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "HCaptchaTaskProxyless",
websiteURL: "https://accounts.hcaptcha.com/demo",
websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
});
console.log(solution.gRecaptchaResponse);
```
자체 프록시를 사용하는 경우:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaTask",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
"proxyType": "http",
"proxyAddress": "proxy.example.com",
"proxyPort": 8080,
"proxyLogin": "user",
"proxyPassword": "pass"
}
}
```
## 반환 결과
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
"respKey": "E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
}
```
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `gRecaptchaResponse` | string | 대상 웹사이트에 제출할 토큰이에요. 1회만 사용할 수 있고 약 120초 동안 유효하며, 60초 안에 사용하는 것을 권장해요 |
| `userAgent` | string | 토큰을 발급받을 때 사용한 User-Agent예요. 토큰을 제출할 때 이 값을 사용하세요. 보낸 값과 다르면 이 값이 우선해요 |
| `respKey` | string | 일부 웹사이트에서 토큰과 함께 제출해야 하는 값이에요. 값이 있으면 함께 제출하세요 |
제출할 때는 다음 순서로 진행하세요.
1. 토큰을 웹페이지의 `h-captcha-response` 필드(`g-recaptcha-response` 필드가 있으면 거기에도)에 넣거나, 대상 웹사이트 API가 요구하는 필드에 넣으세요.
2. 제출 요청을 보낼 때 User-Agent는 반환된 `userAgent`를 사용하세요.
3. `respKey`가 반환되었다면 웹사이트의 요구에 따라 함께 제출하세요.
처리 중이면 `{"errorId": 0, "status": "processing"}`가 반환돼요. 5초 후에 다시 조회하세요. 오류가 발생하면 `errorCode`에 따라 처리하세요. [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.
## 자주 묻는 질문
### 통과율이 왜 일정하지 않나요?
hCaptcha는 웹사이트 설정, 접속 IP, 브라우저 환경을 바탕으로 판단하기 때문에 통과율이 웹사이트마다 달라요. 반환된 `userAgent`를 사용했는지 확인하세요. IP에 민감한 웹사이트에는 자체 프록시를 쓰는 `HCaptchaTask`를 사용하고, 제출할 때도 같은 프록시를 거치세요. `HCaptchaTaskProxylessM1`으로 바꿔서 비교해 볼 수도 있어요.
### 토큰은 얼마 동안 유효한가요?
한 번만 사용할 수 있고, 약 120초 동안 유효해요. 받은 뒤 가능한 한 빨리 제출하세요.
## 관련 튜토리얼
- [hCaptcha 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-hcaptcha-parameters.md)
- [hCaptcha 이미지 인식으로 클릭 시뮬레이션(Selenium)](https://docs.yescaptcha.com/ko/guides/hcaptcha-click-selenium.md)
---
# Cloudflare Turnstile
> YesCaptcha로 Cloudflare Turnstile 토큰을 받아요. TurnstileTaskProxyless, TurnstileTaskProxylessM1, 자체 프록시를 쓰는 TurnstileTask의 파라미터, 예제, 반환 결과와 Cloudflare 챌린지 페이지와의 차이를 설명해요.
Source: https://docs.yescaptcha.com/ko/tasks/turnstile/ · Last verified: 2026-10-21
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/turnstile/
Cloudflare Turnstile 작업은 토큰(`token`)을 반환해요. 이 토큰을 대상 웹사이트에 제출하면 인증을 통과할 수 있어요. `TurnstileTaskProxyless`는 작업당 25 포인트 (≈ $3.75 / 1k)이고, 비동기로 결과를 반환해요. 먼저 `createTask`를 호출한 뒤 5초마다 `getTaskResult`를 폴링하세요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
요청 본문은 JSON이고, `clientKey`로 인증해요. 작업을 생성한 엔드포인트와 같은 엔드포인트에서 결과를 조회하세요.
## 사용 시기
웹페이지의 폼 안에 Cloudflare 인증 위젯(“사람인지 확인”)이 포함되어 있고, 페이지가 `challenges.cloudflare.com/turnstile` 스크립트를 로드하는 경우예요.
페이지 전체가 Cloudflare에 가로막혀 “잠시만 기다리십시오…”, “브라우저를 확인하는 중”이 표시된다면 Turnstile이 아니라 Cloudflare 챌린지 페이지예요. 이 경우에는 [Cloudflare 챌린지 페이지](https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge.md)를 사용하세요. 구분 방법은 [캡차 유형 판별](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)에서 확인할 수 있어요.
## 작업 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `TurnstileTaskProxyless` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 | |
| `TurnstileTaskProxylessM1` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 | |
| `TurnstileTask` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 | 자체 프록시 |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
- `TurnstileTaskProxyless`와 `TurnstileTaskProxylessM1`은 파라미터가 같고 경로만 달라서 서로 대체용으로 쓸 수 있어요.
- `TurnstileTask`는 직접 준비한 프록시로 캡차를 로드해요. 프록시 필드를 함께 전달해야 해요.
## 요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `websiteURL` | string | 예 | 캡차가 표시되는 페이지의 전체 URL이에요. 캡차 제공업체의 도메인이 아니라 캡차가 보이는 사이트를 입력하세요 |
| `websiteKey` | string | 예 | Turnstile 사이트 키(sitekey)예요. 보통 0x로 시작해요 |
| `pageAction` | string | 아니요 | 페이지가 Turnstile에 전달하는 `action`이에요(`turnstile.render`의 옵션 또는 위젯 요소의 `data-action`). 예: `login`. 대부분의 경우 필요하지 않아요. 작업이 계속 실패할 때만 추가하세요 |
| `data` | string | 아니요 | 페이지가 Turnstile에 전달하는 `cData`예요(`turnstile.render`의 옵션 또는 위젯 요소의 `data-cdata`). 예: `c0bd4b36-7419-4e18-83c6-378699f2a9a2`. 대부분의 경우 필요하지 않아요. 작업이 계속 실패할 때만 추가하세요 |
| `proxyType` | string | 일부 유형 | 프록시 프로토콜이에요: `http`, `https`, `socks4`, `socks5` (TurnstileTask에서 필수) |
| `proxyAddress` | string | 일부 유형 | 프록시 IP 주소 또는 호스트 이름이에요. 127.0.0.1이나 192.168.x.x 같은 로컬 또는 사설 주소는 저희 서버가 접근할 수 없어서 사용할 수 없어요 (TurnstileTask에서 필수) |
| `proxyPort` | integer | 일부 유형 | 프록시 포트 (TurnstileTask에서 필수) |
| `proxyLogin` | string | 아니요 | 프록시 사용자 이름(프록시에 인증이 필요한 경우) (TurnstileTask 전용) |
| `proxyPassword` | string | 아니요 | 프록시 비밀번호(프록시에 인증이 필요한 경우) (TurnstileTask 전용) |
| `userAgent` | string | 아니요 | 브라우저 User-Agent예요. 결과에 `userAgent`가 있으면 토큰을 제출할 때 그 값을 사용하세요 (TurnstileTask 전용) |
`websiteKey`는 보통 `0x`로 시작해요. 찾는 방법은 [Turnstile 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-turnstile-parameters.md)를 참고하세요.
### 통과하지 못할 때: pageAction과 data
대부분은 `websiteURL`과 `websiteKey`만 전달하면 충분하고, 이 두 파라미터는 필요하지 않아요. `websiteURL`과 `websiteKey`가 모두 맞는데도 작업이 통과하지 못한다면, 웹페이지가 Turnstile을 호출할 때 `action`과 `cData`를 전달하는지 확인하세요. `turnstile.render`의 파라미터이거나 인증 위젯 요소의 `data-action`, `data-cdata`예요. 있다면 그대로 함께 전달하세요.
- `pageAction`: 웹페이지의 `action` 값이에요. 예: `login`
- `data`: 웹페이지의 `cData` 값이에요. 예: `c0bd4b36-7419-4e18-83c6-378699f2a9a2`
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY",
"pageAction": "login",
"data": "c0bd4b36-7419-4e18-83c6-378699f2a9a2"
}
}
```
## 요청 예제
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
import requests
API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"] # Read the clientKey from an environment variable
def call(method, payload):
r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
data = r.json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def solve(task):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY",
})
print(solution["token"])
```
**Node.js**
solve.mjs
```js
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable
async function call(method, payload) {
const res = await fetch(`${API}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
return data;
}
async function solve(task) {
const { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "TurnstileTaskProxyless",
websiteURL: "https://example.com/login",
websiteKey: "0x4AAAAAAA_SITE_KEY",
});
console.log(solution.token);
```
`websiteURL`과 `websiteKey`를 대상 웹사이트의 값으로 바꾸세요.
## 반환 결과
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.ufq5RgSVZd11DPSX1brdrxnEs28KcVlKj2ORchqxSy2q9yAW6ciq3hriXDF4x...",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
}
}
```
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `token` | string | 대상 웹사이트에 제출할 토큰이에요. 1회만 사용할 수 있으니 가능한 한 빨리 사용하세요 |
| `userAgent` | string | 토큰을 발급받을 때 사용한 User-Agent예요. 토큰을 제출할 때 이 값을 사용하세요. 보낸 값과 다르면 이 값이 우선해요 |
`token`을 웹페이지의 `cf-turnstile-response` 필드(또는 대상 웹사이트 API가 요구하는 필드)에 넣어 제출하세요. 제출 요청의 User-Agent는 반환된 `userAgent`를 사용하세요.
처리 중일 때는 `{"errorId": 0, "status": "processing"}`가 반환돼요. 5초 후에 다시 조회하세요. 오류가 발생하면 `errorCode`에 따라 처리하세요. 자세한 내용은 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.
## 자주 묻는 질문
### 토큰은 얼마 동안 유효한가요?
일회용이에요. 받은 뒤 가능한 한 빨리 제출하세요. Turnstile 토큰은 보통 몇 분 안에 만료되며, 만료 시점은 Cloudflare가 결정해요.
### 제출했는데도 웹사이트에서 통과되지 않아요
`websiteURL`이 인증 위젯이 나타나는 페이지인지, `websiteKey`가 올바른지 확인하고, 제출할 때 반환된 `userAgent`를 사용하세요. 웹페이지가 `action`과 `cData`를 전달한다면 `pageAction`과 `data`로 함께 전달하세요. 위의 [통과하지 못할 때](#%ED%99%95%EC%A0%95%EB%90%98%EC%A7%80-%EC%95%8A%EC%9D%8C)를 참고하세요. 웹사이트가 IP도 함께 검사한다면 `TurnstileTask`를 사용하고, 제출할 때도 같은 프록시를 거치세요.
## 관련 가이드
- [캡차 유형 판별](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)
- [Turnstile 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-turnstile-parameters.md)
---
# Cloudflare 챌린지 페이지
> YesCaptcha로 Cloudflare의 "잠시만 기다리세요" 확인 페이지(Cloudflare 챌린지 페이지)를 통과하고 cf_clearance 등 쿠키, User-Agent, 웹페이지 내용을 받아요. CloudFlareTaskS2와 CloudFlareTaskS3의 파라미터, 프록시 요구 사항, 반환 결과, 결과 사용 방법, 자주 발생하는 오류를 설명해요.
Source: https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/cloudflare-challenge/
Cloudflare 챌린지 페이지는 사이트 전체를 Cloudflare가 가로막고 “잠시만 기다리세요…”, “브라우저를 확인하는 중”을 표시하는 확인 페이지예요. YesCaptcha는 사용자가 제공한 프록시로 페이지를 열어 확인을 통과한 뒤, `cf_clearance` 등 쿠키, 당시 사용한 User-Agent, 요청 헤더, 응답 헤더, 통과 후의 웹페이지 HTML을 반환해요. `CloudFlareTaskS2`는 작업당 25 포인트 (≈ $3.75 / 1k), `CloudFlareTaskS3`는 작업당 20 포인트 (≈ $3.00 / 1k)예요. 두 유형은 파라미터, 반환 결과, 효과가 모두 같고 가격만 달라요. 비동기로 결과를 반환하며, 작업 하나는 보통 6~35초가 걸리고 사이트마다 차이가 커요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
## 사용 상황
- 페이지 소스에 `__cf_chl_rt_tk` 또는 `cdn-cgi/challenge-platform`이 있고 제목이 `Just a moment...` / “잠시만 기다리세요”예요. 이 경우가 Cloudflare 챌린지 페이지예요. 확인 페이지에서 “사람인지 확인” 체크박스를 눌러야 하는 경우도 이 페이지에서 다뤄요.
- 폼 안에 Cloudflare 인증 위젯만 삽입되어 있다면 [Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md)이므로 이 페이지를 쓰지 않아요.
- requests 같은 라이브러리로 요청하면 403과 “Just a moment…“가 반환되지만 브라우저에서는 바로 열려요. 대부분 TLS 핑거프린트 때문에 차단된 거예요. 브라우저의 TLS 핑거프린트를 흉내 내는 라이브러리(예: curl\_cffi)로 바꾸면 요청할 수 있고, 챌린지 통과는 필요 없어요.
## 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `CloudFlareTaskS2` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 | 자체 프록시 |
| `CloudFlareTaskS3` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 | 자체 프록시 |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
## 요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `websiteURL` | string | 예 | 챌린지에 막힌 페이지의 전체 URL이에요. `http://` 또는 `https://`로 시작하는 공개 URL이어야 해요. 사설 IP 주소와 `localhost` 같은 로컬 또는 내부 호스트 이름은 거부돼요 |
| `proxy` | string | 예 | 문자열 하나로 된 프록시예요: `http://user:pass@proxy.example.com:8080`(HTTP 프록시, 인증 정보는 선택) 또는 `socks5://proxy.example.com:1080`(인증 정보 없음). `https://` 프록시와 인증 정보가 있는 SOCKS5는 지원하지 않고, 로컬 또는 사설 주소는 거부돼요. 대상 페이지에 대한 모든 요청이 이 프록시를 통해 전송돼요 |
| `userAgent` | string | 아니요 | 보통은 생략하세요. Linux 데스크톱 Chrome의 User-Agent만 사용되고, 그 외(Windows, macOS, 모바일, 다른 브라우저)는 무시돼요. 이후 요청에는 항상 결과의 `user_agent`를 사용하세요 |
| `waitLoad` | boolean | 아니요 | 기본값은 false예요. true로 설정하면 검증을 통과한 뒤 페이지의 네트워크 활동이 잠잠해질 때까지 기다린 다음 반환해요. 그래서 `content`에 동적으로 불러온 내용이 더 많이 포함되지만 몇 초 더 걸려요 |
| `requiredCookies` | array | 아니요 | 반드시 가져와야 하는 쿠키 이름 목록이에요. 문자열 배열로 전달하세요. 예: `["cf_clearance"]`. 설정하면 모두 가져왔을 때만 성공해요. 하나라도 가져오지 못하면 `ERROR_CAPTCHA_UNSOLVABLE`을 반환하고 포인트가 환불돼요. 생략하면 `cf_clearance`를 가져오려고 시도하지만, 다른 쿠키만 가져와도 성공으로 처리되어 포인트가 차감돼요. `cf_clearance`가 필요하면 반드시 명시적으로 전달하세요 |
| `blockImage` | boolean | 아니요 | true로 설정하면 대상 페이지의 이미지를 불러오지 않아요(Cloudflare 검증 자체에 필요한 이미지는 제외). 프록시 트래픽을 절약할 수 있어요 |
| `postData` | object | 아니요 | 설정하면 일반 HTML 폼 POST처럼 `websiteURL`로 제출돼요(`application/x-www-form-urlencoded`). 각 키는 폼 필드이고 값은 문자열로 전송돼요. 예: `{"name": "hi"}`. 반드시 객체여야 해요 |
### 프록시 요구 사항
`proxy`는 필수예요. 대상 웹페이지를 여는 모든 요청이 이 프록시를 거쳐요. `cf_clearance`는 출구 IP에 묶여 있으므로, 이후 대상 사이트에 접속할 때도 같은 프록시를 써야 해요.
| 형식 | 지원 여부 |
| --- | --- |
| `http://user:pass@proxy.example.com:8080` | 지원: http 프록시, 계정과 비밀번호 포함 |
| `http://proxy.example.com:8080` | 지원: http 프록시, 계정과 비밀번호 없음 |
| `socks5://proxy.example.com:1080` | 지원: socks5 프록시, 계정과 비밀번호 없음. `socks5h://`는 `socks5://`로 처리해요 |
| `socks5://user:pass@proxy.example.com:1080` | 지원 안 함, `ERROR_PROXY_INCORRECT` 반환. 계정과 비밀번호가 필요하면 http 프록시를 쓰세요 |
| `https://proxy.example.com:443` 등 다른 프로토콜, 또는 포트 누락 | 지원 안 함, `ERROR_PROXY_INCORRECT` 반환 |
| `127.0.0.1`, `192.168.x.x`, `10.x.x.x` 같은 로컬, 내부망, 예약 주소 또는 이런 주소로 확인되는 도메인 | 거부, `ERROR_PROXY_BANNED` 반환 |
> **작업을 만들 때 바로 검사해요:** URL이나 프록시가 규칙에 맞지 않으면 `createTask`가 바로 오류를 반환하고 포인트는 차감되지 않아요. 같은 프록시가 짧은 시간에 여러 번 연결되지 않으면, 이후 한동안은 그 프록시로 작업을 만들 때도 바로 `ERROR_PROXY_BANNED`가 반환돼요. 프록시를 바꾸거나 잠시 후 다시 시도하세요.
### User-Agent
보통은 `userAgent`를 보내지 않아요. YesCaptcha는 Linux 데스크톱 버전 Chrome으로 확인을 통과해요. 같은 Linux 데스크톱 버전 Chrome의 User-Agent만 적용되고, 그 밖의 것(Windows, macOS, 모바일, 다른 브라우저)은 무시해요. 실측 결과 브라우저의 실제 환경과 User-Agent가 맞지 않으면 Cloudflare 확인을 통과하지 못했어요. 이후 요청에는 항상 결과의 `user_agent`를 쓰세요.
## 요청 예시
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "CloudFlareTaskS3",
"websiteURL": "https://example.com/",
"proxy": "http://user:pass@proxy.example.com:8080",
"requiredCookies": ["cf_clearance"]
}
}
```
- `CloudFlareTaskS2`를 쓰려면 `type`만 바꾸고 나머지는 그대로 두세요.
- `requiredCookies`에 `["cf_clearance"]`를 보내면 `cf_clearance`를 받지 못했을 때 작업이 실패하고 포인트가 환불돼요. 보내지 않으면 `cf_clearance` 없이 다른 쿠키만 받아도 성공으로 처리되어 포인트가 차감돼요.
- 폼을 제출해야 하면 `postData`를 추가하세요. 예: `{"name": "hi"}`. `websiteURL`로 POST 폼 방식으로 제출돼요.
작업을 만든 뒤에는 5초마다 `getTaskResult`를 호출하세요. 흐름은 다른 비동기 작업과 같아요. [getTaskResult](https://docs.yescaptcha.com/ko/api/get-task-result.md)를 참고하세요.
## 반환 결과
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
"cookies": {
"cf_clearance": "Wq3vXk9...-1760860800-1.2.1.1-..."
},
"request_headers": {
"accept-language": "en-US,en;q=0.9",
"user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
},
"headers": {
"content-type": "text/html; charset=UTF-8",
"server": "cloudflare"
},
"content": "..."
}
}
```
위의 쿠키 값과 요청 헤더는 예시예요. 실제 값은 반환된 결과를 따르세요.
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `cookies` | object | 검증을 통과한 뒤 브라우저에 있는 모든 쿠키예요(이름-값 객체). 보통 `cf_clearance`가 포함돼요. `requiredCookies`를 보냈다면 그 쿠키가 모두 포함돼요. 반환된 `user_agent`, 작업을 만들 때 사용한 프록시와 함께 사용하세요 |
| `user_agent` | string | 검증을 통과할 때 브라우저가 실제로 사용한 User-Agent예요(Linux 데스크톱 Chrome). `cf_clearance`가 이 값에 연결되어 있으므로 이후 모든 요청에 이 값을 사용해야 해요 |
| `request_headers` | object | 브라우저가 대상 웹페이지를 마지막으로 요청할 때 보낸 요청 헤더예요. 이후 요청에도 같은 헤더를 사용하는 것을 권장해요 |
| `headers` | object | 검증을 통과한 뒤 받은 대상 웹페이지의 응답 헤더예요 |
| `content` | string | 검증을 통과한 뒤 받은 대상 웹페이지의 HTML 소스예요 |
## 결과 사용 방법
1. 이후 요청에는 반환된 `cookies`, 반환된 `user_agent`, 작업을 만들 때 쓴 같은 프록시를 **모두 함께** 쓰세요. `cf_clearance`는 User-Agent, 출구 IP에 묶여 있어서 셋 중 하나라도 다르면 챌린지 페이지가 다시 나타나요.
2. 요청 헤더도 가능하면 `request_headers`대로 보내고, 브라우저와 같은 TLS 핑거프린트를 쓰세요(예: curl\_cffi의 `impersonate` 파라미터).
3. `cf_clearance`에는 유효 기간이 있어요(대상 사이트가 설정하며, 길면 1시간까지 가는 경우도 있어요). 유효 기간 안에는 챌린지를 다시 통과할 필요가 없어요. 다만 요청 빈도가 너무 높으면 Cloudflare가 IP를 차단할 수 있어요.
4. 웹페이지 내용만 필요하면 `content`를 그대로 쓰면 돼요. 다시 요청할 필요가 없어요.
## 자주 발생하는 오류
작업을 만들 때 반환된 오류는 포인트가 차감되지 않아요. 작업을 만든 뒤 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요. 인터페이스는 오류 코드와 일반적인 설명만 반환하므로, 구체적인 원인은 아래 표에서 확인하세요.
| 오류 코드 | 반환되는 경우 | 해결 방법 |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | 작업 생성 시: `websiteURL` 또는 `proxy`가 없음 | 필수 필드 두 개를 모두 채우세요 |
| `ERROR_ILLEGAL_PARAMETERS` | 작업 생성 시: `websiteURL`이 `http://` / `https://`로 시작하는 공개 URL이 아님, `postData`가 객체가 아님, `requiredCookies`가 문자열 배열이 아님. 결과 조회 시: 프록시를 통해 대상 URL의 도메인을 확인할 수 없음 | 파라미터를 고치세요. URL 철자와 프록시가 해당 사이트에 접속할 수 있는지 확인하세요 |
| `ERROR_PROXY_INCORRECT` | 작업 생성 시: 프록시 형식이 올바르지 않거나 포트가 없음, `https://` 프록시 또는 계정과 비밀번호가 있는 socks5를 사용함 | 위 “프록시 요구 사항”의 형식으로 고치세요. 계정과 비밀번호가 필요하면 http 프록시를 쓰세요 |
| `ERROR_PROXY_BANNED` | 작업 생성 시: 프록시가 로컬, 내부망 또는 예약 주소이거나, 이 프록시가 짧은 시간에 여러 번 연결되지 않음. 결과 조회 시: 대상 사이트의 Cloudflare가 이 프록시의 IP를 바로 차단함(“Sorry, you have been blocked”, “Access denied” 페이지) | 프록시를 바꾸세요. IP 품질이 좋을수록 통과하기 쉬워요 |
| `ERROR_PROXY_CONNECT_REFUSED` | 프록시에 연결할 수 없거나(연결 거부, 프록시 도메인을 확인할 수 없음), 프록시를 통해 웹페이지를 여는 중 연결이 거부되거나 재설정됨 | 프록시 주소와 포트를 확인하고, 프록시가 온라인이며 외부 접속을 허용하는지 확인하세요. 계속 실패하면 프록시를 바꾸세요 |
| `ERROR_PROXY_CONNECT_TIMEOUT` | 프록시에 연결하거나 프록시를 통해 웹페이지를 여는 중 시간이 초과됨 | 더 빠르고 안정적인 프록시로 바꾸세요 |
| `ERROR_PROXY_NOT_AUTHORISED` | 프록시의 계정 또는 비밀번호가 올바르지 않음 | `proxy`의 계정과 비밀번호를 확인하세요. 특수 문자는 URL 인코딩해야 해요 |
| `ERROR_PROXY_TLS_ERROR` | 프록시를 통해 웹페이지를 여는 중 TLS 핸드셰이크 오류가 발생함 | 프록시 주소, 포트, 프로토콜이 맞는지 확인하세요. 계속 실패하면 프록시를 바꾸세요 |
| `ERROR_CAPTCHA_UNSOLVABLE` | 제한 시간 안에 확인을 통과하지 못했거나, 통과 후에도 챌린지 페이지에 머물러 있거나, `requiredCookies`에 지정한 쿠키를 받지 못함 | 먼저 프록시를 바꿔서 다시 시도하세요. 일부 사이트는 고객 지원에 문의하세요 |
| `ERROR_NO_SLOT_AVAILABLE` | 작업 생성 시: 대기열이 가득 참. 결과 조회 시: 대기 시간이 너무 길어 시작하지 못했고 포인트가 환불됨 | 몇 초 기다린 뒤 작업을 다시 만드세요 |
| `ERROR_TASK_TIMEOUT` | 작업이 제한 시간 안에 완료되지 않음 | 작업을 다시 만드세요. 시간 초과가 계속되면 대개 프록시가 너무 느린 거예요 |
전체 오류 코드는 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.
## 관련 문서
- [캡차 유형 판별](https://docs.yescaptcha.com/ko/guides/identify-captcha.md): Cloudflare 챌린지 페이지와 Turnstile의 차이
- [Cloudflare Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md)
---
# 이미지 영문·숫자 인식
> YesCaptcha로 이미지 속 영문과 숫자를 인식해요. ImageToTextTaskOcrBase와 ImageToTextTaskMuggle은 동기로 결과를 반환하고, ImageToTextTask와 ImageToTextTaskM1은 비동기이며 대소문자, 숫자만, 수식 등의 조건을 지원해요. 모델 맞춤 제작도 가능해요.
Source: https://docs.yescaptcha.com/ko/tasks/image-to-text/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/image-to-text/
문자 캡차 이미지를 Base64로 변환해 보내면 이미지 속 영문과 숫자(`solution.text`)를 반환해요. `ImageToTextTaskOcrBase`는 이미지 한 장당 2 포인트 (≈ $0.30 / 1k)이고 동기로 결과를 반환해요. `createTask` 요청 한 번으로 결과를 받을 수 있어요. 대소문자, 숫자만, 수식 등의 조건을 지정해야 한다면 비동기 방식인 `ImageToTextTask`를 사용하세요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
요청 본문은 JSON이며 `clientKey`로 인증해요.
## 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `ImageToTextTaskOcrBase` | $0.30 / 1k; 2 포인트/작업 · ¥2 / 1k | 동기 | |
| `ImageToTextTaskMuggle` | $0.30 / 1k; 2 포인트/작업 · ¥2 / 1k | 동기 | case, numeric 같은 추가 옵션은 지원하지 않아요. project\_name으로 맞춤 모델을 지정할 수 있어요 |
| `ImageToTextTask` | $0.60 / 1k; 4 포인트/작업 · ¥4 / 1k | 비동기 | |
| `ImageToTextTaskM1` | $2.25 / 1k; 15 포인트/작업 · ¥15 / 1k | 비동기 | |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
| 필요한 경우 | 사용할 유형 |
| --- | --- |
| 일반적인 영문·숫자 캡차, 가장 저렴하고 빠름 | `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` (동기) |
| 나를 위해 맞춤 제작한 모델로 인식 | `ImageToTextTaskMuggle`에 `project_name` 추가 |
| 대소문자 구분, 숫자만, 수식 계산, 길이 제한이 필요한 경우 | `ImageToTextTask`, `ImageToTextTaskM1` (비동기) |
유형마다 모델과 경로가 달라서 같은 종류의 이미지라도 결과가 다를 수 있어요. 모두 테스트해 보고 선택하세요.
## 요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `body` | string | 예 | Base64로 인코딩한 이미지예요. `data:image/...;base64,` 접두사와 줄바꿈은 포함하지 마세요 |
| `project_name` | string | 아니요 | 맞춤 모델의 이름이에요. `ImageToTextTaskMuggle`에서만 지원돼요. 생략하면 범용 영문·숫자 모델을 사용해요. 맞춤 모델이 필요하면 고객 지원에 문의하세요 (ImageToTextTaskMuggle 전용) |
| `phrase` | boolean | 아니요 | true이면 정답에 공백이 하나 이상 포함돼요 (ImageToTextTask, ImageToTextTaskM1 전용) |
| `case` | boolean | 아니요 | true이면 정답의 대소문자를 구분해요 (ImageToTextTask, ImageToTextTaskM1 전용) |
| `numeric` | integer | 아니요 | 0은 제한 없음, 1은 숫자만, 2는 숫자 제외예요 (ImageToTextTask, ImageToTextTaskM1 전용) |
| `math` | boolean | 아니요 | true이면 이미지가 수식이고 정답은 계산 결과예요 (ImageToTextTask, ImageToTextTaskM1 전용) |
| `minLength` | integer | 아니요 | 정답의 최소 길이예요. 0이면 제한이 없어요 (ImageToTextTask, ImageToTextTaskM1 전용) |
| `maxLength` | integer | 아니요 | 정답의 최대 길이예요. 0이면 제한이 없어요 (ImageToTextTask, ImageToTextTaskM1 전용) |
`body`는 이미지 파일의 Base64 인코딩이에요. WebP 이미지는 자동으로 변환돼요.
> **주의:** Base64에 `data:image/...;base64,` 접두사를 붙이지 마세요. 줄바꿈도 넣으면 안 돼요.
## 요청 예시
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}
```
전체 코드(현재 디렉터리의 `captcha.png`를 읽어요):
**curl**
```bash
# Replace BASE64_IMAGE with the Base64-encoded image
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}'
```
**Python**
solve.py
```python
import os
import base64
import requests
API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"] # Read the clientKey from an environment variable
def call(method, payload):
r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
data = r.json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def solve(task):
return call("createTask", {"task": task})["solution"]
# Base64-encode the image (no data: prefix)
with open("captcha.png", "rb") as f:
image_b64 = base64.b64encode(f.read()).decode()
solution = solve({
"type": "ImageToTextTaskOcrBase",
"body": image_b64,
})
print(solution["text"])
```
**Node.js**
solve.mjs
```js
import { readFileSync } from 'node:fs';
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable
async function call(method, payload) {
const res = await fetch(`${API}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
return data;
}
async function solve(task) {
const { solution } = await call('createTask', { task });
return solution;
}
// Base64-encode the image (no data: prefix)
const imageB64 = readFileSync('captcha.png').toString('base64');
const solution = await solve({
type: "ImageToTextTaskOcrBase",
body: imageB64,
});
console.log(solution.text);
```
조건을 지정한 비동기 작업:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTask",
"body": "BASE64_IMAGE",
"case": true,
"numeric": 0,
"minLength": 4,
"maxLength": 6
}
}
```
## 반환 결과
동기 유형은 `createTask`에서 바로 반환해요.
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"text": "LMResm"
},
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
}
```
비동기 유형(`ImageToTextTask`, `ImageToTextTaskM1`)은 먼저 `taskId`를 반환해요. 이후 5초마다 `getTaskResult`로 조회하면 완료 시 같은 형식의 `solution`을 받을 수 있어요.
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `text` | string | 인식된 텍스트예요 |
## 맞춤 모델
범용 모델은 모든 영문·숫자 캡차에 사용할 수 있지만, 특정 스타일 전용으로 학습한 모델보다 정확도가 약간 낮아요. 인식할 이미지가 항상 같은 스타일이라면 [고객 지원](https://docs.yescaptcha.com/ko/help/contact.md)에 문의해 맞춤 모델을 만든 뒤, `ImageToTextTaskMuggle`에 `project_name`을 지정해서 사용하세요.
## 자주 묻는 질문
### 인식이 틀려도 포인트가 차감되나요?
동기 유형은 결과가 반환되면 틀린 결과여도 포인트가 차감돼요. 다른 유형으로 결과를 비교해 보거나 맞춤 모델을 제작해 보세요.
### `ERROR_ZERO_CAPTCHA_FILESIZE` 또는 `ERROR_PARSE_IMAGE_FAIL`이 반환돼요
이미지의 Base64가 불완전하거나 `data:` 접두사 또는 줄바꿈이 포함되어 있어요. 인코딩을 확인하세요. [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.
## 관련 예시
- [빠른 시작](https://docs.yescaptcha.com/ko/getting-started/quickstart.md): `ImageToTextTaskOcrBase`로 첫 요청 보내기
- [Python 예시](https://docs.yescaptcha.com/ko/samples/python.md)
---
# reCAPTCHA v2 이미지 인식
> YesCaptcha로 reCAPTCHA v2 이미지 문제(ReCaptchaV2Classification)를 인식해요. 3x3, 4x4, 1x1 이미지와 질문 ID를 보내면 클릭할 칸을 동기로 반환해요. 이미지 크기별로 과금하며, 질문 ID 표를 제공해요.
Source: https://docs.yescaptcha.com/ko/tasks/recaptcha-classification/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/recaptcha-classification/
`ReCaptchaV2Classification`은 reCAPTCHA v2가 띄우는 이미지 문제를 인식해요. 이미지와 질문 ID를 보내면 클릭해야 할 칸을 반환하고, 브라우저에서 클릭하는 건 여러분의 프로그램이 해요. **토큰은 반환하지 않아요.** 동기 방식이라 `createTask` 요청 한 번으로 결과를 받아요. 3x3, 4x4 이미지는 장당 6 포인트 (≈ $0.90 / 1k)이고, 1x1 작은 이미지는 더 저렴해요. 아래 표를 참고하세요.
> **팁:** 클릭 로직을 직접 작성하고 싶지 않다면 [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)을 사용하세요. 이 API를 기반으로 자동으로 클릭해요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
## 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `ReCaptchaV2Classification` | $0.90 / 1k; 6 포인트/작업 · ¥6 / 1k | 동기 | 1x1 타일(100x100)은 2포인트, 3x3(300x300)와 4x4(450x450)는 6포인트예요 |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
## 요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `image` | string | 예 | 질문 이미지를 Base64로 인코딩한 값이에요. `data:` 접두사는 포함하지 마세요 |
| `question` | string | 예 | `/m/0k4j` 같은 질문 ID예요. 이 페이지의 "질문 ID"를 참고하세요 |
| `confidence` | number | 아니요 | 0에서 1 사이의 신뢰도 임계값이에요. 3x3 이미지에만 적용돼요. 값을 보내면(0.5부터 시작하는 것을 권장) 이 값보다 높은 모든 칸을 반환하고, 보내지 않으면 가능성이 가장 높은 3칸을 반환해요 |
> **주의:** 이미지는 아래 표의 표준 크기로 조정해야 해요. 서버가 크기를 보고 문제 유형을 판단해요.
| 문제 유형 | 이미지 크기 | 반환 |
| --- | --- | --- |
| 3x3 그리드 (“모든 이미지 선택”) | 300 × 300 | `objects`: 클릭할 칸 |
| 4x4 그리드 (“모든 타일 선택”) | 450 × 450 | `objects`: 클릭할 칸 |
| 1x1 작은 이미지 (3x3에서 클릭한 뒤 새로 나타나는 단일 이미지) | 100 × 100 | `hasObject`: 이 이미지를 클릭할지 여부 |
스크린샷이라면 질문 문구로 구분하세요. 3x3은 “모든 이미지 선택”(Select all images with …), 4x4는 “모든 타일 선택”(Select all squares with …)이에요.
## 요청 예시
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ReCaptchaV2Classification",
"image": "BASE64_IMAGE",
"question": "/m/0k4j"
}
}
```
## 반환 결과
3x3, 4x4:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [1, 5, 8],
"type": "multi"
},
"taskId": "3a9e8cb8-3871-11ec-9794-94e6f7355a0b"
}
```
1x1 작은 이미지:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"hasObject": true,
"type": "single"
}
}
```
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `objects` | array | 클릭해야 할 이미지의 번호예요(0부터 시작, 왼쪽에서 오른쪽, 위에서 아래 순서) |
| `hasObject` | boolean | 1x1 작은 이미지일 때 반환돼요. 이 이미지에 대상이 있는지 여부예요 |
| `type` | string | 질문 유형이에요. `multi`(3x3, 4x4 큰 이미지, `objects` 확인), `single`(1x1 작은 이미지, `hasObject` 확인)이며, hCaptcha 드래그 질문은 `drag`예요 |
칸 번호는 0부터 시작하며, 왼쪽에서 오른쪽, 위에서 아래 순서예요.
## confidence: 해당하는 칸을 한 번에 모두 반환
3x3 문제를 클릭하고 나면 보통 1x1 작은 이미지가 새로 나타나 계속 판단해야 해요. 작은 이미지를 가져오기 어렵다면(예: 모바일 개발) `confidence`를 보낼 수 있어요.
- 보내지 않으면 3x3 이미지는 점수가 가장 높은 3개 칸을 반환해요(reCAPTCHA는 최소 3개를 클릭해야 해요).
- 보내면(`0.5` 권장) 점수가 이 값보다 높은 칸을 모두 반환해요. 3개보다 많거나 적을 수 있고, 해당하는 칸이 없으면 빈 배열을 반환해요. 그러면 1x1 작은 이미지를 따로 캡처할 필요가 없어요.
- 4x4와 1x1 이미지에는 영향이 없어요.
## 질문 ID
`question`에는 질문 문구가 아니라 질문의 ID(`/m/`으로 시작)를 넣어요. ID는 reCAPTCHA가 문제를 불러오는 요청(`reload` 또는 `userverify`)의 응답에 이미지와 함께 내려와요. 아래 표는 자주 나오는 질문이며, 한국어 표기는 참고용이에요.
총 16개
| 질문 ID | 질문 (영어) |
| --- | --- |
| `/m/0pg52` | `taxis` |
| `/m/01bjv` | `bus` |
| `/m/04_sv` | `motorcycles` |
| `/m/013xlm` | `tractors` |
| `/m/01jk_4` | `chimneys` |
| `/m/014xcs` | `crosswalks` |
| `/m/015qff` | `traffic lights` |
| `/m/0199g` | `bicycles` |
| `/m/015qbp` | `parking meters` |
| `/m/0k4j` | `cars` |
| `/m/015kr` | `bridges` |
| `/m/019jd` | `boats` |
| `/m/0cdl1` | `palm trees` |
| `/m/09d_r` | `mountains or hills` |
| `/m/01pns0` | `fire hydrant` |
| `/m/01lynh` | `stairs` |
일치하는 질문이 없어요
`ERROR_UNKNOWN_QUESTION`이 반환되면 ID가 잘못되었거나 아직 지원하지 않는 문제예요. `ERROR_UNKNOW_450x450_QUESTION`은 이 문제가 아직 4x4 이미지를 지원하지 않는다는 뜻이니, 웹 페이지에서 새로고침해 다른 문제로 바꾸면 돼요.
## 신고와 포인트 환불
클릭 후 검증에 실패했다면 1시간 이내에 [report](https://docs.yescaptcha.com/ko/api/report.md)로 신고할 수 있어요. 약 24시간 뒤에 포인트 환불이 정산되며, 규칙은 [과금과 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)에서 확인하세요. 검증을 통과한 경우에도 report로 `isSuccess: true`를 신고해 주세요.
## 관련 튜토리얼
- [reCAPTCHA v2 이미지 인식으로 클릭 시뮬레이션 (Selenium)](https://docs.yescaptcha.com/ko/guides/recaptcha-click-selenium.md)
- [reCAPTCHA v2 (토큰 반환)](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md)
---
# hCaptcha 이미지 인식
> YesCaptcha로 hCaptcha 이미지 문제(HCaptchaClassification)를 인식해요. 3×3 그리드 선택, 지정 위치 클릭, 지정 위치로 드래그, 애니메이션 문제를 지원하고, 동기로 결과를 반환하며, 대상을 찾지 못하면 포인트가 차감되지 않아요.
Source: https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/hcaptcha-classification/
`HCaptchaClassification`은 hCaptcha가 띄우는 이미지 문제를 인식해요. 문제와 이미지를 보내면 어떤 이미지를 선택해야 하는지, 어느 위치를 클릭해야 하는지, 어디에서 어디로 드래그해야 하는지를 반환하고, 브라우저에서의 실제 동작은 직접 작성한 프로그램이 처리해요. **토큰은 반환하지 않아요.** 동기로 결과를 반환하며, 요청당 8 포인트 (≈ $1.20 / 1k)가 차감돼요. 대상을 찾지 못해 결과가 비어 있으면 포인트가 차감되지 않아요.
> **팁:** 클릭 로직을 직접 작성하고 싶지 않다면 [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)을 사용하세요. 이 문제 유형을 모두 지원해요. 클릭 위치 대신 토큰이 필요하다면 [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md)를 사용하세요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
## 작업 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `HCaptchaClassification` | $1.20 / 1k; 8 포인트/작업 · ¥8 / 1k | 동기 | 대상을 찾지 못하면 포인트가 차감되지 않아요 |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
## 요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `queries` | array | 예 | 질문 이미지의 Base64 인코딩 목록이에요. 웹페이지에 표시된 순서대로 보내세요(3×3 그리드는 작은 이미지 9장) |
| `question` | string | 아니요 | 웹페이지에 표시된 질문 전체 문장이에요(간체 중국어 또는 영어 권장). 예: `Please click each image containing a bicycle`. `question`과 `anchors` 중 하나 이상을 보내야 하며, 둘 다 보내는 것을 권장해요 |
| `anchors` | array | 아니요 | 질문 옆에 표시되는 예시 이미지의 Base64 인코딩 목록이에요. 예시 이미지가 있는 질문에는 반드시 보내야 해요 |
- `question`에는 웹페이지에 표시된 문제 문장을 그대로 넣으세요. 번역할 필요는 없지만 hCaptcha 언어를 중국어 간체나 영어로 바꾸는 것을 권장해요. 새로운 문제 문구는 보통 빠르게 지원하고, 완전히 새로운 카테고리는 영업일 기준 3일 이내에 지원해요.
> **주의:** 문제 오른쪽 위에 예시 이미지가 있다면 그 이미지를 `anchors`에 넣으세요. 예시 이미지를 봐야만 풀 수 있는 문제는 `anchors`를 보내지 않으면 인식할 수 없어요.
## 3×3 그리드 선택
문제가 “… 이(가) 포함된 이미지를 모두 클릭하세요”이고 아래에 이미지 9장이 있는 유형이에요. `queries`에 9장의 이미지를 순서대로 Base64로 넣으세요:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaClassification",
"question": "Please click each image containing a bicycle",
"queries": ["BASE64_IMAGE_1", "BASE64_IMAGE_2"]
}
}
```
반환 결과:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [true, false, false, true, true, false, true, true, false],
"top_k": [0, 3, 4, 6, 7],
"confidences": [1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0, 0.0]
}
}
```
`objects`와 `top_k`는 같은 정보를 담고 있어요. `objects`는 각 이미지가 대상인지 여부이고, `top_k`는 대상 이미지의 번호(0부터 시작)예요. 해당 이미지를 클릭하면 돼요.
## 지정 위치 클릭
문제가 “… 을(를) 클릭하세요”이고 아래에 큰 이미지가 하나 있어, 이미지 위의 한 곳 또는 여러 곳을 클릭하는 유형이에요.
1. `question`에는 웹페이지의 문제를 넣고, 예시 이미지가 있으면 `anchors`에 넣으세요.
2. `queries`에는 이미지 한 장을 넣어요. canvas에서 바로 내보낸 원본 이미지가 가장 좋아요(JPG로 변환하는 것을 권장해요). 스크린샷만 가능하다면 아래 빨간 박스 안의 큰 이미지 영역만 정확히 캡처하세요. 더 넓거나 좁으면 안 돼요.
3. 반환된 `box`는 클릭할 좌표이며 x1, y1, x2, y2 … 순서로 들어 있고, 업로드한 이미지의 왼쪽 위를 원점으로 해요.
4. 업로드한 이미지 크기가 웹페이지에 표시된 크기와 다르면 변환해야 해요. 웹페이지의 x = 반환된 x × 표시 너비 ÷ 업로드 이미지 너비예요(y도 같아요). 예를 들어 반환된 x = 769이고 canvas 표시 너비가 350, 업로드 이미지 너비가 1000이면 웹페이지에서는 769 × 350 ÷ 1000 ≈ 269 위치를 클릭해야 해요.
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaClassification",
"question": "Please click on the entity present in the sample image.",
"anchors": ["BASE64_ANCHOR_1", "BASE64_ANCHOR_2", "BASE64_ANCHOR_3"],
"queries": ["BASE64_OF_THE_BIG_IMAGE"]
}
}
```
반환 결과:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"box": ["221", "213"]
}
}
```
대상을 여러 개 클릭해야 하면 `box`에 여러 좌표 쌍이 순서대로 들어 있어요: `["221", "213", "340", "118", ...]`.
## 지정 위치로 드래그
문제가 “… 을(를) … 로 드래그하세요”이고, 오른쪽의 조각을 이미지의 해당 위치로 드래그하는 유형이에요.
1. `question`에는 웹페이지의 문제를 넣으세요.
2. 스크린샷 한 장을 `queries`에 넣으세요. 이미지에 드래그할 조각과 목표 위치가 **모두** 보여야 하고, 이미지의 어느 변도 260픽셀 이상이어야 해요.
3. 반환된 `box`의 각 항목은 한 번의 드래그예요. `start`는 조각의 위치이고 `end`는 놓을 위치예요. 조각이 여러 개면 하나씩 드래그하세요.
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"type": "drag",
"box": [
{
"start": [644, 218],
"end": [239, 315]
}
]
}
}
```
스크린샷이 아니라 프로토콜 데이터(조각 이미지, 조각 좌표, 배경 큰 이미지)를 가지고 있다면, 먼저 좌표에 맞게 조각을 큰 이미지 위에 합성해서 웹페이지 스크린샷과 같은 모양으로 만든 뒤 전송하세요.
## 애니메이션 문제
문제 이미지가 애니메이션이면 애니메이션(GIF 등 형식)을 Base64로 인코딩해서 `queries`에 넣으세요. 애니메이션 길이는 최소 3초, 가능하면 5~6초, 프레임 레이트는 약 12 FPS를 권장해요.
## 신고와 포인트 환불
클릭 후 검증에 실패했다면 1시간 이내에 [report](https://docs.yescaptcha.com/ko/api/report.md)로 신고할 수 있어요. 약 24시간 후 포인트 환불이 정산돼요. 규칙은 [과금 및 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.
## 관련 튜토리얼
- [hCaptcha 이미지 인식 클릭 시뮬레이션(Selenium)](https://docs.yescaptcha.com/ko/guides/hcaptcha-click-selenium.md)
---
# FunCaptcha 이미지 인식
> YesCaptcha로 FunCaptcha(Arkose Labs)의 이미지 문제(FunCaptchaClassification)를 인식해요. 문제 이미지(6칸 그리드 또는 좌우로 합쳐진 화살표 문제)와 영어 질문을 업로드하면 몇 번째 이미지를 선택해야 하는지 동기로 반환해요. 모든 문제 유형을 지원해요.
Source: https://docs.yescaptcha.com/ko/tasks/funcaptcha-classification/ · Last verified: 2026-10-16
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/funcaptcha-classification/
`FunCaptchaClassification`은 FunCaptcha(Arkose Labs)의 이미지 문제를 인식해요. 문제 이미지와 영어 질문을 보내면 선택해야 할 이미지의 번호를 반환하고, 브라우저에서 클릭하는 것은 직접 작성한 프로그램이 해요. **토큰은 반환하지 않아요**. 동기로 반환하며, 요청 1회당 3 포인트 (≈ $0.45 / 1k)예요.
> **팁:** 코드를 작성하지 않으려면 [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)으로 웹 페이지에서 자동으로 처리할 수 있어요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
## 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `FunCaptchaClassification` | $0.45 / 1k; 3 포인트/작업 · ¥3 / 1k | 동기 | |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
## 요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `image` | string | 예 | 질문 이미지를 Base64로 인코딩한 값이에요. `data:` 접두사는 포함하지 마세요 |
| `question` | string | 예 | 질문의 영어 원문(예: `Pick the image that is the correct way up`)이에요. 지원하는 질문은 이 페이지에서 확인하세요 |
- `image`에는 문제의 이미지 부분(6칸 그리드 또는 좌우로 합쳐진 화살표 문제 이미지)만 넣으세요. 위쪽의 제목과 버튼은 포함하지 마세요. 스크린샷은 전체가 나와야 하며, 한 부분이라도 빠지면 인식에 영향을 줘요. 세로로 배열된 6칸 그리드는 원본 이미지를 그대로 업로드하면 돼요.
- `question`에는 웹 페이지에 표시된 영어 질문 전체를 그대로 넣으세요. 대소문자를 정확히 지키고, 직접 번역하지 마세요. 웹 페이지가 다른 언어이면 먼저 캡차를 영어로 전환하세요. 서버가 질문을 보고 문제 유형을 판단하므로 질문이 정확해야 해요.
## 요청 예시
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "FunCaptchaClassification",
"image": "BASE64_IMAGE",
"question": "Pick the bread"
}
}
```
## 반환 결과
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [4],
"labels": ["parrot", "panda", "octopus", "owl", "bread", "dog"]
},
"taskId": "04a3fa76-11a0-11ed-a58c-0ef20f419382"
}
```
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `objects` | array | 선택해야 할 이미지의 번호예요(0부터 시작, 왼쪽에서 오른쪽, 위에서 아래 순서) |
| `labels` | array | 인식된 라벨이에요 |
`objects: [4]`는 5번째 이미지를 선택하라는 뜻이에요(번호는 0부터 시작하고, 왼쪽에서 오른쪽, 위에서 아래 순서예요). 한 문제가 여러 라운드로 이어지는 경우가 많아요. 매 라운드마다 새로 스크린샷을 찍고 다시 호출하세요.
## 지원하는 질문
**모든 문제 유형을 지원해요**. 먼저 질문 목록을 확인할 필요 없이 웹 페이지의 영어 질문과 문제 이미지를 그대로 제출하면 돼요. `ERROR_UNKNOWN_QUESTION`이 반환되면 [고객 지원](https://docs.yescaptcha.com/ko/help/contact.md)에 문의하세요.
요즘 흔한 유형은 좌우로 합쳐진 화살표 문제예요. 왼쪽은 비교할 예시이고 오른쪽은 현재 이미지이며, 웹 페이지에서 화살표로 오른쪽 이미지를 바꾸면서 질문에 맞는 이미지를 찾아요. 웹 페이지에 보이는 그대로 전체 이미지(좌우 두 부분)를 업로드하세요. 예를 들면 다음과 같아요.
`Use the arrows to change the number of objects until it matches the left image`개수가 왼쪽 이미지와 같아요
`use the arrows to choose the image where all the darts add up to the number in the left image`다트의 숫자 합이 왼쪽 이미지의 숫자와 같아요
`use the arrows to find the jigsaw puzzle that is missing the puzzle piece shown on the left`왼쪽에 있는 조각이 빠진 퍼즐이에요
`find the image that has the prize on the left held by the claw in the machine on the right`집게가 왼쪽의 상품을 잡고 있어요
다른 하나는 6칸 그리드 선택 문제(예: `Pick the bread`)예요. 위의 요청 예시처럼 6칸 그리드 부분만 업로드하면 돼요.
## 신고와 포인트 환불
한 묶음의 문제를 마지막에 제출했는데 실패했고 어느 라운드가 틀렸는지 모르겠다면, 해당 묶음의 작업 ID를 함께 [report](https://docs.yescaptcha.com/ko/api/report.md)로 신고할 수 있어요(1시간 이내). 약 24시간 후에 신고 후 포인트 환불이 정산돼요. 규칙은 [과금 및 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.
---
# AWS WAF / bCaptcha 이미지 인식
> YesCaptcha로 AWS WAF CAPTCHA와 bCaptcha의 3×3 그리드 이미지 문제를 인식해요 (AwsClassification, bCaptchaClassification). 전체 이미지와 질문을 보내면 클릭할 칸을 동기로 반환해요.
Source: https://docs.yescaptcha.com/ko/tasks/aws-bcaptcha-classification/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/aws-bcaptcha-classification/
`AwsClassification`은 AWS WAF CAPTCHA의 3×3 그리드 이미지 문제를, `bCaptchaClassification`은 bCaptcha의 3×3 그리드 이미지 문제를 인식해요. 전체 이미지와 질문을 보내면 클릭할 칸을 반환하고, 클릭은 사용자의 프로그램이 브라우저에서 직접 해요. **토큰은 반환하지 않아요.** 동기로 반환하며 요청당 8 포인트 (≈ $1.20 / 1k)예요.
코드를 작성하지 않고 쓰려면 [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)을 사용하세요.
- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)
## 작업 유형과 가격
| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `AwsClassification` | $1.20 / 1k; 8 포인트/작업 · ¥8 / 1k | 동기 | |
| `bCaptchaClassification` | $1.20 / 1k; 8 포인트/작업 · ¥8 / 1k | 동기 | |
미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.
두 유형은 매개변수와 반환 형식이 같아요. 캡차의 출처에 따라 고르세요. AWS WAF는 `AwsClassification`, bCaptcha는 `bCaptchaClassification`을 사용해요.
## 요청 매개변수
| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `queries` | string | 예 | 3×3 그리드 전체 이미지의 Base64 인코딩이에요(이미지 1장) |
| `question` | string | 아니요 | 웹페이지에 표시된 질문 전체 문장이에요. 예: `Select all hats`. 다른 언어는 자동으로 번역돼요 |
`queries`에는 3×3 그리드 **전체** 이미지를 넣어요 (작은 이미지 9장이 아니라 한 장이에요). `question`은 웹페이지에 표시된 문장을 그대로 넣으세요. 중국어와 영어를 모두 지원하고, 다른 언어는 자동으로 번역돼요.
## 요청 예시
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "AwsClassification",
"queries": "BASE64_IMAGE",
"question": "Select all hats"
}
}
```
## 반환 결과
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"label": "Select All Hats",
"objects": [false, true, false, false, true, true, true, true, false],
"top_k": [1, 4, 5, 6, 7],
"confidences": [0.0, 1.0, 0.0, 0.255, 1.0, 1.0, 0.9637, 0.9999, 0.0]
},
"taskId": "2053f690-3c3b-11f0-8ffb-d2c180657082"
}
```
| 필드 | 유형 | 설명 |
| --- | --- | --- |
| `label` | string | 인식된 질문의 대상이에요 |
| `objects` | array | 9개 칸이 각각 대상인지 여부(true / false)예요(왼쪽에서 오른쪽, 위에서 아래 순서) |
| `top_k` | array | 대상인 이미지의 번호예요(0부터 시작). `objects`와 같은 의미이므로 둘 중 하나만 사용하면 돼요 |
| `confidences` | array | 각 결과의 신뢰도예요 |
9개 칸은 3×3 그리드에서 왼쪽에서 오른쪽, 위에서 아래 순서로 0부터 8까지 번호가 매겨져요. `objects`와 `top_k`는 같은 정보를 담고 있으니 하나만 쓰면 돼요. `objects`가 `true`인 칸을 클릭하거나, `top_k`에 있는 번호의 칸을 클릭하세요.
## 신고와 포인트 환불
클릭 후 검증에 실패했다면 1시간 이내에 [report](https://docs.yescaptcha.com/ko/api/report.md)로 신고할 수 있어요. 약 24시간 후에 포인트 환불이 정산돼요. 규칙은 [과금 및 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.
---
# YesCaptcha Assistant
> YesCaptcha Assistant(브라우저 확장 프로그램)는 Chrome과 Firefox에서 reCAPTCHA, hCaptcha, FunCaptcha, AWS WAF 같은 캡차를 자동으로 인식하고 클릭해요. 확장 프로그램은 무료이고, 인식에 사용한 API 기준으로 포인트가 차감돼요. 스토어 링크, 설치 파일 다운로드, Chrome·BitBrowser·Kiwi Browser 설치 영상을 안내해요.
Source: https://docs.yescaptcha.com/ko/extension/ · Last verified: 2026-10-24
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/extension/
YesCaptcha Assistant는 Chrome과 Firefox용 브라우저 확장 프로그램이에요. 캡차가 있는 웹페이지를 열면 캡차 이미지를 YesCaptcha로 보내 인식한 뒤 자동으로 클릭해요. 코드를 작성할 필요가 없어요. 확장 프로그램 자체는 무료이고, 인식할 때 사용한 API 기준으로 포인트가 차감돼요. API와 같은 계정, 같은 잔액을 사용해요.
## 할 수 있는 일
- reCAPTCHA v2, hCaptcha, FunCaptcha, AWS WAF, bCaptcha의 이미지 문제를 자동으로 인식하고 클릭해요.
- 일반 문자 캡차: 이미지에서 오른쪽 클릭 후 “캡차로 표시”를 선택하고, 입력란에서 오른쪽 클릭 후 “캡차 입력”을 선택하면 확장 프로그램이 인식해서 채워 줘요.
- 설정에서 캡차 종류별로 켜고 끌 수 있고, 클릭 속도와 실패 시 재시도 등을 조정할 수 있어요.
> **참고:** 모든 사이트를 통과할 수 있는 것은 아니니 먼저 무료 체험으로 확인해 보세요.
## 설치
**스토어에서 설치 (권장, 자동으로 업데이트돼요):**
- Chrome (및 Edge 등 Chromium 기반 브라우저): [Chrome 웹 스토어](https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl)
- Firefox: [Firefox 부가 기능](https://addons.mozilla.org/firefox/addon/yescaptcha-assistant/)
Chrome 웹 스토어에서 확장 프로그램 페이지를 열고 “Chrome에 추가”를 클릭한 다음, 도구 모음의 확장 프로그램 아이콘을 클릭해서 `clientKey`를 입력하세요.
브라우저에서 이 동영상을 재생할 수 없어요. 다운로드해서 보세요: [영상: Chrome 웹 스토어에서 설치 (34초)](https://docs.yescaptcha.com/videos/extension-chrome-store.mp4)
영상: Chrome 웹 스토어에서 설치 (34초)
**스토어에 접속할 수 없다면 설치 파일을 다운로드하세요:**
Chrome 버전
버전
1.4.12
크기
1.1 MB
업데이트 날짜
2026-11-10
[다운로드](https://api.yescaptcha.com/extension/chrome/latest)[Chrome 웹 스토어](https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl)
Firefox 버전
버전
0.4.6
크기
0.9 MB
업데이트 날짜
2026-10-31
[다운로드](https://api.yescaptcha.com/extension/firefox/latest)[Firefox 부가 기능](https://addons.mozilla.org/firefox/addon/yescaptcha-assistant/)
Firefox 스토어의 버전이 여기 있는 설치 파일보다 오래됐을 수 있어요. 최신 버전이 필요하면 설치 파일을 사용하세요.
### Chrome에서 설치 파일로 설치
1. zip 파일을 다운로드하고 고정된 폴더에 압축을 풀어요.
2. 주소창에 `chrome://extensions`를 열고 오른쪽 위의 “개발자 모드”를 켜요.
3. “압축해제된 확장 프로그램을 로드합니다”를 클릭하고, 방금 압축을 푼 폴더를 선택해요.
4. 도구 모음에서 확장 프로그램 아이콘을 클릭하고 `clientKey`를 입력해요.
로드하기 전에 텍스트 편집기로 압축을 푼 `config.js`를 열어 `clientKey: ''`의 따옴표 안에 `clientKey`를 입력하고 저장해도 돼요. 이렇게 하면 설치 후 다시 입력하지 않아도 돼요. 여러 브라우저 환경에 확장 프로그램을 설치할 때 더 편해요.
브라우저에서 이 동영상을 재생할 수 없어요. 다운로드해서 보세요: [영상: Chrome에서 설치 파일로 설치, 먼저 config.js에 clientKey 입력 (44초, 영상은 이전 버전이지만 단계는 같아요)](https://docs.yescaptcha.com/videos/extension-chrome-zip.mp4)
영상: Chrome에서 설치 파일로 설치, 먼저 config.js에 clientKey 입력 (44초, 영상은 이전 버전이지만 단계는 같아요)
> **주의:** 압축을 푼 폴더는 이후에 삭제하거나 옮기지 마세요. 그러면 브라우저가 확장 프로그램을 불러올 수 없어요. 설치 파일로 설치한 경우 자동으로 업데이트되지 않으니, 새 버전이 나오면 다시 다운로드하세요.
### Firefox에서 설치 파일로 설치
1. `.xpi` 파일을 다운로드해요.
2. 주소창에 `about:addons`를 열고 톱니바퀴 아이콘을 클릭한 뒤 “파일에서 부가 기능 설치”를 선택하고, 다운로드한 파일을 선택해요.
3. 도구 모음에서 확장 프로그램 아이콘을 클릭하고 `clientKey`를 입력해요.
## BitBrowser에서 설치
BitBrowser 같은 안티 디텍트 브라우저는 Chrome 기반이라서 확장 프로그램을 “확장 센터”에서 추가해야 해요. 추가한 뒤에는 모든 창 또는 지정한 창에서 사용하도록 설정할 수 있어요. 아래 단계와 영상은 중국어 인터페이스의 BitBrowser 6.0으로 녹화했고, 새 버전은 화면이 조금 다를 수 있어요.
### Chrome 웹 스토어에서 추가
1. BitBrowser 왼쪽에서 “확장 센터”를 클릭하고, “사용자 지정 확장 프로그램 추가”를 클릭한 뒤 “Chrome 웹 스토어 확장 프로그램 추가”를 선택해요.
2. 확장 프로그램 상세 URL 입력란에 Chrome 웹 스토어 주소 `https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl`을 붙여 넣고, 입력란 오른쪽 버튼을 클릭해서 인식해요. YesCaptcha Assistant가 인식되면 “확인”을 클릭해요.
3. 추가한 뒤 YesCaptcha Assistant 카드에서 “설정”을 클릭하고, 확장 프로그램 활성화 방식에서 “모든 창”을 선택하거나 “지정한 창”을 선택해서 사용할 창을 체크한 다음 “확인”을 클릭해요.
4. 브라우저 창을 열고 도구 모음의 확장 프로그램 아이콘을 클릭해서 YesCaptcha Assistant를 찾아 `clientKey`를 입력해요. 잔액이 보이면 설정이 끝난 거예요.
브라우저에서 이 동영상을 재생할 수 없어요. 다운로드해서 보세요: [영상: BitBrowser에서 Chrome 웹 스토어로 추가 (30초)](https://docs.yescaptcha.com/videos/extension-bit-store.mp4)
영상: BitBrowser에서 Chrome 웹 스토어로 추가 (30초)
### 설치 파일로 추가
1. 위의 Chrome 버전 설치 파일을 다운로드하고 고정된 폴더에 압축을 풀어요.
2. (선택) 텍스트 편집기로 폴더 안의 `config.js`를 열고 `clientKey: ''`의 따옴표 안에 `clientKey`를 입력한 뒤 저장해요. 이렇게 하면 각 창에 설치한 뒤 다시 입력하지 않아도 돼요.
3. “확장 센터”에서 “사용자 지정 확장 프로그램 추가”를 클릭하고 “로컬 확장 프로그램 추가”를 선택한 다음, 확장 프로그램 업로드에서 압축을 푼 폴더(`manifest.json`이 들어 있는 바로 그 폴더)를 선택하고 “확인”을 클릭해요.
4. 업로드에 성공하면 YesCaptcha Assistant 카드에서 “설정”을 클릭하고, 활성화 방식(모든 창 또는 지정한 창)을 선택한 뒤 “확인”을 클릭해요.
5. 브라우저 창을 열고 확장 프로그램 아이콘에서 YesCaptcha Assistant를 클릭해요. ClientKey와 잔액이 보이면 설정이 끝난 거예요.
브라우저에서 이 동영상을 재생할 수 없어요. 다운로드해서 보세요: [영상: BitBrowser에서 설치 파일로 추가 (46초, 영상은 이전 버전이지만 단계는 같아요)](https://docs.yescaptcha.com/videos/extension-bit-zip.mp4)
영상: BitBrowser에서 설치 파일로 추가 (46초, 영상은 이전 버전이지만 단계는 같아요)
## 안드로이드 휴대폰에서 사용 (Kiwi Browser)
> **주의:** Kiwi Browser는 2025년 1월에 유지 관리가 중단되었고 Google Play에서도 삭제되어, 이후로는 업데이트와 보안 패치가 없어요. 아래 단계와 영상은 이전 문서에서 가져온 것으로, 아직 Kiwi Browser를 사용하는 사용자를 위한 참고용이에요. 현재 버전의 확장 프로그램은 Kiwi Browser에서 다시 테스트하지 않았어요.
1. Chrome 버전 설치 파일(`.zip`)을 휴대폰에 다운로드해요. 압축을 풀 필요는 없어요. ClientKey를 미리 입력해 두려면 먼저 컴퓨터에서 압축을 풀고 `config.js`를 수정한 다음 다시 zip으로 압축하세요(`manifest.json`이 압축 파일의 최상위에 있어야 해요).
2. Kiwi Browser에서 오른쪽 위의 메뉴를 누르고 “Extensions”를 선택해요.
3. “Developer mode”를 켜고 “+ (from .zip/.crx/.user.js)“를 눌러 다운로드한 설치 파일을 선택해요.
4. 오른쪽 위의 메뉴를 다시 누르면 맨 아래에 YesCaptcha Assistant가 나타나요. 눌러서 열고 `clientKey`를 입력해요. 잔액이 보이면 설정이 끝난 거예요.
브라우저에서 이 동영상을 재생할 수 없어요. 다운로드해서 보세요: [영상: Kiwi Browser에서 설치 (16초, 영상은 이전 버전이지만 단계는 같아요)](https://docs.yescaptcha.com/videos/extension-kiwi.mp4)
영상: Kiwi Browser에서 설치 (16초, 영상은 이전 버전이지만 단계는 같아요)
## 설정
1. [yescaptcha.com](https://yescaptcha.com/)에서 회원가입하고 충전한 뒤, 대시보드에서 `clientKey`를 복사해요. 자세한 내용은 [빠른 시작](https://docs.yescaptcha.com/ko/getting-started/quickstart.md)을 참고하세요.
2. 확장 프로그램 아이콘을 클릭하고 설정 패널에 ClientKey를 입력해요. 잔액이 보이면 설정이 끝난 거예요.
3. 캡차가 있는 웹페이지를 열면 확장 프로그램이 자동으로 인식을 시작해요.
## 비용
확장 프로그램은 무료예요. 인식할 때 사용한 유형 기준으로 포인트가 차감돼요. 예를 들어 reCAPTCHA 이미지 문제는 [reCAPTCHA v2 이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md) 가격, hCaptcha는 [hCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification.md) 가격으로 계산해요. 잘못 인식한 결과는 신고해서 포인트 환불을 신청할 수 있어요. 자세한 내용은 [요금과 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.
---
# 캡차 유형 판별하기
> 웹 페이지의 캡차가 어떤 종류인지 판별하는 방법과 reCAPTCHA v2, v2 인비저블, v3, Enterprise, hCaptcha, Cloudflare Turnstile, Cloudflare 챌린지 페이지의 차이, 그리고 각각에 맞는 YesCaptcha 작업 유형을 안내해요.
Source: https://docs.yescaptcha.com/ko/guides/identify-captcha/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/identify-captcha/
알맞은 작업 유형을 고르려면 먼저 캡차를 알아봐야 해요. 가장 확실한 방법은 브라우저 개발자 도구(F12)를 열고 Network(네트워크) 패널에서 페이지가 어떤 캡차 스크립트를 불러오는지 확인하는 거예요. 겉모습으로도 판단할 수 있어요.
## 모양으로 구별하기
각 캡차가 웹페이지에서 어떻게 보이는지 보여 주는 애니메이션 일러스트예요(스크린샷이 아니에요). 카드를 클릭하면 해당 작업 유형 페이지로 이동해요. 모양만으로 구별하기 어려우면 아래 빠른 참조표와 Network 패널로 확인하세요.
- [reCAPTCHA v2: 체크박스 · 보이지 않는 방식](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md)
- [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md)
- [reCAPTCHA v2 이미지 인식: 3×3 그리드 · 4×4 그리드 · 1×1 단일 이미지](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)
- [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md)
- [hCaptcha 이미지 인식: 이미지 그리드 · 지점 클릭 · 드래그 앤 드롭 · 애니메이션 질문](https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification.md)
- [Cloudflare Turnstile: 자동 · 체크박스](https://docs.yescaptcha.com/ko/tasks/turnstile.md)
- [Cloudflare 챌린지 페이지: 자동 · 체크박스](https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge.md)
- [FunCaptcha 이미지 인식: 화살표 · 6개 이미지 그리드](https://docs.yescaptcha.com/ko/tasks/funcaptcha-classification.md)
- [AWS WAF / bCaptcha 이미지 인식: AWS WAF · bCaptcha](https://docs.yescaptcha.com/ko/tasks/aws-bcaptcha-classification.md)
- [이미지 영문·숫자 인식: 노이즈 · 노이즈 선 · 수식](https://docs.yescaptcha.com/ko/tasks/image-to-text.md)
## 빠른 참조표
| 보이는 모습 | 종류 | 사용할 작업 유형 |
| --- | --- | --- |
| “로봇이 아닙니다(I’m not a robot)” 체크박스 | reCAPTCHA v2 | [reCAPTCHA v2](https://docs.yescaptcha.com/ko/tasks/recaptcha-v2.md) |
| 체크박스가 없고, 제출을 누르면 이미지 문제가 나타나요. 오른쪽 아래에 reCAPTCHA 배지가 있어요 | reCAPTCHA v2 인비저블(또는 v3) | 아래 “reCAPTCHA 버전”을 참고하세요 |
| 아무 상호작용 없이 오른쪽 아래에 reCAPTCHA 배지만 있어요 | reCAPTCHA v3 | [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md) |
| “I am human” 체크박스, hCaptcha 표시가 있는 이미지 문제 | hCaptcha | [hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md) |
| 폼 안에 Cloudflare 인증 상자가 들어 있고, 체크한 뒤에도 페이지가 이동하지 않아요 | Cloudflare Turnstile | [Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md) |
| 페이지 전체에 “Just a moment…” / “Checking your connection”이 표시되고 자동으로 이동해요 | Cloudflare 챌린지 페이지 | [Cloudflare 챌린지 페이지](https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge.md) |
| Arkose Labs의 퍼즐, 이미지 선택 문제(예: “올바른 방향의 이미지를 고르세요”) | FunCaptcha | [FunCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/funcaptcha-classification.md) |
| 글자와 숫자가 왜곡된 이미지 한 장 | 문자 캡차 | [이미지 영숫자 인식](https://docs.yescaptcha.com/ko/tasks/image-to-text.md) |
## reCAPTCHA 버전
Network 패널에서 `api.js` 또는 `enterprise.js`를 검색하세요.
| 불러온 스크립트 | 버전 |
| --- | --- |
| `recaptcha/api.js`, `render` 파라미터가 없거나 `render=explicit` | v2 일반 버전 |
| 위와 같고, `anchor` 요청 주소에 `size=invisible`이 있어요 | v2 인비저블 버전, 작업에 `"isInvisible": true`를 추가하세요 |
| `recaptcha/api.js?render=SITE_KEY` (`render`가 `explicit`이 아닌 경우) | v3 일반 버전 |
| `recaptcha/enterprise.js`, `render` 파라미터가 없거나 `render=explicit` | v2 Enterprise 버전 |
| `recaptcha/enterprise.js?render=SITE_KEY` | v3 Enterprise 버전 |
예시:
```text
https://www.google.com/recaptcha/api.js?onload=onloadcallback&render=explicit → v2
https://www.google.com/recaptcha/api.js?render=6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696 → v3
https://www.google.com/recaptcha/enterprise.js?render=explicit → v2 Enterprise
```
v2 인비저블 버전은 v3 유형으로만 통과되는 경우도 있으니 두 가지를 모두 시도해 보세요.
콘솔(Console)에서 아래 코드를 실행할 수도 있어요. 페이지에 있는 모든 reCAPTCHA의 버전, 사이트 키, 페이지 주소, 콜백 함수를 나열해 줘요.
find-recaptcha-clients.js
```js
// Paste into the browser DevTools console on a page with reCAPTCHA, then run findRecaptchaClients().
// Lists every reCAPTCHA on the page: version (V2/V3), sitekey, page URL and the callback function.
function findRecaptchaClients() {
if (typeof ___grecaptcha_cfg === 'undefined') return [];
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([, value]) => value && typeof value === 'object');
objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(
([, value]) => value && typeof value === 'object' && 'sitekey' in value && 'size' in value,
);
if (toplevel instanceof HTMLElement && toplevel.tagName === 'DIV') data.pageurl = toplevel.baseURI;
if (found) {
const [sublevelKey, sublevel] = found;
data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
findRecaptchaClients();
```
실행 결과 예시:
```json
[
{
"id": "0",
"version": "V2",
"sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"function": "onSuccess",
"callback": "___grecaptcha_cfg.clients['0']['l']['l']['callback']",
"pageurl": "https://www.google.com/recaptcha/api2/demo"
}
]
```
비교용으로 Google 공식 데모 페이지를 사용할 수 있어요. v2 일반 버전은 `https://www.google.com/recaptcha/api2/demo`, v2 인비저블 버전은 `https://www.google.com/recaptcha/api2/demo?invisible=true`예요.
## Turnstile과 Cloudflare 챌린지 페이지
둘 다 Cloudflare에서 제공하지만 서로 다른 종류예요.
- **Turnstile**은 웹 페이지 폼에 삽입된 인증 상자예요. 인증이 끝나면 체크 표시가 나타나고 페이지는 이동하지 않아요. 페이지가 `challenges.cloudflare.com/turnstile/v0/api.js`를 불러와요. [Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md)을 사용하세요.
- **Cloudflare 챌린지 페이지**는 페이지 전체가 Cloudflare의 검사 화면(“Just a moment…”, “example.com needs to review the security of your connection”)으로 바뀌어요. 안에 인증 상자가 있을 수도 있고, 통과하면 실제 페이지로 자동 이동해요. 소스에 `__cf_chl_rt_tk` 또는 `cdn-cgi/challenge-platform`이 있어요. [Cloudflare 챌린지 페이지](https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge.md)를 사용하세요.
프로그램으로 요청하면 403과 “Just a moment…“가 반환되는데 브라우저로는 바로 열린다면, 대부분 TLS 핑거프린트 때문에 차단된 거예요. 브라우저의 TLS 핑거프린트를 흉내 내는 라이브러리(예: curl\_cffi)로 바꾸면 요청할 수 있고, 챌린지를 풀 필요가 없어요.
---
# reCAPTCHA 파라미터 찾기
> reCAPTCHA의 websiteKey(sitekey), websiteURL, v3의 pageAction, 콜백 함수를 개발자 도구의 Network, Sources, Console에서 찾는 방법과 자동 조회 스크립트를 안내해요.
Source: https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/find-recaptcha-parameters/
reCAPTCHA 작업을 만들려면 `websiteURL`(캡차가 나타나는 페이지 주소)과 `websiteKey`(사이트 키)가 필요하고, v3는 `pageAction`도 필요해요. Selenium 같은 도구로 제출을 시뮬레이션할 때는 콜백 함수도 알아야 해요. 이 값들은 모두 브라우저 개발자 도구(F12)에서 찾을 수 있어요.
## 가장 빠른 방법: 자동 조회 스크립트
캡차가 나타나는 페이지를 열고 F12를 눌러 콘솔(Console)을 연 다음, 아래 스크립트를 붙여넣고 실행하세요.
find-recaptcha-clients.js
```js
// Paste into the browser DevTools console on a page with reCAPTCHA, then run findRecaptchaClients().
// Lists every reCAPTCHA on the page: version (V2/V3), sitekey, page URL and the callback function.
function findRecaptchaClients() {
if (typeof ___grecaptcha_cfg === 'undefined') return [];
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([, value]) => value && typeof value === 'object');
objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(
([, value]) => value && typeof value === 'object' && 'sitekey' in value && 'size' in value,
);
if (toplevel instanceof HTMLElement && toplevel.tagName === 'DIV') data.pageurl = toplevel.baseURI;
if (found) {
const [sublevelKey, sublevel] = found;
data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
findRecaptchaClients();
```
결과에서 `sitekey`가 `websiteKey`, `pageurl`이 `websiteURL`이에요. `version`은 v2인지 v3인지를 나타내고, `function`과 `callback`은 콜백 함수예요.
```json
[
{
"id": "0",
"version": "V2",
"sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"function": "onSuccess",
"callback": "___grecaptcha_cfg.clients['0']['l']['l']['callback']",
"pageurl": "https://www.google.com/recaptcha/api2/demo"
}
]
```
빈 배열이 반환되면 페이지에 reCAPTCHA가 아직 로드되지 않은 거예요. 캡차가 나타난 뒤에 다시 실행하세요.
## websiteKey와 websiteURL
Network 패널에서 `anchor`를 검색해 다음과 같은 요청을 찾으세요.
```text
https://www.google.com/recaptcha/api2/anchor?ar=1&k=6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9&co=...&hl=en&size=normal
```
- `k=` 뒤의 값이 `websiteKey`예요.
- `websiteURL`에는 캡차가 나타나는 페이지의 전체 주소를 넣으세요(이 요청의 `Referer`가 보통 그 주소예요).
페이지 소스에서 `data-sitekey`를 검색해도 찾을 수 있어요.
## pageAction (v3)
`pageAction`은 페이지가 `grecaptcha.execute(사이트 키, {action: '...'})`를 호출할 때 전달하는 `action` 값이에요. 반드시 페이지와 같아야 해요.
**방법 1: 소스 검색.** 개발자 도구의 Sources 패널에서 마우스 오른쪽 버튼을 눌러 “Search in all files”를 선택하세요. 일반 v3는 `.execute(`, Enterprise v3는 `.enterprise.execute`를 검색하고 뒤에 오는 `action`을 확인하세요.
```js
grecaptcha.ready(function () {
grecaptcha.execute('6LdpS-gUAAAAAL3Qr2yP7rkrQjkKBVvEY_48JS5l', { action: 'login' }).then(function (token) {
// ...
});
});
```
여기서 `pageAction`은 `login`이에요.
**방법 2: 브레이크포인트.** 코드가 난독화되어 검색되지 않으면 콘솔에서 `debug(grecaptcha.execute)`(Enterprise는 `debug(grecaptcha.enterprise.execute)`)를 실행한 뒤, 페이지에서 검증이 발생하는 동작(예: 로그인 클릭)을 하세요. 브레이크포인트에서 멈추면 오른쪽 Scope에서 `action` 값을 확인하세요.
한 사이트가 단계마다 다른 `action`을 쓸 수도 있어요(예: 회원가입 시 먼저 `signup/submit_email`, 그다음 `signup/success`). 통과하려는 단계의 값을 사용하세요. F8을 누르면 계속 실행되어 다음 `action`을 볼 수 있어요.
## 콜백 함수
Selenium 등으로 브라우저에 토큰을 입력할 때는, 입력한 뒤 페이지의 콜백 함수를 호출해 검증이 끝났음을 페이지에 알려야 해요.
- Elements 패널에서 `data-callback`을 검색하세요. 그 값이 콜백 함수 이름이에요. 예: `data-callback="onSuccess"`
- 또는 `grecaptcha.render`를 검색해 인자의 `callback`을 확인하세요.
- 또는 콘솔에서 `___grecaptcha_cfg.clients`를 확인하거나 위의 자동 조회 스크립트를 사용하세요.
호출 방법:
```python
driver.execute_script("onSuccess(arguments[0])", g_recaptcha_response)
```
콜백 함수가 없는 페이지도 있어요. 이럴 때는 토큰을 `g-recaptcha-response` 텍스트 상자에 입력한 뒤 바로 폼을 제출하면 돼요. 전체 과정은 [토큰으로 reCAPTCHA 완료하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md)를 참고하세요.
---
# hCaptcha 파라미터 찾기
> hCaptcha의 websiteKey(sitekey), websiteURL, 엔터프라이즈 버전의 rqdata를 찾는 방법이에요. 웹 페이지 소스에서 data-sitekey를 검색하거나 Network에서 checksiteconfig, getcaptcha 요청을 찾아보세요.
Source: https://docs.yescaptcha.com/ko/guides/find-hcaptcha-parameters/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/find-hcaptcha-parameters/
[hCaptcha](https://docs.yescaptcha.com/ko/tasks/hcaptcha.md) 작업을 만들려면 `websiteURL`(캡차가 나타나는 웹 페이지 주소)과 `websiteKey`(사이트 키, UUID 형식)가 필요해요. 엔터프라이즈 버전은 `rqdata`가 추가로 필요할 때도 있어요. 모두 브라우저 개발자 도구(F12)에서 찾을 수 있어요.
## websiteKey
**방법 1: 웹 페이지 소스 검색.** Elements 패널에서 Ctrl+F(Mac은 Cmd+F)를 눌러 `data-sitekey`를 검색하세요.
```html
```
`data-sitekey`의 값이 `websiteKey`예요.
**방법 2: 네트워크 요청 확인.** Network 패널에서 `hcaptcha`를 검색해 `checksiteconfig` 요청을 찾으세요. 주소에서 `sitekey=` 뒤에 있는 값이 `websiteKey`예요.
```text
https://api.hcaptcha.com/checksiteconfig?v=...&host=example.com&sitekey=51829642-2cda-4b09-896c-594f89d700cc&sc=1&swa=1
```
## websiteURL
캡차가 나타나는 웹 페이지의 전체 주소를 입력하세요. `hcaptcha.com`이 **아니에요**. 위 요청의 `host=`가 바로 이 웹 페이지의 도메인이에요.
## rqdata (엔터프라이즈 버전)
일부 웹사이트는 엔터프라이즈 버전 hCaptcha를 사용해요. 캡차를 불러올 때마다 웹사이트가 `rqdata`를 내려주고, 이 값을 보내지 않으면 통과할 수 없어요. 보통 웹사이트 자체 API의 응답(예: 로그인 API가 반환하는 `captcha_rqdata`)에 들어 있거나, `hcaptcha.render` / `hcaptcha.setData`를 호출할 때 전달돼요. 값을 얻으면 작업의 `rqdata` 필드에 넣으세요. `rqdata`는 보통 한 번만 사용할 수 있으므로 매번 새로 가져와야 해요.
## userAgent
`userAgent`에는 [/useragent](https://docs.yescaptcha.com/ko/api/useragent.md)가 반환한 값만 사용할 수 있어요. token을 제출할 때는 인식 결과에 반환된 `userAgent`를 사용하세요.
---
# Turnstile 파라미터 찾기
> Cloudflare Turnstile의 websiteKey(sitekey, 0x로 시작)와 websiteURL을 찾는 방법이에요. 페이지 소스에서 data-sitekey 또는 turnstile.render를 검색하거나, Network 패널에서 challenges.cloudflare.com 요청을 확인하세요.
Source: https://docs.yescaptcha.com/ko/guides/find-turnstile-parameters/ · Last verified: 2026-10-21
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/find-turnstile-parameters/
[Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md) 작업을 만들려면 `websiteURL`(인증 위젯이 나타나는 페이지 주소)과 `websiteKey`(사이트 키, 보통 `0x`로 시작)가 필요해요. 먼저 Cloudflare 챌린지 페이지가 아니라 Turnstile이 맞는지 확인하세요. [캡차 유형 판별하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)를 참고하세요.
## websiteKey
**방법 1: 페이지 소스 검색.** 개발자 도구(F12)의 Elements 패널에서 `data-sitekey`를 검색하세요.
```html
```
**방법 2: 스크립트 검색.** JavaScript로 렌더링한 위젯은 Sources 패널에서 마우스 오른쪽 버튼을 눌러 “Search in all files”를 선택하고 `turnstile.render`를 검색한 뒤, 옵션에 있는 `sitekey`를 확인하세요.
```js
turnstile.render('#container', { sitekey: '0x4AAAAAAAxxxxxxxxxxxxxx', callback: onDone });
```
**방법 3: 네트워크 요청 확인.** Network 패널에서 `challenges.cloudflare.com`을 검색하세요. 위젯 iframe 주소에 `0x`로 시작하는 사이트 키가 들어 있어요.
## websiteURL
인증 위젯이 나타나는 페이지의 전체 주소를 입력하세요. 예: `https://example.com/login`
## action과 cData (보통 필요 없어요)
대부분의 경우 필요하지 않아요. `websiteKey`와 `websiteURL`이 모두 맞는데도 작업이 계속 실패할 때만 찾아보세요. `turnstile.render`의 옵션이나 위젯 요소에 `action`, `cData`가 있는지 확인하면 돼요(요소에서는 `data-action`, `data-cdata`).
```js
turnstile.render('#container', { sitekey: '0x4AAAAAAAxxxxxxxxxxxxxx', action: 'login', cData: 'c0bd4b36-7419-4e18-83c6-378699f2a9a2' });
```
값이 있으면 작업을 만들 때 `action`은 `pageAction`에, `cData`는 `data`에 넣으세요. [Turnstile](https://docs.yescaptcha.com/ko/tasks/turnstile.md)을 참고하세요.
## 토큰 제출
작업이 완료되면 `token`을 폼의 `cf-turnstile-response`라는 이름의 숨김 필드에 넣고(`turnstile.render`에 `callback`을 설정했다면 그 콜백 함수를 호출하면서 토큰을 전달하세요) 폼을 제출하세요. 제출 요청의 User-Agent는 결과에 포함된 `userAgent`를 사용하세요.
---
# token으로 reCAPTCHA 완료하기
> reCAPTCHA의 token(gRecaptchaResponse)을 받은 뒤 사용하는 방법을 설명해요. 동작 원리, 직접 요청으로 제출하기(g-recaptcha-response 필드), 브라우저에 입력하고 콜백 함수 호출하기, 그리고 Google 데모 페이지의 전체 Python 예제를 담았어요.
Source: https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/submit-recaptcha-token/
YesCaptcha가 반환하는 `gRecaptchaResponse`는 웹 페이지에서 캡차를 완료한 뒤 Google이 페이지에 전달하는 결과와 같은 값이에요. 이 값을 받으면 브라우저처럼 **대상 웹사이트에 제출**해야 해요(Google이나 YesCaptcha에 제출하는 게 아니에요). 웹사이트는 이 값을 Google에 확인한 뒤 통과시켜요. 방법은 두 가지예요. 직접 요청을 보내 제출하거나, 브라우저에서 페이지에 입력한 뒤 제출해요.
## 동작 원리
일반적인 접속 흐름은 다음과 같아요.
1. 웹 페이지가 reCAPTCHA를 로드하고, 사용자가 인증을 완료해요.
2. Google이 페이지에 token을 주고, 페이지는 이를 `g-recaptcha-response` 텍스트 상자에 넣어요(또는 콜백 함수에 전달해요).
3. 사용자가 폼을 제출하면 token이 폼과 함께 웹사이트 서버로 전송돼요.
4. 웹사이트 서버가 token을 Google에 확인하고, 통과하면 요청을 허용해요.
YesCaptcha를 사용하면 1, 2단계는 저희가 처리해요. `websiteURL`과 `websiteKey`로 작업을 생성해 token을 받은 뒤, 3단계부터 이어서 진행하면 돼요.
> **주의:** token은 일회용이며 약 120초 동안 유효해요. 받은 뒤 60초 이내에 제출하는 것을 권장해요. 만료된 token은 웹사이트에서 받아주지 않아요.
## 방법 1: 직접 요청으로 제출하기 (권장)
1. 브라우저에서 한 번 정상적으로 진행해요. F12를 눌러 Network 패널을 열고, 캡차를 완료한 뒤 제출해서 폼을 제출하는 요청을 찾아요.
2. 요청의 Payload(또는 Form Data)에서 token을 담은 필드를 찾아요. 보통 `g-recaptcha-response`이고, token은 `03A`로 시작해요. 일부 웹사이트는 이름을 바꾸기도 해요. 예를 들면 `grecaptcharesponse`, `captcha`가 있어요.
3. 프로그램에서 똑같은 요청을 보내되, 해당 필드의 값을 YesCaptcha가 반환한 token으로 바꿔요. 다른 필드, Cookie, 요청 헤더도 브라우저와 동일해야 해요. 웹사이트가 이들을 함께 검사하는 경우가 많아요.
Google 데모 페이지의 전체 예제예요. 먼저 인식한 뒤, token을 `g-recaptcha-response` 필드로 데모 페이지에 다시 제출해요.
recaptcha_requests.py
```python
"""Solve reCAPTCHA v2 on Google's demo page and submit the token with plain HTTP (no browser).
Run: pip install requests
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_requests.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
WEBSITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
def call(method, payload):
data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def get_token():
task = {"type": "NoCaptchaTaskProxyless", "websiteURL": WEBSITE_URL, "websiteKey": WEBSITE_KEY}
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]["gRecaptchaResponse"]
raise TimeoutError(task_id)
token = get_token()
print("token:", token[:40], "...")
# Submit the token the same way the browser does: the demo form posts the field
# "g-recaptcha-response" back to the page. Check your own site's request in DevTools > Network.
page = requests.post(WEBSITE_URL, data={"g-recaptcha-response": token}, timeout=30)
print("passed" if "Verification Success" in page.text else "not passed", page.status_code)
```
## 방법 2: 브라우저에 입력하기 (Selenium 등)
Selenium, Playwright 같은 도구로 실제 브라우저를 조작할 때는 다음과 같이 해요.
1. 페이지에서 `data-sitekey`를 읽고, 이 값으로 작업을 생성해 token을 받아요.
2. token을 페이지의 `g-recaptcha-response` 텍스트 상자에 써 넣어요.
3. 페이지에 콜백 함수(`data-callback="..."`)가 설정되어 있으면 token을 전달해 호출해요. 일부 웹사이트는 콜백을 호출해야 제출 버튼이 클릭 가능해져요.
4. 폼을 제출해요.
```js
// Step 2: write the token (run in the page)
document.getElementById('g-recaptcha-response').value = 'TOKEN';
// Step 3: call the callback if there is one, e.g. data-callback="onSuccess"
onSuccess('TOKEN');
```
페이지에 reCAPTCHA가 여러 개 있으면 텍스트 상자의 id가 `g-recaptcha-response-1`처럼 될 수 있어요. 이 텍스트 상자를 찾을 수 없으면, 먼저 수동으로 인증을 한 번 완료하고 Elements에서 `03A`를 검색해 결과가 어디에 들어가는지 확인해 보세요. 콜백 함수를 찾는 방법은 [reCAPTCHA 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md)를 참고하세요.
전체 예제(Selenium 4)예요.
recaptcha_selenium.py
```python
"""Solve reCAPTCHA v2 on Google's demo page in a real browser with Selenium 4:
get a token from YesCaptcha, put it into the page, then submit the form.
Run: pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_selenium.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time
import requests
from selenium import webdriver
from selenium.webdriver.common.by import By
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
def call(method, payload):
data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def get_token(website_url, website_key):
task = {"type": "NoCaptchaTaskProxyless", "websiteURL": website_url, "websiteKey": website_key}
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36):
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]["gRecaptchaResponse"]
raise TimeoutError(task_id)
driver = webdriver.Chrome() # Selenium 4 downloads a matching chromedriver automatically
try:
driver.get(WEBSITE_URL)
site_key = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-sitekey")
token = get_token(WEBSITE_URL, site_key)
# Put the token where reCAPTCHA keeps it ...
driver.execute_script(
"document.getElementById('g-recaptcha-response').value = arguments[0];", token
)
# ... and, if the page uses a callback (data-callback="..."), call it:
callback = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-callback")
if callback:
driver.execute_script(f"window[{callback!r}](arguments[0]);", token)
driver.find_element(By.ID, "recaptcha-demo-submit").click()
time.sleep(2)
print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
driver.quit()
```
## reCAPTCHA v3
v3에는 체크박스가 없어요. 웹 페이지가 필요할 때 `grecaptcha.execute(사이트 키, {action: '...'})`를 호출해 token을 받고, 그 token을 자체 요청에 넣어요(필드 이름은 웹사이트가 정해요. 흔히 `g-recaptcha-response`, `token`, `recaptchaToken`을 써요). 방법은 방법 1과 같아요. Network에서 token이 담긴 요청을 찾아 그대로 보내면 돼요. 작업을 생성할 때 `pageAction`은 웹 페이지의 `action`과 일치해야 해요.
## 제출했는데도 통과하지 않을 때
- token이 만료됐어요. 받은 뒤 최대한 빨리, 60초를 넘기지 말고 제출하세요.
- 웹사이트가 검사하는 필드가 아닌 곳에 제출했거나, 다른 필드나 Cookie가 빠졌어요. 브라우저의 요청과 항목별로 대조해 확인하세요.
- 웹사이트가 IP, User-Agent 등도 함께 검사해요. 자체 프록시를 사용하는 유형(예: `NoCaptchaTask`)을 쓰고, 제출할 때도 같은 프록시를 거치세요.
- v3 점수가 부족해요. `pageAction`을 확인하거나 고정 고점수 유형으로 바꾸세요. [reCAPTCHA v3](https://docs.yescaptcha.com/ko/tasks/recaptcha-v3.md)를 참고하세요.
- 웹사이트의 위험 탐지가 다른 행동 신호도 확인해요. token 방식의 통과율이 낮으면 [이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)으로 브라우저에서 실제로 클릭하거나, [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)을 사용하세요.
---
# reCAPTCHA v2 이미지 인식 클릭 시뮬레이션(Selenium)
> Python Selenium 4와 ReCaptchaV2Classification으로 브라우저에서 reCAPTCHA v2 이미지 문제를 자동으로 클릭해요. 캡차 실행, 질문과 이미지 읽기, 인식 API 호출, 칸 클릭, 제출까지 전체 예제 코드를 제공해요.
Source: https://docs.yescaptcha.com/ko/guides/recaptcha-click-selenium/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/recaptcha-click-selenium/
이 튜토리얼에서는 Selenium 4로 Google의 reCAPTCHA 데모 페이지를 열고, 실제 브라우저에서 이미지 문제를 풀어요. 질문과 이미지를 읽은 뒤 [reCAPTCHA v2 이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)(`ReCaptchaV2Classification`)에 보내 어느 칸을 클릭해야 하는지 판단하게 하고, 그 칸을 클릭해요. 토큰을 받는 방식과 달리 브라우저 안에서 직접 검증을 통과하므로, 토큰 통과율이 낮은 사이트에 적합해요.
코드를 작성하고 싶지 않다면 [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)을 바로 사용하세요. 같은 API를 기반으로 자동 클릭해요.
## 준비
```bash
pip install requests selenium pillow
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
Chrome이 설치되어 있어야 해요. Selenium 4는 버전이 맞는 chromedriver를 자동으로 다운로드해요.
## 흐름
1. **체크박스를 클릭해요.** 체크박스는 `title="reCAPTCHA"`인 iframe 안에 있어요. 먼저 그 iframe으로 전환한 뒤 `#recaptcha-anchor`를 클릭해요.
2. **문제 iframe으로 전환해요.** 문제는 다른 iframe(title에 “challenge”가 포함됨) 안에 있어요.
3. **질문을 읽어요.** `.rc-imageselect-desc-wrapper strong` 안의 굵은 글씨가 찾아야 할 대상이에요. 예를 들어 “traffic lights”예요. API에는 질문 ID가 필요하므로 대응표로 이름을 ID(`/m/015qff`)로 바꿔요. [질문 ID](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)를 참고하세요. 브라우저 화면을 영어로 두면 대응표와 비교하기 가장 편해요.
4. **이미지를 가져와요.** 칸에 보이는 이미지는 사실 하나의 큰 이미지예요. `td.rc-imageselect-tile img`의 `src`를 다운로드해요. 9칸(3x3)은 300×300, 16칸(4x4)은 450×450으로 크기를 조정한 뒤 Base64로 변환해요.
5. **인식해요.** `createTask`를 호출하고 유형은 `ReCaptchaV2Classification`, `image`와 `question`을 전달해요. `"confidence": 0.5`를 추가하면 3x3 이미지는 조건에 맞는 칸을 한 번에 모두 반환하므로, 클릭 후 새로 나타나는 작은 이미지를 따로 처리할 필요가 없어요.
6. **클릭해요.** 반환된 `objects`는 칸 번호이며, 0부터 시작해 왼쪽에서 오른쪽, 위에서 아래 순서예요. 해당하는 `td`를 차례로 클릭해요.
7. **검증해요.** `#recaptcha-verify-button`을 클릭해요. 새로운 문제가 다시 나오면 3단계로 돌아가요. 문제 창이 닫히면 통과한 거예요.
8. **양식을 제출해요.** 메인 페이지로 돌아가 제출 버튼을 클릭해요.
## 전체 코드
recaptcha_click_selenium.py
```python
"""Click through a reCAPTCHA v2 image challenge with Selenium 4 and ReCaptchaV2Classification.
Flow: open the page -> click the checkbox -> read the target name and the grid image ->
ask YesCaptcha which tiles to click -> click them -> press Verify. Repeat if a new challenge appears.
Run: pip install requests selenium pillow
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_click_selenium.py
Each recognized image is charged (see the price list). reCAPTCHA's page structure can change;
adjust the selectors below if a step stops working.
"""
import base64
import io
import os
import time
import requests
from PIL import Image
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
PAGE_URL = "https://www.google.com/recaptcha/api2/demo"
# Target names shown in the challenge (English UI) -> question IDs.
# Full list: https://docs.yescaptcha.com/en/tasks/recaptcha-classification/
QUESTION_IDS = {
"taxis": "/m/0pg52", "bus": "/m/01bjv", "buses": "/m/01bjv", "motorcycles": "/m/04_sv",
"tractors": "/m/013xlm", "chimneys": "/m/01jk_4", "crosswalks": "/m/014xcs",
"traffic lights": "/m/015qff", "bicycles": "/m/0199g", "parking meters": "/m/015qbp",
"cars": "/m/0k4j", "bridges": "/m/015kr", "boats": "/m/019jd", "palm trees": "/m/0cdl1",
"mountains or hills": "/m/09d_r", "fire hydrants": "/m/01pns0", "a fire hydrant": "/m/01pns0",
"stairs": "/m/01lynh",
}
def classify(image_b64, question):
task = {"type": "ReCaptchaV2Classification", "image": image_b64, "question": question, "confidence": 0.5}
data = requests.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
timeout=30,
).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data["solution"] # synchronous: the solution comes back right away
def grid_image_b64(url, size):
"""Download the challenge image and scale it to the standard size (300 for 3x3, 450 for 4x4)."""
img = Image.open(io.BytesIO(requests.get(url, timeout=30).content)).convert("RGB")
img = img.resize((size, size))
buf = io.BytesIO()
img.save(buf, format="JPEG")
return base64.b64encode(buf.getvalue()).decode()
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)
try:
driver.get(PAGE_URL)
# 1. Click the checkbox (inside the "reCAPTCHA" iframe)
wait.until(EC.frame_to_be_available_and_switch_to_it((By.CSS_SELECTOR, 'iframe[title="reCAPTCHA"]')))
wait.until(EC.element_to_be_clickable((By.ID, "recaptcha-anchor"))).click()
driver.switch_to.default_content()
# 2. Switch to the challenge iframe and solve rounds until it closes
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.XPATH, '//iframe[contains(@title, "challenge")]')))
for _ in range(5):
target = wait.until(EC.presence_of_element_located(
(By.CSS_SELECTOR, ".rc-imageselect-desc-wrapper strong"))).text.strip().lower()
question = QUESTION_IDS.get(target)
if not question:
print("unsupported target, reloading:", target)
driver.find_element(By.ID, "recaptcha-reload-button").click()
time.sleep(2)
continue
tiles = driver.find_elements(By.CSS_SELECTOR, "td.rc-imageselect-tile")
size = 450 if len(tiles) == 16 else 300
url = driver.find_element(By.CSS_SELECTOR, "td.rc-imageselect-tile img").get_attribute("src")
solution = classify(grid_image_b64(url, size), question)
for index in solution.get("objects", []):
tiles[index].click()
time.sleep(0.3)
time.sleep(1)
driver.find_element(By.ID, "recaptcha-verify-button").click()
time.sleep(3)
driver.switch_to.default_content()
frame = driver.find_element(By.XPATH, '//iframe[contains(@title, "challenge")]')
if not frame.is_displayed(): # challenge closed: passed
break
driver.switch_to.frame(frame)
driver.switch_to.default_content()
driver.find_element(By.ID, "recaptcha-demo-submit").click()
time.sleep(2)
print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
driver.quit()
```
## 참고
- reCAPTCHA의 페이지 구조는 업데이트되므로, 코드의 선택자가 동작하지 않으면 실제 페이지에 맞게 조정해야 해요.
- 이미지를 한 장 인식할 때마다 포인트가 차감돼요(가격은 [reCAPTCHA v2 이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md) 참고). 클릭 후 검증에 실패한 작업은 1시간 안에 [신고](https://docs.yescaptcha.com/ko/api/report.md)하여 포인트 환불을 신청할 수 있어요.
- 대응표에 없는 질문이 나오면 새로고침 버튼을 눌러 다른 문제로 바꾸거나, 고객 지원에 문의해 지원을 추가해 달라고 요청하세요.
---
# hCaptcha 이미지 인식 클릭 시뮬레이션(Selenium)
> Python Selenium 4와 HCaptchaClassification으로 브라우저에서 hCaptcha의 3×3 그리드 이미지 문제를 자동으로 풀어요. 체크박스 클릭, 질문과 이미지 9장 읽기, 인식 API 호출, 클릭, 제출까지 전체 예제 코드를 제공해요.
Source: https://docs.yescaptcha.com/ko/guides/hcaptcha-click-selenium/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/hcaptcha-click-selenium/
이 튜토리얼은 Selenium 4로 hCaptcha 데모 페이지를 열고, 실제 브라우저에서 3×3 그리드 이미지 문제를 풀어요. 질문과 이미지 9장을 읽은 뒤 [hCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification.md)(`HCaptchaClassification`)에 보내 어떤 칸이 목표인지 판단하게 하고, 그 칸을 클릭해요.
hCaptcha에는 “지정한 위치 클릭”, “드래그” 같은 문제 유형도 있어요. 이런 유형은 칸이 아니라 좌표를 반환해요. 처리 방법은 [hCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/hcaptcha-classification.md)을 참고하세요. 코드를 작성하고 싶지 않다면 [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)을 바로 사용하세요. 이 문제 유형을 모두 지원해요.
## 준비
```bash
pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## 흐름
1. **체크박스를 클릭해요.** 체크박스는 주소에 `frame=checkbox`가 포함된 hCaptcha iframe 안에 있어요. 해당 iframe으로 전환한 뒤 `#checkbox`를 클릭하세요.
2. **문제 iframe으로 전환해요.** 문제는 주소에 `frame=challenge`가 포함된 iframe 안에 있어요.
3. **질문을 읽어요.** `.prompt-text`의 텍스트가 질문이에요. 그대로 API에 전달하세요(hCaptcha 인터페이스 언어를 영어 또는 중국어 간체로 바꾸는 것을 권장해요). 질문 옆에 예시 이미지가 있으면 그 이미지도 `anchors`에 넣으세요.
4. **이미지를 가져와요.** 각 칸 `.task-image .image`의 배경 이미지가 이미지 한 장이에요. 순서대로 다운로드해 Base64로 변환하고 `queries` 목록을 만드세요.
5. **인식해요.** `createTask`를 호출하고 유형은 `HCaptchaClassification`으로 지정하세요. 반환된 `objects`는 칸과 하나씩 대응하고, `true`인 칸이 목표예요.
6. **클릭하고 제출해요.** 목표인 칸을 클릭하고 제출 버튼을 누르세요. 여러 라운드가 연속으로 나올 수 있으니 3~6단계를 반복하세요.
7. **완료해요.** 통과하면 페이지의 `h-captcha-response` 필드에 토큰이 들어가요. 이 토큰을 폼과 함께 제출하세요.
## 전체 코드
hcaptcha_click_selenium.py
```python
"""Click through an hCaptcha 3x3 image challenge with Selenium 4 and HCaptchaClassification.
Flow: open the page -> click the checkbox -> read the question and the 9 images ->
ask YesCaptcha which images match -> click them -> submit. Repeat while new rounds appear.
Run: pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
python hcaptcha_click_selenium.py
Each recognized round is charged (see the price list; rounds with no target found are free).
hCaptcha changes its page structure often; adjust the selectors below if a step stops working.
Click and drag questions return coordinates instead; see the HCaptchaClassification page.
"""
import base64
import os
import re
import time
import requests
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
PAGE_URL = "https://accounts.hcaptcha.com/demo"
def classify(question, images_b64):
task = {"type": "HCaptchaClassification", "question": question, "queries": images_b64}
data = requests.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
timeout=60,
).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data["solution"] # synchronous
def background_image_b64(element):
"""The tiles are s with a CSS background image; download it and Base64-encode it."""
style = element.get_attribute("style") or ""
match = re.search(r'url\("?(.*?)"?\)', style)
if not match:
return None
return base64.b64encode(requests.get(match.group(1), timeout=30).content).decode()
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)
try:
driver.get(PAGE_URL)
# 1. Click the checkbox (inside the first hCaptcha iframe)
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.CSS_SELECTOR, 'iframe[src*="hcaptcha"][src*="frame=checkbox"]')))
wait.until(EC.element_to_be_clickable((By.ID, "checkbox"))).click()
driver.switch_to.default_content()
# 2. Solve rounds in the challenge iframe
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.CSS_SELECTOR, 'iframe[src*="hcaptcha"][src*="frame=challenge"]')))
for _ in range(5):
question = wait.until(EC.presence_of_element_located((By.CSS_SELECTOR, ".prompt-text"))).text.strip()
tiles = driver.find_elements(By.CSS_SELECTOR, ".task-image")
images = [background_image_b64(t.find_element(By.CSS_SELECTOR, ".image")) for t in tiles]
if not tiles or None in images:
print("not a 3x3 image challenge; see the docs for click/drag questions")
break
solution = classify(question, images)
for tile, hit in zip(tiles, solution.get("objects", [])):
if hit:
tile.click()
time.sleep(0.3)
driver.find_element(By.CSS_SELECTOR, ".button-submit").click()
time.sleep(3)
if not driver.find_elements(By.CSS_SELECTOR, ".task-image"):
break
driver.switch_to.default_content()
token = driver.find_element(By.NAME, "h-captcha-response").get_attribute("value")
print("token received" if token else "not passed")
finally:
driver.quit()
```
## 참고
- hCaptcha의 페이지 구조는 자주 바뀌어요. 코드의 선택자가 동작하지 않으면 실제 페이지에 맞게 조정하세요.
- 라운드마다 포인트가 차감돼요. 목표를 인식하지 못한 라운드는 차감되지 않아요. 클릭 후 검증에 실패했다면 1시간 이내에 [신고](https://docs.yescaptcha.com/ko/api/report.md)해서 포인트 환불을 신청할 수 있어요.
- 새로운 질문에서 `ERROR_UNKNOWN_QUESTION`이 반환되면 새로고침해서 다른 문제를 받거나 고객 지원에 문의하세요.
---
# 예제 코드와 SDK
> YesCaptcha의 바로 실행할 수 있는 예제 코드(Python, Node.js, curl, C#, 이지 랭귀지)와 사용자가 제공한 비공식 SDK(Python, Node.js, Go)예요.
Source: https://docs.yescaptcha.com/ko/samples/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/
여기 있는 예제는 모두 바로 실행할 수 있는 완성된 파일이며, 환경 변수 `YESCAPTCHA_CLIENT_KEY`에서 clientKey를 읽어요. 각 작업 유형 페이지에도 해당 유형에 맞춰 생성한 curl, Python, Node.js 예제가 있어요.
[Python](https://docs.yescaptcha.com/ko/samples/python.md)잔액 조회, 첫 요청, 재사용 가능한 클라이언트, 동시 작업 제어, Selenium
[Node.js](https://docs.yescaptcha.com/ko/samples/nodejs.md)Node.js 18+, 서드파티 라이브러리 불필요
[C#](https://docs.yescaptcha.com/ko/samples/csharp.md).NET 6+
[이지 랭귀지](https://docs.yescaptcha.com/ko/samples/easy-language.md)사용자가 제공한 클릭 시뮬레이션 예제
명령줄로만 테스트하려면 [빠른 시작](https://docs.yescaptcha.com/ko/getting-started/quickstart.md)과 [getBalance](https://docs.yescaptcha.com/ko/api/get-balance.md)의 curl 예제를 참고하세요.
## 커뮤니티 SDK
아래 SDK는 사용자가 제공한 **비공식** SDK예요. 코드를 검토하지 않았으니 사용하기 전에 직접 평가하시고, 문제가 있으면 작성자에게 문의하세요.
| 언어 | 프로젝트 |
| --- | --- |
| Python | [github.com/yescaptcha/yescaptcha-python](https://github.com/yescaptcha/yescaptcha-python) |
| Node.js | [github.com/ScoLib/yescaptcha](https://github.com/ScoLib/yescaptcha) |
| Go | [github.com/FreedWu/yescaptcha](https://github.com/FreedWu/yescaptcha) |
| Go | [github.com/deanxv/yescaptcha-go](https://github.com/deanxv/yescaptcha-go) |
어떤 SDK를 사용하든 `api.yescaptcha.com` 또는 `cn.yescaptcha.com`을 호출하는지, 작업 유형 이름이 이 사이트와 같은지 확인하세요.
---
# Python
> YesCaptcha의 Python 예제예요. 잔액 조회, 이미지 캡차 인식, 재사용 가능한 클라이언트 클래스(작업 생성, 5초마다 폴링), asyncio 동시 작업 수 제어, requests와 Selenium으로 reCAPTCHA 제출까지 다뤄요.
Source: https://docs.yescaptcha.com/ko/samples/python/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/python/
실행 환경: Python 3.8 이상, `pip install requests`. 실행하기 전에 환경 변수를 설정하세요:
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## 잔액 조회
포인트가 차감되지 않으며, clientKey가 올바른지 확인할 때 사용해요:
get_balance.py
```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
r = requests.post(
"https://api.yescaptcha.com/getBalance",
json={"clientKey": CLIENT_KEY},
timeout=30,
)
data = r.json()
if data.get("errorId"):
# e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
print("balance (points):", data["balance"])
```
## 이미지 캡차 하나 인식하기
동기 작업 유형 `ImageToTextTaskOcrBase`는 요청 한 번으로 결과를 받아요. 예제 이미지: [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg).
quickstart.py
```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).
Usage:
export YESCAPTCHA_CLIENT_KEY=your_client_key
python quickstart.py captcha.png
"""
import base64
import os
import sys
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
with open(image_path, "rb") as f:
body = base64.b64encode(f.read()).decode() # no "data:" prefix
r = requests.post(
"https://api.yescaptcha.com/createTask",
json={
"clientKey": CLIENT_KEY,
"task": {"type": "ImageToTextTaskOcrBase", "body": body},
},
timeout=30,
)
data = r.json()
if data.get("errorId"):
raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```
## 재사용 가능한 클라이언트
아래 파일을 프로젝트에 복사하세요. 동기와 비동기 작업 유형 모두 사용할 수 있어요:
yescaptcha.py
```python
"""A small client you can copy into your project: create tasks, poll results, check the balance.
from yescaptcha import YesCaptcha
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
"""
import os
import time
import requests
class YesCaptchaError(Exception):
def __init__(self, code, description):
super().__init__(f"{code}: {description}")
self.code = code
self.description = description
class YesCaptcha:
def __init__(self, client_key, endpoint="https://api.yescaptcha.com", poll_interval=5, timeout=180):
self.client_key = client_key
self.endpoint = endpoint.rstrip("/")
self.poll_interval = poll_interval # 5 s: polling the same taskId more often only returns "processing"
self.timeout = timeout
self.session = requests.Session()
def call(self, method, payload=None):
body = {"clientKey": self.client_key, **(payload or {})}
data = self.session.post(f"{self.endpoint}/{method}", json=body, timeout=30).json()
if data.get("errorId"):
raise YesCaptchaError(data.get("errorCode"), data.get("errorDescription"))
return data
def balance(self):
return self.call("getBalance")["balance"]
def solve(self, task):
created = self.call("createTask", {"task": task})
if created.get("status") == "ready": # synchronous types return the solution directly
return created["solution"]
task_id = created["taskId"]
deadline = time.time() + self.timeout
while time.time() < deadline:
time.sleep(self.poll_interval)
result = self.call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(f"task {task_id} not ready after {self.timeout}s")
if __name__ == "__main__":
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
print("balance:", client.balance())
```
```python
from yescaptcha import YesCaptcha
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```
오류가 발생하면 `YesCaptchaError`가 발생하고, `e.code`가 오류 코드예요. 의미는 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.
## 동시 작업 수 제어
작업을 일괄로 보낼 때는 동시에 처리 중인 요청 수를 제한하고, `ERROR_THREADS_MAXIMUM`을 받으면 잠시 기다렸다가 다시 시도하세요(`pip install aiohttp` 필요). 자세한 내용은 [동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)를 참고하세요:
concurrency.py
```python
"""Limit concurrency: keep the number of requests waiting for a result below your limit, and back off
on ERROR_THREADS_MAXIMUM (rejected requests are not charged). Requires: pip install aiohttp"""
import asyncio
import os
import aiohttp
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15 # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)
async def solve(session, task):
async with sem: # at most LIMIT requests in progress at a time
result = {}
for attempt in range(5):
async with session.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
) as resp:
result = await resp.json()
if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
return result
await asyncio.sleep(1 + attempt) # over the limit: wait and retry
return result
async def main(tasks):
async with aiohttp.ClientSession() as session:
return await asyncio.gather(*(solve(session, t) for t in tasks))
if __name__ == "__main__":
print(asyncio.run(main([])))
```
## reCAPTCHA 토큰 제출
- requests로 직접 제출: [토큰으로 reCAPTCHA 완료하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md#method-1-send-the-request-yourself-recommended)를 참고하세요
- Selenium으로 브라우저에 입력: [토큰으로 reCAPTCHA 완료하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md#method-2-fill-it-into-the-page-selenium-and-similar)를 참고하세요
- Selenium으로 이미지 문제 클릭 시뮬레이션: [reCAPTCHA v2 이미지 인식 클릭 시뮬레이션](https://docs.yescaptcha.com/ko/guides/recaptcha-click-selenium.md), [hCaptcha 이미지 인식 클릭 시뮬레이션](https://docs.yescaptcha.com/ko/guides/hcaptcha-click-selenium.md)을 참고하세요
---
# Node.js
> YesCaptcha의 Node.js 예제(Node.js 18 이상, 내장 fetch 사용, 서드파티 라이브러리 불필요): 잔액 조회, 이미지 캡차 인식, 재사용 가능한 클라이언트 클래스(작업 생성, 5초마다 폴링).
Source: https://docs.yescaptcha.com/ko/samples/nodejs/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/nodejs/
실행 환경은 Node.js 18 이상(내장 `fetch`)이에요. 예제는 ES module(`.mjs`)이고 서드파티 라이브러리를 설치할 필요가 없어요. 실행하기 전에 환경 변수를 설정하세요:
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## 잔액 조회
포인트가 차감되지 않아요. clientKey가 올바른지 확인할 때 사용하세요:
get-balance.mjs
```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const res = await fetch('https://api.yescaptcha.com/getBalance', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
// e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
console.log('error:', data.errorCode, data.errorDescription);
} else {
console.log('balance (points):', data.balance);
}
```
## 이미지 캡차 인식하기
동기 유형인 `ImageToTextTaskOcrBase`는 요청 한 번으로 결과를 받아요. 예제 이미지: [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg). `node quickstart.mjs captcha.jpg`를 실행하세요.
quickstart.mjs
```js
// First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
// Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
import { readFileSync } from 'node:fs';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
const res = await fetch('https://api.yescaptcha.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
console.log('text:', data.solution.text);
```
## 재사용 가능한 클라이언트
yescaptcha.mjs
```js
// A small client you can copy into your project: create tasks, poll results, check the balance. Node.js 18+
//
// import { YesCaptcha } from './yescaptcha.mjs';
// const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
// const solution = await client.solve({ type: 'NoCaptchaTaskProxyless', websiteURL: '...', websiteKey: '...' });
export class YesCaptchaError extends Error {
constructor(code, description) {
super(`${code}: ${description}`);
this.code = code;
}
}
export class YesCaptcha {
constructor(clientKey, { endpoint = 'https://api.yescaptcha.com', pollInterval = 5000, timeout = 180000 } = {}) {
this.clientKey = clientKey;
this.endpoint = endpoint.replace(/\/$/, '');
this.pollInterval = pollInterval; // 5 s: polling the same taskId more often only returns "processing"
this.timeout = timeout;
}
async call(method, payload = {}) {
const res = await fetch(`${this.endpoint}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: this.clientKey, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new YesCaptchaError(data.errorCode, data.errorDescription);
return data;
}
async balance() {
return (await this.call('getBalance')).balance;
}
async solve(task) {
const created = await this.call('createTask', { task });
if (created.status === 'ready') return created.solution; // synchronous types return the solution directly
const deadline = Date.now() + this.timeout;
while (Date.now() < deadline) {
await new Promise((r) => setTimeout(r, this.pollInterval));
const result = await this.call('getTaskResult', { taskId: created.taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`task ${created.taskId} not ready after ${this.timeout} ms`);
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
console.log('balance:', await client.balance());
}
```
```js
import { YesCaptcha } from './yescaptcha.mjs';
const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
const solution = await client.solve({
type: 'TurnstileTaskProxyless',
websiteURL: 'https://example.com/login',
websiteKey: '0x4AAAAAAA_SITE_KEY',
});
console.log(solution.token);
```
오류가 발생하면 `YesCaptchaError`를 던져요. `err.code`는 오류 코드이고, 의미는 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)에서 확인하세요.
---
# C#
> YesCaptcha의 C# 예제(.NET 6+, HttpClient + System.Text.Json)예요. 잔액을 조회하고, reCAPTCHA v2 작업을 만든 뒤 5초마다 결과를 폴링해요.
Source: https://docs.yescaptcha.com/ko/samples/csharp/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/csharp/
실행 환경: .NET 6 이상이며, 표준 라이브러리(`HttpClient`, `System.Text.Json`)만 사용해요.
```bash
dotnet new console -o YesCaptchaDemo
cd YesCaptchaDemo
# replace Program.cs with the code below
export YESCAPTCHA_CLIENT_KEY=your_client_key
dotnet run
```
Program.cs
```csharp
// YesCaptcha C# sample (.NET 6+): check the balance, then solve a reCAPTCHA v2.
// Run: dotnet new console -o YesCaptchaDemo, replace Program.cs with this file, set YESCAPTCHA_CLIENT_KEY, then dotnet run
using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Threading.Tasks;
class Program
{
const string Api = "https://api.yescaptcha.com";
static readonly HttpClient Http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
static readonly string ClientKey = Environment.GetEnvironmentVariable("YESCAPTCHA_CLIENT_KEY") ?? "";
static async Task Call(string method, JsonObject payload)
{
payload["clientKey"] = ClientKey;
var res = await Http.PostAsJsonAsync($"{Api}/{method}", payload);
var data = JsonNode.Parse(await res.Content.ReadAsStringAsync())!;
if ((int?)data["errorId"] != 0)
throw new Exception($"{data["errorCode"]}: {data["errorDescription"]}");
return data;
}
static async Task Solve(JsonObject task)
{
var created = await Call("createTask", new JsonObject { ["task"] = task });
if ((string?)created["status"] == "ready") return created["solution"]!; // synchronous types
var taskId = (string)created["taskId"]!;
for (var i = 0; i < 36; i++) // poll every 5 seconds, for up to about 3 minutes
{
await Task.Delay(5000);
var result = await Call("getTaskResult", new JsonObject { ["taskId"] = taskId });
if ((string?)result["status"] == "ready") return result["solution"]!;
}
throw new TimeoutException(taskId);
}
static async Task Main()
{
var balance = await Call("getBalance", new JsonObject());
Console.WriteLine($"balance (points): {balance["balance"]}");
var solution = await Solve(new JsonObject
{
["type"] = "NoCaptchaTaskProxyless",
["websiteURL"] = "https://www.google.com/recaptcha/api2/demo",
["websiteKey"] = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
Console.WriteLine(solution["gRecaptchaResponse"]);
}
}
```
다른 작업 유형으로 바꿀 때는 `Solve`에 전달하는 작업 객체만 수정하면 돼요. 필드는 각 [작업 유형](https://docs.yescaptcha.com/ko/tasks.md) 페이지에서 확인하세요. 동기 유형(이미지 인식, `ImageToTextTaskOcrBase`)은 `createTask`에서 바로 결과를 반환하며, `Solve`가 이미 이 경우를 처리해요.
---
# 이지 랭귀지(易语言)
> 사용자가 제공한 YesCaptcha 이지 랭귀지(易语言) 예제예요. reCAPTCHA·hCaptcha 클릭 시뮬레이션, FunCaptcha 이미지 인식, reCAPTCHA 토큰 제출과 다운로드 패키지, API 호출 요령을 안내해요.
Source: https://docs.yescaptcha.com/ko/samples/easy-language/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/samples/easy-language/
이지 랭귀지(易语言)는 중국에서 많이 쓰는 중국어 기반 프로그래밍 언어예요. 이 예제는 사용자(南方填表, 松 등)가 제공한 것이며 참고용이에요. 한 줄씩 검토하지는 않았어요. 예제에는 다음이 포함돼요.
- reCAPTCHA, hCaptcha 클릭 시뮬레이션 (브라우저를 실행한 뒤 자동으로 인식하고 클릭해요)
- FunCaptcha 이미지 인식
- reCAPTCHA 토큰 제출
> **다운로드 패키지:** 예제 패키지(가장 큰 것은 브라우저를 포함해 약 87 MB)는 새 다운로드 주소로 옮기는 중이에요. 그때까지는 [고객 지원](https://docs.yescaptcha.com/ko/help/contact.md)에 문의해서 받으세요.
## 이지 랭귀지로 API 호출하기
예제 패키지가 없어도 이지 랭귀지의 웹 접속 명령(POST)으로 API를 호출할 수 있어요.
1. 주소는 `https://api.yescaptcha.com/createTask`, 메서드는 `POST`예요. 헤더에 `Content-Type: application/json`을 추가하세요.
2. 전송 내용은 JSON 텍스트예요. 예: `{"clientKey":"YOUR_CLIENT_KEY","task":{"type":"ImageToTextTaskOcrBase","body":"BASE64_IMAGE"}}`
3. 응답 JSON에서 `errorId`가 0이면 성공이에요. 비동기 유형은 `taskId`를 받아서 5초마다 `https://api.yescaptcha.com/getTaskResult`에 `{"clientKey":"…","taskId":"…"}`를 보내고, `status`가 `ready`가 될 때까지 폴링하세요.
4. 이미지의 Base64에는 `data:image/...;base64,` 접두사를 붙이지 말고, 줄바꿈도 넣지 마세요.
요청과 응답 형식은 [요청과 응답](https://docs.yescaptcha.com/ko/api/overview.md)을 참고하세요.
## 예제가 실행되지 않을 때
- 브라우저를 만들 수 없다는 메시지가 나올 때: 예제 패키지에 들어 있는 브라우저를 먼저 사용하세요. 충돌할 수 있는 다른 브라우저는 삭제하세요. 또는 프로그램으로 컴파일한 뒤 실행하세요.
- 오류 코드가 반환될 때: [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 보고 파라미터를 확인하세요.
---
# 여러 clientKey: 한도, IP 허용 목록, 만료 시각
> YesCaptcha 계정 하나에 clientKey를 최대 20개 만들 수 있고, 모두 같은 계정 잔액에서 포인트가 차감돼요. 각 clientKey마다 사용 한도(매일, 매주, 매월 또는 1회성, 베이징 시간 기준으로 초기화), IP 허용 목록, 만료 시각을 따로 설정할 수 있고, 몇 초 안에 적용돼요.
Source: https://docs.yescaptcha.com/ko/account/client-keys/ · Last verified: 2026-10-29
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/client-keys/
YesCaptcha 계정 하나에는 `clientKey`를 최대 20개(기존 키 포함) 만들 수 있어요. [yescaptcha.com](https://yescaptcha.com/security) 대시보드의 “키와 보안” 페이지에서 관리해요. 모든 `clientKey`로 작업을 만들고 잔액을 조회할 수 있고, 포인트는 모두 같은 계정 잔액에서 차감돼요. 각 `clientKey`마다 한도, IP 허용 목록, 만료 시각을 따로 설정할 수 있고, 몇 초 안에 적용돼요.
이런 경우에 쓰면 좋아요. 테스트 환경과 운영 환경, 또는 프로젝트별로 키를 나눠 쓸 때. 하위 고객이나 파트너에게 키를 나눠 주고 각자 한도를 둘 때. 어떤 `clientKey`가 유출돼도 그 키만 삭제하면 다른 프로그램은 영향을 받지 않아요.
## 기본 Key와 하위 Key
| | 기본 Key | 하위 Key |
| --- | --- | --- |
| 어떤 키인가요 | 원래 쓰던 `clientKey`예요. 계정마다 하나예요 | 기본 Key 외에 새로 만든 키예요. 최대 19개예요 |
| 한도, IP 허용 목록, 만료 시각 | 설정할 수 있어요 | 설정할 수 있어요 |
| 재설정 | 가능해요. 기존 키는 즉시 사용할 수 없게 되고 잔액이 새 키로 옮겨져요 | 재설정할 수 없어요. 삭제하고 새로 만드세요 |
| 삭제 | 할 수 없어요 | 할 수 있어요. 몇 초 안에 사용할 수 없게 되고 복구할 수 없어요 |
- 형식은 모두 같아요. 앞 40자는 비밀 키이고, 뒤는 내 사용자 ID예요.
- 기본 Key를 재설정해도 하위 Key에는 영향이 없어요.
- 어떤 `clientKey`로 작업을 만들고 잔액을 조회하든 API와 응답은 같아요. 한도, 허용 목록, 만료 시각을 추가로 확인할 뿐이에요.
## 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,000포인트 = ¥1). 1에서 10,000,000,000포인트까지 설정할 수 있어요. 주기는 네 가지이고, 베이징 시간(UTC+8) 기준으로 초기화돼요.
| 주기 | 초기화 시점 |
| --- | --- |
| 매일 | 매일 0시 |
| 매주 | 매주 월요일 0시 |
| 매월 | 매월 1일 0시 |
| 1회성 총액 | 초기화되지 않아요. 다 쓰면 이 `clientKey`로는 더 이상 작업을 만들 수 없어요. 계속 쓰려면 한도를 올리세요 |
- 실제로 차감된 포인트를 기준으로 계산해요. 인식 실패나 시간 초과로 환불된 포인트는 한도에도 되돌아가요.
- 이번 주기에 남은 한도가 작업의 포인트 차감액보다 적으면 `createTask`가 [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED)를 반환해요. 포인트는 차감되지 않고, [자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)에도 포함되지 않아요.
- 대시보드 목록에서 각 `clientKey`가 이번 주기에 얼마나 썼는지, 다음 초기화가 언제인지 볼 수 있어요.
- 한도는 별도의 잔액이 아니에요. 모든 `clientKey`가 같은 계정 잔액에서 차감되고, 계정 잔액이 부족하면 평소처럼 `ERROR_ZERO_BALANCE`가 반환돼요.
한도를 설정한 `clientKey`로 [`getBalance`](https://docs.yescaptcha.com/ko/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 API를 호출하는 머신의 공인 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/ko/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED)를 반환해요. 포인트는 차감되지 않고, 자동 일시 중지에도 포함되지 않아요.
- 외부로 나가는 IP가 바뀌는 환경(가정용 인터넷, 클라우드 함수, 순환하는 출구 IP)에서는 설정하지 않거나, 대역 전체를 허용하세요.
## 만료 시각
- 기본 Key를 포함해 어떤 `clientKey`든 10년 이내로 만료 시각을 설정할 수 있어요. 이후 언제든 수정하거나 없앨 수 있어요.
- 만료된 뒤에는 그 키로 `createTask`, `getBalance`를 호출하면 [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_EXPIRED)가 반환되고 포인트는 차감되지 않아요. 이미 만든 작업은 `getTaskResult`로 계속 결과를 가져올 수 있어요.
- 오랫동안 사용하지 않은 `clientKey`에는 계정 보안을 위해 시스템이 만료 시각을 설정하고, 만료 전에 이메일로 알려 드려요. 이 만료 시각은 수정할 수 없어요. 기본 Key를 다시 생성하거나(잔액이 새 키로 자동으로 옮겨져요) 새 `clientKey`를 만든 뒤 프로그램에 반영하세요.
## 잔액, 동시 작업 수 제한, 자동 일시 중지
- **잔액**: 모든 `clientKey`가 같은 계정 잔액에서 차감돼요. 충전, VIP 보너스, 추천 보상, 개발자 수익 배분은 모두 계정 기준이고, 어떤 `clientKey`를 쓰는지와 관계없어요.
- **동시 작업 수 제한**: 계정 기준으로 계산해요. 모든 `clientKey`가 같은 상한을 함께 적용받아요. [동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)를 참고하세요.
- **자동 일시 중지**: `clientKey`별로 따로 계산해요. 한 `clientKey`가 오류가 너무 많아 일시 중지돼도 다른 키에는 영향이 없어요.
## 관련 오류 코드
| 오류 코드 | 반환되는 경우 |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | 이번 주기에 남은 한도가 이 작업에 부족해요(`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | 요청한 IP가 이 `clientKey`의 IP 허용 목록에 없어요(`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_EXPIRED) | `clientKey`가 만료됐어요(`createTask`, `getBalance`) |
세 가지 모두 포인트가 차감되지 않아요. 해결 방법은 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.
---
# 충전과 VIP
> YesCaptcha 충전 방법(WeChat Pay, Alipay, PayPal, 암호화폐)과 1,000포인트 = ¥1 기준을 안내해요. 누적 충전 금액에 따라 VIP 1부터 VIP 10까지 자동으로 올라가고, 이후 충전할 때마다 비율에 따라 보너스 포인트를 받아요.
Source: https://docs.yescaptcha.com/ko/account/recharge/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/recharge/
[yescaptcha.com](https://yescaptcha.com/) 대시보드의 온라인 충전 페이지([yescaptcha.com/payment.html](https://yescaptcha.com/payment.html))에서 충전하세요. 1,000포인트 = ¥1이며, 입금되면 바로 사용할 수 있어요. 누적 충전 금액이 일정 금액에 도달하면 VIP 등급이 자동으로 올라가고, 이후 충전할 때마다 VIP 등급 비율만큼 보너스 포인트가 추가로 지급돼요.
## 충전 방법
| 방법 | 설명 |
| --- | --- |
| WeChat Pay | QR 코드 스캔 결제 |
| Alipay | QR 코드 스캔 또는 페이지 이동 결제 |
| PayPal | 해외 사용자에게 적합해요 |
| 암호화폐 | Cryptomus를 통해 결제하며 BTC, ETH, USDT 등을 지원해요 |
| 계좌 이체 | 고객 지원에 문의하면 재무 확인 후 수동으로 충전해 드려요 |
충전 내역은 충전 페이지에서 확인할 수 있어요. 충전에 문제가 있으면 주문 정보와 함께 [고객 지원에 문의](https://docs.yescaptcha.com/ko/help/contact.md)하세요.
## VIP 등급
누적 충전 금액이 아래 표의 기준에 도달하면 해당 등급으로 자동 승급돼요. 승급 후에는 매 충전마다 보너스 비율만큼 포인트가 추가로 들어와요.
| 등급 | 누적 충전 | 충전할 때마다 보너스 |
| --- | --- | --- |
| VIP 1 | ¥10 | 2% |
| VIP 2 | ¥100 | 5% |
| VIP 3 | ¥500 | 8% |
| VIP 4 | ¥1,000 | 10% |
| VIP 5 | ¥2,000 | 15% |
| VIP 6 | ¥3,000 | 20% |
| VIP 7 | ¥6,000 | 25% |
| VIP 8 | ¥12,000 | 30% |
| VIP 9 | ¥24,000 | 35% |
| VIP 10 | ¥48,000 | 40% |
- **누적 계산**: 몇 번에 나누어 충전하든 누적 금액이 기준에 도달하면 승급돼요.
- **충전 후 누적 금액 기준**: 예를 들어 첫 충전에서 ¥1,000을 충전해 누적 금액이 VIP 4 기준에 도달하면, 이번 충전부터 VIP 4 비율로 보너스가 지급돼요.
- 친구의 추천 링크로 회원가입하면 일정 VIP 등급을 바로 받아요. [추천 보상](https://docs.yescaptcha.com/ko/account/referral.md)을 참고하세요.
- 현재 등급과 보너스 비율은 대시보드의 충전 페이지에서 확인할 수 있어요.
---
# 추천 보상
> YesCaptcha 추천 보상: 추천받은 사용자는 가입하면 바로 VIP 등급을 받고(내 등급 −1, VIP 1~VIP 6), 나는 상대방 사용 금액의 20%를 받아요(개발자 수익 배분이 함께 있으면 각각 절반씩). 보상은 잔액으로 전환하거나 ¥100 이상일 때 대시보드에서 출금을 신청할 수 있어요.
Source: https://docs.yescaptcha.com/ko/account/referral/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/referral/
친구를 YesCaptcha에 추천하면, 친구는 가입하는 즉시 VIP 등급을 받고 나는 친구가 사용한 금액의 20%를 보상으로 받아요. 보상은 계정 잔액으로 전환하거나, ¥100 이상 쌓이면 대시보드에서 출금을 신청할 수 있어요.
## 추천하는 방법
[yescaptcha.com](https://yescaptcha.com/) 대시보드에 로그인하면 추천 프로그램 패널에서 내 추천 링크, 추천한 사람 수, 누적 보상을 확인할 수 있어요. 추천 링크를 친구에게 보내고, 친구가 그 링크로 가입하면 돼요.
## 규칙
1. **친구의 VIP**: 친구는 가입하면 바로 내 등급에서 1을 뺀 VIP 등급을 받아요. 최저 VIP 1, 최고 VIP 6이에요. 예를 들어 내가 VIP 6이면 친구는 가입 후 VIP 5가 돼요. 등급별 보너스 비율은 [충전 및 VIP](https://docs.yescaptcha.com/ko/account/recharge.md)에서 확인하세요.
2. **내 보상**: 친구가 사용할 때마다(인식 포인트 차감) 사용 금액의 \*\*20%\*\*를 받아요.
3. **개발자 수익 배분과 함께 있을 때**: 친구의 작업에 개발자 ID도 함께 포함되어 있으면([개발자 수익 배분](https://docs.yescaptcha.com/ko/account/developer.md) 참고), 추천인과 개발자가 \*\*각각 10%\*\*를 받아요.
4. 친구가 인식 오류를 신고해서 포인트 환불을 받은 작업은 해당 보상이 회수돼요.
5. 보상 잔액은 [getBalance](https://docs.yescaptcha.com/ko/api/get-balance.md)의 `inviteBalance`로 조회할 수 있어요(단위: 위안).
## 보상 사용하기
- **잔액으로 전환**: 대시보드에서 보상을 계정 잔액으로 옮기면 1,000포인트 = ¥1 기준으로 인식에 사용할 수 있어요.
- **출금**: 보상이 **¥100** 이상이 되면 대시보드에서 출금을 신청하세요. 심사 후 입금돼요.
- 출금 수입에 대한 소득세는 직접 신고해야 해요.
## 글로 추천하기
포럼, 블로그, 소셜 미디어 등에 YesCaptcha 관련 추천 글, 튜토리얼, 사용 후기, 확장 프로그램이나 코드 저장소를 올렸다면 링크를 고객 지원에 보내 주세요. 검토 후 내용의 품질에 따라 포인트나 VIP 등급을 보상으로 드릴 수 있어요.
보상 규칙이 바뀌면 이 페이지와 [서비스 업데이트 기록](https://docs.yescaptcha.com/ko/changelog.md)에 안내해요.
---
# 개발자 수익 배분
> YesCaptcha 개발자 수익 배분: 직접 개발한 소프트웨어나 확장 프로그램이 사용자의 요청에 softID를 포함하면 사용자 소비 금액의 20%를 받아요(추천인도 있으면 각각 10%). 대시보드에서 잔액으로 전환하거나 100위안부터 출금을 신청할 수 있어요.
Source: https://docs.yescaptcha.com/ko/account/developer/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/developer/
직접 개발한 소프트웨어, 스크립트 또는 확장 프로그램이 YesCaptcha를 사용한다면, 다른 사용자를 위해 보내는 요청에 개발자 ID(`softID`)를 포함해 보세요. 사용자의 소비 금액에 따라 수익을 배분받을 수 있어요. 사용자는 자신의 `clientKey`로 자신의 포인트를 차감하므로, 수익 배분 때문에 추가로 내는 비용은 없어요.
## 연동 방법
1. 본인의 `clientKey`로 [getSoftID](https://docs.yescaptcha.com/ko/api/get-soft-id.md)를 호출해 개발자 ID를 받아요.
```json
{
"errorId": 0,
"softID": 3,
"balance": 0.004
}
```
2. 소프트웨어가 보내는 모든 `createTask` 요청에 최상위 필드 `softID`를 추가해요(`clientKey`, `task`와 같은 레벨이며 대소문자를 구분해요).
```json
{
"clientKey": "THE_USERS_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
},
"softID": 3
}
```
`clientKey`는 사용자 본인의 키예요.
## 수익 배분 규칙
- 내 `softID`가 포함된 작업은 사용자가 실제로 소비한 금액의 \*\*20%\*\*가 개발자 수익으로 적립돼요.
- 해당 사용자가 다른 사람의 추천으로 가입한 경우([추천 보상](https://docs.yescaptcha.com/ko/account/referral.md) 참고), 개발자와 추천인이 \*\*각각 10%\*\*씩 받아요.
- 포인트가 정상적으로 차감된 작업만 수익이 발생해요. 실패하거나 시간 초과로 포인트가 환불된 작업은 해당되지 않아요. 사용자가 인식 오류를 신고해 포인트를 환불받은 작업은 해당 수익도 회수돼요.
- 수익 잔액은 [getSoftID](https://docs.yescaptcha.com/ko/api/get-soft-id.md)의 `balance` 또는 [getBalance](https://docs.yescaptcha.com/ko/api/get-balance.md)의 `softBalance`로 확인할 수 있으며, 단위는 위안이에요.
## 수익 사용
- **잔액으로 전환**: 대시보드에서 수익을 계정 잔액으로 옮기면 1,000 포인트 = ¥1 기준으로 인식에 사용할 수 있어요.
- **출금**: 수익이 **100위안**이 되면 대시보드에서 출금을 신청해요. 심사 후 입금돼요.
- 출금 소득에 대한 개인소득세는 직접 신고해야 해요.
---
# 자주 묻는 질문
> YesCaptcha 자주 묻는 질문. 인식에 실패하면 포인트가 차감되는지, 토큰 유효 시간, 통과율, 사람이 인식하는지 기계가 인식하는지, 계정 차단 여부, 하나의 clientKey를 여러 곳에서 사용하는 방법, 엔드포인트 선택, 확장 프로그램과 API의 차이.
Source: https://docs.yescaptcha.com/ko/help/faq/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/help/faq/
## YesCaptcha가 인식에 실패하면 포인트가 차감되나요?
차감되지 않아요. 인식 실패(`ERROR_CAPTCHA_UNSOLVABLE`)와 시간 초과(`ERROR_TASK_TIMEOUT`)가 발생한 작업은 포인트가 자동으로 환불되고, 매개변수 오류 등 오류 코드를 반환한 요청은 포인트가 차감되지 않아요. 토큰을 받았지만 대상 웹사이트가 받아들이지 않은 경우는 웹사이트의 판정 결과를 알 수 없으므로 성공으로 간주해 과금해요. 이미지 인식 유형은 잘못 클릭했을 때 신고해서 포인트 환불을 요청할 수 있어요. 자세한 내용은 [과금 및 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.
## 인식 한 번에 얼마인가요?
작업 유형별로 정해진 포인트가 차감되고, 1위안 = 1,000포인트이며 유형마다 가격이 달라요. 전체 가격은 [작업 유형 및 가격](https://docs.yescaptcha.com/ko/tasks.md)에서 확인하세요. 기계가 읽을 수 있는 버전은 [/data/task-types.json](https://docs.yescaptcha.com/data/task-types.json)에 있어요.
## 토큰은 얼마 동안 유효한가요?
reCAPTCHA, hCaptcha, Turnstile의 토큰은 모두 일회용이에요. reCAPTCHA 토큰은 약 120초 동안 유효하며, 받은 후 60초 이내에 제출하는 것을 권장해요. 유효 시간은 캡차 제공 업체가 정해요.
## 받은 토큰이 가끔 통과되지 않는 이유는 무엇인가요?
토큰의 통과 여부는 대상 웹사이트가 판정해요. 웹사이트는 점수, IP, 브라우저 환경 등을 종합해 판단하고 기준도 언제든 바뀔 수 있어서, 통과율은 웹사이트마다 달라요. 같은 종류의 다른 작업 유형과 비교해 보거나, 자체 프록시를 사용하는 유형을 쓰고 제출할 때도 같은 프록시를 사용하거나, 이미지 인식으로 바꿔 브라우저에서 직접 클릭해 보세요.
## 인식에 얼마나 걸리나요?
비동기 작업은 보통 몇 초에서 수십 초가 걸리고, 최대 약 110초(일부 유형은 180~220초)이며, 시간 초과되면 포인트가 자동으로 환불돼요. 이미지 인식과 이미지 영숫자 인식은 동기 방식이라 요청 한 번으로 바로 결과를 반환해요.
## 사람이 인식하나요, 기계가 인식하나요?
기계가 인식해요. 머신러닝 모델을 기반으로 해요.
## YesCaptcha를 사용하면 계정이 차단되나요?
YesCaptcha는 인식 결과만 반환하고, 대상 웹사이트의 계정에는 접근하지 않아요. 대상 웹사이트가 어떻게 판정하고 계정을 차단할지는 웹사이트가 직접 결정하므로 해당 웹사이트의 규칙을 지켜 주세요. YesCaptcha는 합법적인 용도로만 사용할 수 있고, 불법적인 용도로 사용하는 것은 금지돼요.
## 하나의 clientKey를 여러 프로그램, 여러 브라우저에서 동시에 사용할 수 있나요?
가능해요. 같은 계정의 요청은 [동시 작업 수 제한](https://docs.yescaptcha.com/ko/api/rate-limits.md)을 합산해서 계산하고, 같은 잔액을 함께 사용해요.
## 글로벌 엔드포인트와 중국 엔드포인트 중 어느 것을 써야 하나요?
서버가 중국 본토에 있다면 `cn.yescaptcha.com`을, 그 외 지역이라면 `api.yescaptcha.com`을 사용하세요. 작업을 생성한 엔드포인트에서 결과를 조회해야 해요. [엔드포인트](https://docs.yescaptcha.com/ko/getting-started/endpoints.md)를 참고하세요.
## 브라우저 확장 프로그램과 API는 어떻게 다른가요?
확장 프로그램도 같은 API를 호출해서 인식해요. 무료로 설치할 수 있고, 사용한 API만큼 포인트가 차감돼요. 코드를 작성하지 않고 브라우저에서 사용하려는 경우에 적합해요. API는 프로그램에서 대량으로 처리하는 경우에 적합해요. [브라우저 확장 프로그램](https://docs.yescaptcha.com/ko/extension.md)을 참고하세요.
## 왜 일시 중지되고 ERROR\_IP\_BLOCKED\_5MIN이 반환되나요?
같은 clientKey에서 1분 안에 오류 요청이 너무 많이 발생해서 몇 분 동안 자동 일시 중지된 거예요. 시간이 지나면 자동으로 복구돼요. 응답의 `blockReason`은 일시 중지를 유발한 오류 코드이니, 이 코드에 맞춰 프로그램을 수정하세요. [동시 작업 수 제한 및 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)를 참고하세요.
## 어떤 웹사이트를 지원하나요?
특정 웹사이트가 아니라 캡차 유형별로 인식을 제공해요. 통과 여부는 대상 웹사이트의 설정에 따라 달라지므로 먼저 소량으로 테스트해 보세요. 일부 웹사이트가 아직 지원되지 않는 경우 `ERROR_DOMAIN_NOT_ALLOWED`가 반환돼요.
---
# 연결 및 네트워크 문제
> YesCaptcha API에 연결되지 않을 때 대처법. Failed to establish a new connection, DNS 확인 실패, 프록시 소프트웨어 간섭, SSL 인증서 오류(Certificate has expired, SSLEOFError)의 점검 절차를 안내해요.
Source: https://docs.yescaptcha.com/ko/help/troubleshooting/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/help/troubleshooting/
API를 호출할 때 연결 오류(예: `Failed to establish a new connection`, `getaddrinfo failed`, 타임아웃, SSL 오류)가 발생한다면 대개 로컬 네트워크, DNS, 프록시 소프트웨어가 원인이에요. 아래 순서대로 점검하세요.
## 1\. 다른 엔드포인트로 시도하기
YesCaptcha에는 `https://api.yescaptcha.com`(글로벌)과 `https://cn.yescaptcha.com`(중국) 두 개의 엔드포인트가 있어요. 중국 본토 서버에서는 중국 엔드포인트를, 그 외 지역에서는 글로벌 엔드포인트를 사용하세요. 엔드포인트를 바꿨다면 결과 조회도 같은 엔드포인트로 해야 해요.
```bash
curl -s https://api.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
curl -s https://cn.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
```
둘 중 하나라도 JSON을 반환하면 네트워크는 정상이고, 다른 엔드포인트로 가는 회선에 문제가 있는 거예요.
## 2\. 프록시 소프트웨어 확인하기
YesCaptcha에 접속하는 데 프록시는 필요하지 않아요. 컴퓨터에서 프록시나 VPN 소프트웨어를 실행 중이라면:
- 먼저 끄고 다시 시도하세요.
- 꼭 켜 두어야 한다면 전역 모드 대신 규칙 기반 분류(PAC 모드)로 바꾸거나, `api.yescaptcha.com`과 `cn.yescaptcha.com`을 직접 연결 목록에 추가하세요.
- 프록시를 켠 상태에서 Python이 `SSLEOFError(8, 'EOF occurred in violation of protocol')`를 반환하는 것도 대부분 프록시 때문이에요. 프록시를 끄거나 이 두 도메인을 직접 연결하면 해결돼요.
## 3\. 네트워크와 DNS 확인하기
```bash
ping api.yescaptcha.com
```
- 호스트를 찾을 수 없다고 나오는 경우: DNS 확인에 실패한 거예요. DNS 캐시를 초기화하거나(Windows: `ipconfig /flushdns`, macOS: `sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder`), 컴퓨터의 DNS를 공용 DNS(예: `223.5.5.5`, `119.29.29.29`, `8.8.8.8`)로 바꾼 뒤 다시 시도하세요.
- ping은 실패하지만 주소는 확인되는 경우: 네트워크에서 ICMP를 차단했을 수 있어요. API에 접속할 수 없다는 뜻은 아니므로 1단계의 curl 결과를 기준으로 판단하세요.
## 4\. SSL 인증서 오류
- `Certificate has expired` 또는 `certificate verify failed`가 나오는 경우: 먼저 컴퓨터의 **시스템 시간**이 정확한지 확인하세요. 그다음 운영체제, Python의 `certifi`, Postman 등의 도구를 최신 버전으로 업데이트해서 최신 루트 인증서를 사용하게 하세요.
- 항상 `https://`를 사용하세요. 인증서 오류를 피하려고 `http://`로 바꾸거나 인증서 검증을 끄지 마세요.
## 5\. 그래도 해결되지 않나요?
[고객 지원](https://docs.yescaptcha.com/ko/help/contact.md)에 다음 내용을 함께 보내 주세요: 전체 오류 메시지, 사용 중인 엔드포인트, 서버가 있는 지역, 1단계 curl의 출력 결과.
---
# 문의하기
> YesCaptcha 고객 지원 문의: WeChat, QQ, WhatsApp, LINE, Telegram @yescaptcha_official, 이메일 yescaptcha@gmail.com, 운영 시간 UTC+8 9:00–21:00.
Source: https://docs.yescaptcha.com/ko/help/contact/ · Last verified: 2026-10-15
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/help/contact/
YesCaptcha 고객 지원 운영 시간은 **UTC+8(베이징 시간) 9:00–21:00**이에요. 답변이 늦어지면 메시지를 남겨 주세요. 최대한 빨리 처리할게요.
- 이메일: [yescaptcha@gmail.com](mailto:yescaptcha@gmail.com)
- Telegram: [@yescaptcha\_official](https://t.me/yescaptcha_official)
QR 코드를 스캔해서 추가하세요:
**WeChat**WeChat에서 QR 코드를 스캔해 친구로 추가하세요. 사용자 그룹에 초대해 드려요
**QQ**QQ에서 QR 코드를 스캔해 친구로 추가하세요
**WhatsApp**WhatsApp 카메라로 QR 코드를 스캔해 추가하세요
**LINE**LINE의 "친구 추가"에서 QR 코드를 스캔하세요
**[Telegram](https://t.me/yescaptcha_official)**@yescaptcha\_official
문의할 때 다음 내용을 함께 보내 주세요:
- 계정 이메일 또는 사용자 ID (`clientKey`는 **절대** 보내지 마세요)
- 관련 `taskId`, 오류 코드, 발생 시각
- 사용한 작업 유형과 엔드포인트(`api.yescaptcha.com` 또는 `cn.yescaptcha.com`)
많은 문제는 [자주 묻는 질문](https://docs.yescaptcha.com/ko/help/faq.md), [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md), [연결 및 네트워크 문제](https://docs.yescaptcha.com/ko/help/troubleshooting.md)에서 답을 찾을 수 있어요.
---
# 서비스 업데이트 기록
> YesCaptcha에서 사용자에게 영향을 주는 변경 사항을 날짜별로 기록해요. 새로 오픈하거나 중단한 작업 유형, 과금 및 포인트 환불 규칙, 동시 작업 수 제한, 문서 이전을 담고 있어요. 2026-10부터 기록해요.
Source: https://docs.yescaptcha.com/ko/changelog/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/changelog/
여기에는 사용자에게 영향을 주는 변경 사항을 날짜별로 기록해요. 작업 유형의 오픈과 중단, 과금 규칙, 제한 규칙 등이 해당돼요. 최신 내용이 맨 위에 있어요.
## 2026-10-19
- **Cloudflare 챌린지 페이지는 더 이상 “비추천”으로 표시하지 않아요**: `CloudFlareTaskS2`, `CloudFlareTaskS3`의 서비스를 다시 구축했어요. 작업 하나에 보통 6~35초가 걸려요. 두 유형의 파라미터, 반환 결과, 효과는 같고 가격도 그대로예요(25포인트, 20포인트). 프록시는 `http://`(계정·비밀번호 포함 가능)와 계정·비밀번호가 없는 `socks5://`만 지원해요. `https://` 프록시, 로컬 주소, 내부망 주소는 작업을 생성할 때 바로 거부돼요(포인트 차감 없음). `userAgent`는 Linux 데스크톱 Chrome 값만 사용하므로, 이후 요청에는 결과의 `user_agent`를 사용하세요. `requiredCookies`를 전달했다면 모두 받아야 성공으로 처리해요. [Cloudflare 챌린지 페이지](https://docs.yescaptcha.com/ko/tasks/cloudflare-challenge.md)를 참고하세요.
## 2026-10-16
- **FunCaptcha 토큰 유형은 당분간 추천하지 않아요**: 비용이 높고 안정적인 방법이 없어요. `FunCaptchaTask`는 작업당 30포인트로 바뀌었어요(기존 15포인트). `FunCaptchaTaskProxyless`는 여전히 인식에 성공하지 못하며, 실패한 작업은 자동으로 포인트 환불돼요. FunCaptcha를 통과해야 한다면 [FunCaptcha 이미지 인식](https://docs.yescaptcha.com/ko/tasks/funcaptcha-classification.md) 또는 브라우저 확장 프로그램을 사용하세요.
## 2026-10-15
- **문서 이전**: 문서를 Confluence에서 이 사이트(docs.yescaptcha.com)로 옮겼어요. 중국어와 영어로 제공하며, 중국어가 기준이에요. AI와 프로그램이 읽기 쉽도록 [llms.txt](https://docs.yescaptcha.com/llms.txt), [OpenAPI](https://docs.yescaptcha.com/openapi.json), 각 페이지의 Markdown 버전을 제공해요.
- **신고 후 포인트 환불은 약 24시간 뒤에 정산해요**: 이미지 인식 유형에서 인식 오류를 신고하면 더 이상 즉시 포인트를 환불하지 않고, 약 24시간 뒤에 일괄 정산해요. 실패율이 같은 기간보다 뚜렷하게 높은 경우에는 같은 기간의 실패율대로 환불해요. [과금 및 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요.
- **동시 작업 수 제한**: 계정별, 작업 유형별로 동시에 처리 중인 작업 수를 집계하기 시작했어요. 한도를 넘으면 `ERROR_THREADS_MAXIMUM`을 반환하고, 포인트는 차감되지 않으며 자동 일시 중지에도 포함되지 않아요. 유형별 한도가 정해지면 [동시 작업 수 제한 및 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)에 공개할게요.
- **공개 작업 유형 추가**: `HCaptchaTask`, `NoCaptchaTask`, `TurnstileTask`, `RecaptchaV2EnterpriseTask`(자체 프록시 사용), `FunCaptchaTaskProxylessM1`, `FunCaptchaTask`, `HCaptchaTaskProxylessM1`을 문서에 추가했어요.
- **FunCaptcha 토큰 유형**: `FunCaptchaTaskProxylessM1`, `FunCaptchaTask`는 사용할 수 있어요. `FunCaptchaTaskProxyless` 경로는 2026-09-10 전후부터 인식에 성공하지 못하고 있으며, 실패한 작업은 자동으로 포인트 환불돼요.
- **서비스 중단**: reCAPTCHA K1 커스텀 핑거프린트 시리즈, `FunCaptchaTaskS1`, `CloudFlareTaskS1`, `TurnstileTaskS2`, `TurnstileTaskProxylessS2`, `bCaptcha2Classification`, `GeneralClassification`의 서비스를 중단했어요.
## 2026-10-15 이전
- **전용 서버** 셀프 임대 서비스는 종료했어요.