# 빠른 시작

> 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).