# Imagem para texto

> Leia letras e números em uma imagem com o YesCaptcha. ImageToTextTaskOcrBase e ImageToTextTaskMuggle retornam de forma síncrona; ImageToTextTask e ImageToTextTaskM1 são assíncronos e aceitam maiúsculas/minúsculas, somente números, expressões matemáticas e limite de tamanho; modelos personalizados disponíveis.

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

Envie a imagem de um captcha de texto em Base64 e receba as letras e os números que ela contém (`solution.text`). `ImageToTextTaskOcrBase` custa 2 pontos (≈ US$0.30 / 1k) por imagem e é síncrono: uma única requisição `createTask` já retorna o resultado. Se precisar de requisitos como diferenciar maiúsculas de minúsculas, somente números ou expressões matemáticas, use o `ImageToTextTask`, que é assíncrono.

- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)

O corpo da requisição é JSON, autenticado com `clientKey`.

## Tipos e preços

| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `ImageToTextTaskOcrBase` | US$0.30 / 1k; 2 pontos/tarefa · ¥2 / 1k | Síncrono |  |
| `ImageToTextTaskMuggle` | US$0.30 / 1k; 2 pontos/tarefa · ¥2 / 1k | Síncrono | Não suporta as opções case/numeric; use project\_name para selecionar um modelo personalizado |
| `ImageToTextTask` | US$0.60 / 1k; 4 pontos/tarefa · ¥4 / 1k | Assíncrono |  |
| `ImageToTextTaskM1` | US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k | Assíncrono |  |

Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.

| Necessidade | Qual usar |
| --- | --- |
| Captchas alfanuméricos comuns, o mais barato e rápido | `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` (síncronos) |
| Reconhecer com um modelo personalizado para você | `ImageToTextTaskMuggle` com `project_name` |
| Diferenciar maiúsculas de minúsculas, somente números, cálculo de expressões, limite de tamanho | `ImageToTextTask`, `ImageToTextTaskM1` (assíncronos) |

Cada tipo usa modelos e rotas diferentes, então o resultado para o mesmo tipo de imagem pode variar. Teste todos e escolha o melhor.

## Parâmetros da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `type` | string | Sim | Tipo de tarefa; veja "Tipos de tarefa e preços" nesta página |
| `body` | string | Sim | Imagem codificada em Base64, sem o prefixo `data:image/...;base64,` e sem quebras de linha |
| `project_name` | string | Não | Nome de um modelo personalizado, suportado apenas por `ImageToTextTaskMuggle`. Omita para usar o modelo alfanumérico geral. Entre em contato com o suporte para obter um modelo personalizado (somente ImageToTextTaskMuggle) |
| `phrase` | boolean | Não | true significa que a resposta contém pelo menos um espaço (somente ImageToTextTask, ImageToTextTaskM1) |
| `case` | boolean | Não | true significa que a resposta diferencia maiúsculas de minúsculas (somente ImageToTextTask, ImageToTextTaskM1) |
| `numeric` | integer | Não | 0 sem exigência; 1 somente dígitos; 2 sem dígitos (somente ImageToTextTask, ImageToTextTaskM1) |
| `math` | boolean | Não | true significa que a imagem é uma expressão matemática e a resposta é o seu resultado (somente ImageToTextTask, ImageToTextTaskM1) |
| `minLength` | integer | Não | Comprimento mínimo da resposta; 0 significa sem limite (somente ImageToTextTask, ImageToTextTaskM1) |
| `maxLength` | integer | Não | Comprimento máximo da resposta; 0 significa sem limite (somente ImageToTextTask, ImageToTextTaskM1) |

`body` é o conteúdo do arquivo de imagem codificado em Base64. Imagens WebP são convertidas automaticamente.

> **Cuidado:** Não inclua o prefixo `data:image/...;base64,` nem quebras de linha no Base64.

## Exemplo de requisição

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

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

Código completo (lê o arquivo `captcha.png` do diretório atual):

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

Tarefa assíncrona com requisitos:

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

## Resultado

Os tipos síncronos retornam o resultado diretamente em `createTask`:

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

Os tipos assíncronos (`ImageToTextTask`, `ImageToTextTaskM1`) retornam primeiro o `taskId`; depois consulte `getTaskResult` a cada 5 segundos. Quando concluído, `solution` tem o mesmo formato.

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `text` | string | O texto reconhecido |

## Modelo personalizado

O modelo geral funciona para qualquer captcha alfanumérico, mas é um pouco menos preciso que um modelo treinado especificamente. Se as imagens que você precisa reconhecer seguem sempre o mesmo estilo, [entre em contato com o suporte](https://docs.yescaptcha.com/pt/help/contact.md) para solicitar um modelo personalizado e depois selecione-o com `ImageToTextTaskMuggle` e `project_name`.

## Perguntas frequentes

### Os pontos são cobrados se o reconhecimento estiver errado?

Nos tipos síncronos, os pontos são cobrados sempre que um resultado é retornado, mesmo que esteja errado. Compare com outro tipo ou solicite um modelo personalizado.

### Recebi `ERROR_ZERO_CAPTCHA_FILESIZE` ou `ERROR_PARSE_IMAGE_FAIL`

O Base64 da imagem está incompleto ou contém o prefixo `data:` ou quebras de linha. Verifique a codificação; veja [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md).

## Exemplos relacionados

-   [Início rápido](https://docs.yescaptcha.com/pt/getting-started/quickstart.md): envie a primeira requisição com `ImageToTextTaskOcrBase`
-   [Exemplos em Python](https://docs.yescaptcha.com/pt/samples/python.md)