샘플 코드

Node.js

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

실행 환경은 Node.js 18 이상(내장 fetch)이에요. 예제는 ES module(.mjs)이고 서드파티 라이브러리를 설치할 필요가 없어요. 실행하기 전에 환경 변수를 설정하세요:

export YESCAPTCHA_CLIENT_KEY=your_client_key

잔액 조회

포인트가 차감되지 않아요. clientKey가 올바른지 확인할 때 사용하세요:

// 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. node quickstart.mjs captcha.jpg를 실행하세요.

// 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);

재사용 가능한 클라이언트

// 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());
}

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는 오류 코드이고, 의미는 오류 코드에서 확인하세요.