# 이미지 영문·숫자 인식

> YesCaptcha로 이미지 속 영문과 숫자를 인식해요. ImageToTextTaskOcrBase와 ImageToTextTaskMuggle은 동기로 결과를 반환하고, ImageToTextTask와 ImageToTextTaskM1은 비동기이며 대소문자, 숫자만, 수식 등의 조건을 지원해요. 모델 맞춤 제작도 가능해요.

Source: https://docs.yescaptcha.com/ko/tasks/image-to-text/ · 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/tasks/image-to-text/

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

- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://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

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

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

**curl**

```bash
# 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

```python
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

```js
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

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

## 반환 결과

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

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

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

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

## 맞춤 모델

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

## 자주 묻는 질문

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

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

### `ERROR_ZERO_CAPTCHA_FILESIZE` 또는 `ERROR_PARSE_IMAGE_FAIL`이 반환돼요

이미지의 Base64가 불완전하거나 `data:` 접두사 또는 줄바꿈이 포함되어 있어요. 인코딩을 확인하세요. [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.

## 관련 예시

-   [빠른 시작](https://docs.yescaptcha.com/ko/getting-started/quickstart.md): `ImageToTextTaskOcrBase`로 첫 요청 보내기
-   [Python 예시](https://docs.yescaptcha.com/ko/samples/python.md)