이미지 영문·숫자 인식

문자 캡차 이미지를 Base64로 변환해 보내면 이미지 속 영문과 숫자(solution.text)를 반환해요. ImageToTextTaskOcrBase는 이미지 한 장당 2 포인트 (≈ $0.30 / 1k)이고 동기로 결과를 반환해요. createTask 요청 한 번으로 결과를 받을 수 있어요. 대소문자, 숫자만, 수식 등의 조건을 지정해야 한다면 비동기 방식인 ImageToTextTask를 사용하세요.

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

POSThttps://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

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

전체 코드(현재 디렉터리의 captcha.png를 읽어요):

curl

# 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

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

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "ImageToTextTask",
    "body": "BASE64_IMAGE",
    "case": true,
    "numeric": 0,
    "minLength": 4,
    "maxLength": 6
  }
}

반환 결과

동기 유형은 createTask에서 바로 반환해요.

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

비동기 유형(ImageToTextTask, ImageToTextTaskM1)은 먼저 taskId를 반환해요. 이후 5초마다 getTaskResult로 조회하면 완료 시 같은 형식의 solution을 받을 수 있어요.

필드	유형	설명
text	string	인식된 텍스트예요

맞춤 모델

범용 모델은 모든 영문·숫자 캡차에 사용할 수 있지만, 특정 스타일 전용으로 학습한 모델보다 정확도가 약간 낮아요. 인식할 이미지가 항상 같은 스타일이라면 고객 지원에 문의해 맞춤 모델을 만든 뒤, ImageToTextTaskMuggle에 project_name을 지정해서 사용하세요.

자주 묻는 질문

인식이 틀려도 포인트가 차감되나요?

동기 유형은 결과가 반환되면 틀린 결과여도 포인트가 차감돼요. 다른 유형으로 결과를 비교해 보거나 맞춤 모델을 제작해 보세요.

ERROR_ZERO_CAPTCHA_FILESIZE 또는 ERROR_PARSE_IMAGE_FAIL이 반환돼요

이미지의 Base64가 불완전하거나 data: 접두사 또는 줄바꿈이 포함되어 있어요. 인코딩을 확인하세요. 오류 코드를 참고하세요.

관련 예시

• 빠른 시작: ImageToTextTaskOcrBase로 첫 요청 보내기
• Python 예시