API 레퍼런스

createTask 작업 생성

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

createTask는 인식 작업을 생성해요. task.type에 어떤 캡차를 인식할지 지정해요. 비동기 유형은 taskId를 반환하며, 이후 getTaskResult로 결과를 가져와요. 동기 유형은 결과를 바로 반환해요.

POSThttps://api.yescaptcha.com/createTask글로벌 엔드포인트

POSThttps://cn.yescaptcha.com/createTask중국 엔드포인트

요청 파라미터

필드	타입	필수	설명
`clientKey`	string	예	ClientKey. yescaptcha.com 대시보드에서 복사해요
`task`	object	예	작업 객체. 반드시 `type`이 있어야 하고, 나머지 필드는 작업 유형에 따라 채워요. 각 작업 유형 페이지를 참고하세요
`softID`	integer	아니요	개발자 ID. 직접 개발한 소프트웨어를 다른 사람이 사용할 때 이 값을 함께 보내면 수익을 배분받을 수 있어요. 개발자 수익 배분을 참고하세요

요청 예시

이미지 캡차 인식(동기):

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "ImageToTextTaskOcrBase",
    "body": "BASE64_IMAGE"
  }
}

reCAPTCHA v2 토큰 가져오기(비동기):

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}

각 작업 유형의 task 필드는 작업 유형과 가격 아래의 각 페이지에 있어요.

반환 결과

비동기 유형:

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

taskId를 기록해 두고, 5초 후부터 getTaskResult로 조회하세요.

동기 유형:

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

실패:

{
  "errorId": 1,
  "errorCode": "ERROR_TASK_NOT_SUPPORTED",
  "errorDescription": "任务类型不正确或不受支持"
}

검증 순서

서버는 다음 순서로 요청을 검사하고, 처음 발견한 문제에 해당하는 오류 코드를 반환해요. 이 경우 포인트는 차감되지 않아요.

요청 본문이 올바른 JSON인지: ERROR_REQUEST_FORMATS
clientKey가 있는지: ERROR_REQUIRED_FIELDS
clientKey가 존재하는지: ERROR_KEY_DOES_NOT_EXIST
자동 일시 중지 상태가 아닌지: ERROR_IP_BLOCKED_5MIN (동시 작업 수 제한과 자동 일시 중지 참고)
잔액이 10 포인트보다 많은지: ERROR_ZERO_BALANCE
task가 있는지: ERROR_TASK_ABSENT
task.type이 존재하는지: ERROR_TASK_NOT_SUPPORTED
필수 필드가 모두 있는지: ERROR_REQUIRED_FIELDS (errorDescription에 누락된 필드가 적혀 있어요)
이미지 작업의 이미지가 올바른지: ERROR_ZERO_CAPTCHA_FILESIZE, ERROR_IMAGE_TYPE_NOT_SUPPORTED 등

전체 예시

작업을 생성하고 결과를 폴링해요(비동기 유형):

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

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

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