# 图片英数字识别

> 用 YesCaptcha 识别图片里的英文和数字：ImageToTextTaskOcrBase、ImageToTextTaskMuggle 同步返回，ImageToTextTask、ImageToTextTaskM1 异步并支持大小写、纯数字、算式等要求；可以定制模型。

Source: https://docs.yescaptcha.com/zh/tasks/image-to-text/ · Last verified: 2026-10-15

把一张字符验证码图片转成 Base64 发过来，返回图片里的英文和数字（`solution.text`）。`ImageToTextTaskOcrBase` 每张 2 点（0.002 元），同步返回：一次 `createTask` 请求就拿到结果。需要指定大小写、纯数字、算式等要求时，用异步的 `ImageToTextTask`。

- POST `https://api.yescaptcha.com/createTask` (国际节点)
- POST `https://cn.yescaptcha.com/createTask` (国内节点)

请求体是 JSON，用 `clientKey` 鉴权。

## 类型与价格

| 任务类型 | 价格 | 返回方式 | 说明 |
| --- | --- | --- | --- |
| `ImageToTextTaskOcrBase` | 2 点（0.002 元） | 同步 |  |
| `ImageToTextTaskMuggle` | 2 点（0.002 元） | 同步 | 不支持 case、numeric 等附加要求；可以用 project\_name 指定定制模型 |
| `ImageToTextTask` | 4 点（0.004 元） | 异步 |  |
| `ImageToTextTaskM1` | 15 点（0.015 元） | 异步 |  |

| 需要 | 用哪个 |
| --- | --- |
| 普通的英数字验证码，最便宜、最快 | `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 编码：不带 `data:image/...;base64,` 前缀，不要有换行。WebP 图片会自动转换。

## 请求示例

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

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

完整代码（读取当前目录下的 `captcha.png`）：

**curl**

```bash
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"]  # 从环境变量读取 clientKey

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（不带 data: 前缀）
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; // 从环境变量读取 clientKey

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（不带 data: 前缀）
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/zh/help/contact/) 定制模型，之后用 `ImageToTextTaskMuggle` 加 `project_name` 指定。

## 常见问题

### 识别错了扣点吗？

同步类型识别出结果就扣点，即使结果不对。可以换一个类型对比效果，或者定制模型。

### 返回 `ERROR_ZERO_CAPTCHA_FILESIZE` 或 `ERROR_PARSE_IMAGE_FAIL`？

图片的 Base64 不完整，或者带了 `data:` 前缀、换行。检查编码，见 [错误码](https://docs.yescaptcha.com/zh/api/errors/)。

## 相关示例

-   [快速开始](https://docs.yescaptcha.com/zh/getting-started/quickstart/)：用 `ImageToTextTaskOcrBase` 发第一个请求
-   [Python 示例](https://docs.yescaptcha.com/zh/samples/python/)