빠른 시작

이 페이지에서는 가장 간단한 작업 유형인 ImageToTextTaskOcrBase(이미지 속 영문과 숫자를 인식해요)로 첫 요청을 보내요. 동기 방식이라 createTask 요청 한 번으로 결과가 반환되고, 건당 2 포인트 (≈ $0.30 / 1k)가 차감돼요. 서드파티 사이트에 의존하지 않아서 계정과 코드가 문제없는지 확인하기 좋아요.

1. 회원가입

   yescaptcha.com에서 회원가입하고 로그인하세요.

2. clientKey 복사

   로그인한 뒤 대시보드(yescaptcha.com/dashboard.html)에서 “내 ClientKey”를 찾아 복사를 눌러요. 값 전체를 빠짐없이 복사하세요.

   주의

   모든 API 요청은 clientKey로 인증해요. 다른 사람이 clientKey를 알면 내 잔액을 사용할 수 있어요. 다른 사람에게 보내거나 공개 코드에 넣지 마세요. 유출됐다면 같은 위치에서 재설정할 수 있어요.

3. 충전

   작업을 만들려면 잔액이 10포인트보다 많아야 해요. 충전 방법과 VIP 보너스는 충전 및 VIP를 참고하세요.

4. clientKey가 작동하는지 확인

   getBalance로 잔액을 조회해요. 포인트는 차감되지 않아요.

   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를 내려받으세요(가지고 있는 캡차 이미지를 써도 돼요). clientKey를 환경 변수에 넣은 뒤 실행하세요.

   export YESCAPTCHA_CLIENT_KEY=your_client_key

   curl

   quickstart.sh

   #!/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

   """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

   // 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. 결과 확인

   성공하면 다음과 같이 반환돼요.

   {
     "errorId": 0,
     "status": "ready",
     "solution": {
       "text": "LMResm"
     },
     "taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
   }

   errorId가 0이면 성공이고, 인식된 텍스트는 solution.text에 있어요. errorId가 1이면 errorCode를 확인하세요. 의미는 오류 코드를 참고하세요.

다음 단계

• reCAPTCHA, hCaptcha처럼 토큰을 반환하는 작업은 비동기예요. createTask가 먼저 taskId를 반환하고, 그다음 5초마다 getTaskResult를 호출해요. 전체 흐름은 요청과 응답을, 예시는 reCAPTCHA v2를 참고하세요.
• 작업 유형 선택: 작업 유형과 가격.
• 프로젝트에 바로 복사해 쓸 수 있는 클라이언트: Python, Node.js.
• 코드 없이 사용하기: 브라우저 확장 프로그램.