# Nhận dạng chữ và số trong ảnh

> Dùng YesCaptcha để đọc chữ cái và chữ số trong ảnh: ImageToTextTaskOcrBase và ImageToTextTaskMuggle trả kết quả đồng bộ; ImageToTextTask và ImageToTextTaskM1 bất đồng bộ, hỗ trợ phân biệt hoa/thường, chỉ chữ số, phép tính; có thể định chế mô hình riêng.

Source: https://docs.yescaptcha.com/vi/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/

Chuyển một ảnh captcha ký tự sang Base64 rồi gửi lên, bạn sẽ nhận lại chữ cái và chữ số trong ảnh (`solution.text`). `ImageToTextTaskOcrBase` có giá 2 điểm (≈ $0.30 / 1k) cho mỗi ảnh và trả kết quả đồng bộ: chỉ một yêu cầu `createTask` là có kết quả. Khi cần chỉ định phân biệt hoa/thường, chỉ chữ số, phép tính, v.v., hãy dùng `ImageToTextTask` (bất đồng bộ).

- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)

Nội dung yêu cầu là JSON, xác thực bằng `clientKey`.

## Loại tác vụ và giá

| Loại tác vụ | Giá | Cách trả kết quả | Ghi chú |
| --- | --- | --- | --- |
| `ImageToTextTaskOcrBase` | $0.30 / 1k; 2 điểm/tác vụ · ¥2 / 1k | Đồng bộ |  |
| `ImageToTextTaskMuggle` | $0.30 / 1k; 2 điểm/tác vụ · ¥2 / 1k | Đồng bộ | Không hỗ trợ các tùy chọn case/numeric; dùng project\_name để chọn mô hình tùy chỉnh |
| `ImageToTextTask` | $0.60 / 1k; 4 điểm/tác vụ · ¥4 / 1k | Bất đồng bộ |  |
| `ImageToTextTaskM1` | $2.25 / 1k; 15 điểm/tác vụ · ¥15 / 1k | Bất đồng bộ |  |

Giá bằng đô la Mỹ chỉ là ước tính theo US$1 ≈ ¥6.67; tác vụ được trừ điểm.

| Nhu cầu | Dùng loại nào |
| --- | --- |
| Captcha chữ và số thông thường, rẻ nhất, nhanh nhất | `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` (đồng bộ) |
| Nhận dạng bằng mô hình được định chế riêng cho bạn | `ImageToTextTaskMuggle` kèm `project_name` |
| Cần phân biệt hoa/thường, chỉ có chữ số, tính giá trị phép tính, giới hạn độ dài | `ImageToTextTask`, `ImageToTextTaskM1` (bất đồng bộ) |

Mỗi loại dùng mô hình và đường xử lý khác nhau, nên với cùng một kiểu ảnh kết quả có thể khác nhau. Hãy thử cả các loại rồi chọn loại phù hợp.

## Tham số yêu cầu

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `type` | string | Có | Loại tác vụ; xem "Loại tác vụ và giá" trên trang này |
| `body` | string | Có | Ảnh mã hóa Base64, không có tiền tố `data:image/...;base64,` và không có ký tự xuống dòng |
| `project_name` | string | Không | Tên mô hình tùy chỉnh, chỉ `ImageToTextTaskMuggle` hỗ trợ. Bỏ qua để dùng mô hình chữ và số thông dụng. Liên hệ bộ phận hỗ trợ nếu cần mô hình tùy chỉnh (chỉ ImageToTextTaskMuggle) |
| `phrase` | boolean | Không | true nghĩa là đáp án chứa ít nhất một khoảng trắng (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `case` | boolean | Không | true nghĩa là đáp án phân biệt chữ hoa chữ thường (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `numeric` | integer | Không | 0 không có yêu cầu; 1 chỉ gồm chữ số; 2 không chứa chữ số (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `math` | boolean | Không | true nghĩa là ảnh là một phép tính và đáp án là kết quả của phép tính đó (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `minLength` | integer | Không | Độ dài tối thiểu của đáp án; 0 nghĩa là không giới hạn (chỉ ImageToTextTask, ImageToTextTaskM1) |
| `maxLength` | integer | Không | Độ dài tối đa của đáp án; 0 nghĩa là không giới hạn (chỉ ImageToTextTask, ImageToTextTaskM1) |

`body` là chuỗi Base64 của tệp ảnh, ảnh WebP sẽ được tự động chuyển đổi.

> **Chú ý:** Base64 không được có tiền tố `data:image/...;base64,` và không được có ký tự xuống dòng.

## Ví dụ yêu cầu

POST https://api.yescaptcha.com/createTask

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

Mã đầy đủ (đọc tệp `captcha.png` trong thư mục hiện tại):

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

Tác vụ bất đồng bộ kèm yêu cầu:

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

## Kết quả trả về

Các loại đồng bộ trả kết quả ngay trong `createTask`:

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

Các loại bất đồng bộ (`ImageToTextTask`, `ImageToTextTaskM1`) trả về `taskId` trước, sau đó cứ mỗi 5 giây gọi `getTaskResult` để kiểm tra (polling). Khi hoàn tất, `solution` có định dạng giống như trên.

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `text` | string | Văn bản đã nhận dạng |

## Mô hình định chế riêng

Mô hình chung dùng được cho mọi captcha chữ và số, nhưng độ chính xác thấp hơn một chút so với mô hình được huấn luyện riêng. Nếu ảnh bạn cần nhận dạng luôn có cùng một kiểu, bạn có thể [liên hệ bộ phận hỗ trợ](https://docs.yescaptcha.com/vi/help/contact.md) để định chế mô hình, sau đó chỉ định bằng `ImageToTextTaskMuggle` cùng `project_name`.

## Câu hỏi thường gặp

### Nhận dạng sai có bị trừ điểm không?

Với các loại đồng bộ, hễ trả về kết quả là bị trừ điểm, kể cả khi kết quả sai. Bạn có thể đổi sang loại khác để so sánh hiệu quả, hoặc định chế mô hình riêng.

### Nhận được `ERROR_ZERO_CAPTCHA_FILESIZE` hoặc `ERROR_PARSE_IMAGE_FAIL`?

Base64 của ảnh không đầy đủ, hoặc có tiền tố `data:` hay ký tự xuống dòng. Hãy kiểm tra lại phần mã hóa, xem [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).

## Ví dụ liên quan

-   [Bắt đầu nhanh](https://docs.yescaptcha.com/vi/getting-started/quickstart.md): gửi yêu cầu đầu tiên với `ImageToTextTaskOcrBase`
-   [Ví dụ Python](https://docs.yescaptcha.com/vi/samples/python.md)