# YesCaptcha Docs (full text)
> O YesCaptcha é uma API de reconhecimento de captcha. Resolva reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF e captchas de imagem com uma única API JSON, com cobrança de pontos por tarefa e reembolso automático de pontos em caso de falha ou timeout.
---
# Resolva captchas com uma única API JSON
> O YesCaptcha é uma API de reconhecimento de captcha. Resolva reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF e captchas de imagem com uma única API JSON, com cobrança de pontos por tarefa e reembolso automático de pontos em caso de falha ou timeout.
Source: https://docs.yescaptcha.com/pt/ · 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/
[API de reconhecimento de captchaStatus](https://status.yescaptcha.com/?lang=en)
Reconhece reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, AWS WAF e captchas de imagem alfanuméricos. A cobrança é por tarefa, em pontos (1,000 pontos = ¥1); tarefas com falha ou timeout têm os pontos reembolsados automaticamente.
[Início rápido](https://docs.yescaptcha.com/pt/getting-started/quickstart.md)[Referência da API](https://docs.yescaptcha.com/pt/api/overview.md)
Versões para IA e programas:[llms.txt](https://docs.yescaptcha.com/pt/llms.txt)[llms-full.txt](https://docs.yescaptcha.com/pt/llms-full.txt)[OpenAPI](https://docs.yescaptcha.com/openapi.json)[Markdown](https://docs.yescaptcha.com/pt/index.md)
O YesCaptcha só pode ser usado para fins lícitos. Qualquer uso ilegal é proibido.
POSTapi.yescaptcha.com/createTask
```
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
1. /createTasktaskId 61138bb6-19fb-11ec-a9c8-0242ac110006
2. /getTaskResultprocessing
3. /getTaskResultprocessing
4. /getTaskResultready
5. gRecaptchaResponse03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU...
1. 1Criar tarefa
2. 2Obter resultado
3. 3Enviar
Exemplo: reCAPTCHA v2, consultando o resultado a cada 5 segundos
A partir de US$0.30 / 1k
Menor preço unitário por tarefa
1,000 pontos = ¥1
Tarefas com falha ou expiradas têm reembolso de pontos
2 endpoints
Endpoint global e endpoint China
9:00–21:00
Suporte humano (UTC+8)
[Início rápidoCadastre-se, obtenha sua clientKey e envie a primeira requisição em 5 minutos](https://docs.yescaptcha.com/pt/getting-started/quickstart.md)[Referência da APIcreateTask, getTaskResult, códigos de erro e limite de tarefas simultâneas](https://docs.yescaptcha.com/pt/api/overview.md)[Tipos de tarefa e preçosPreços, forma de retorno e parâmetros de todos os tipos públicos](https://docs.yescaptcha.com/pt/tasks.md)[Extensão do navegadorResolva captchas nas páginas sem escrever código](https://docs.yescaptcha.com/pt/extension.md)
## Captchas compatíveis
[01reCAPTCHAv2, v3, Enterprise e reconhecimento de imagem do v2A partir de US$0.90 / 1k](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md)[02hCaptchaRetorna um token, ou reconhece as imagens para você clicarA partir de US$1.20 / 1k](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md)[03Cloudflare TurnstileToken de verificação do TurnstileA partir de US$3.75 / 1k](https://docs.yescaptcha.com/pt/tasks/turnstile.md)[04FunCaptchaReconhecimento dos desafios de imagem da Arkose Labs, com suporte a todos os tiposA partir de US$0.45 / 1k](https://docs.yescaptcha.com/pt/tasks/funcaptcha-classification.md)[05AWS WAF / bCaptchaReconhecimento de imagem em grade 3×3A partir de US$1.20 / 1k](https://docs.yescaptcha.com/pt/tasks/aws-bcaptcha-classification.md)[06Imagem para textoCaptchas de caracteres alfanuméricos, retorno síncronoA partir de US$0.30 / 1k](https://docs.yescaptcha.com/pt/tasks/image-to-text.md)
## Três passos
1. 01
**Crie uma tarefa**
Envie o tipo de tarefa e os parâmetros do site com `createTask` e receba um `taskId`. Tipos síncronos, como reconhecimento de imagem e imagem para texto, retornam o resultado diretamente.
2. 02
**Obtenha o resultado**
Chame `getTaskResult` a cada 5 segundos. Quando `status` for `ready`, o resultado estará em `solution`.
3. 03
**Envie ao site de destino**
Preencha o formulário ou a requisição da página com o token obtido. O token é de uso único; use-o em até 60 segundos.
POST /createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
POST /getTaskResult
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
## Páginas mais acessadas
- [**Códigos de erro**O significado de cada código de erro e como tratá-lo](https://docs.yescaptcha.com/pt/api/errors.md)
- [**Limite de tarefas simultâneas e pausa automática**O que acontece ao exceder o limite ou ao ter erros demais](https://docs.yescaptcha.com/pt/api/rate-limits.md)
- [**Cobrança e reembolso de pontos**Pontos, pré-cobrança, reembolso de pontos e reembolso de pontos após reportar](https://docs.yescaptcha.com/pt/getting-started/billing.md)
- [**Fale conosco**WeChat, QQ, Telegram e e-mail, atendimento das 9:00 às 21:00 (UTC+8)](https://docs.yescaptcha.com/pt/help/contact.md)
- [**Painel**Cadastro, obtenção da clientKey e recarga](https://yescaptcha.com/)
---
# Introdução
> O que é o YesCaptcha. Resolva reCAPTCHA, hCaptcha, Turnstile, FunCaptcha e captchas de imagem por API ou extensão do navegador, com cobrança por tarefa e reembolso automático de pontos em caso de falha.
Source: https://docs.yescaptcha.com/pt/getting-started/introduction/ · 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/getting-started/introduction/
O YesCaptcha é um serviço de reconhecimento de captcha. Você envia os dados do captcha para a API do YesCaptcha e recebe de volta um token que pode ser enviado diretamente ao site de destino, ou o resultado do reconhecimento de uma imagem. Há suporte para reCAPTCHA (v2, v3 e Enterprise), hCaptcha, Cloudflare Turnstile, página de desafio do Cloudflare, FunCaptcha, AWS WAF, bCaptcha e captchas de imagem alfanuméricos. A cobrança é feita por tarefa, em pontos (1,000 pontos = ¥1); tarefas que falham ou expiram têm os pontos reembolsados automaticamente.
O YesCaptcha só pode ser usado para fins legais. É proibido qualquer uso ilegal.
## Duas formas de usar
| | API | Extensão do navegador (YesCaptcha Assistant) |
| --- | --- | --- |
| Indicado para | Desenvolvedores que processam captchas em lote no próprio código | Quem não programa e trabalha no navegador |
| Como usar | Chame `createTask` e `getTaskResult` com sua `clientKey` | Instale a extensão e informe sua `clientKey`; os captchas são reconhecidos e clicados automaticamente |
| Suporte | Todos os tipos de tarefa listados neste site | Desafios de imagem do reCAPTCHA v2, hCaptcha, FunCaptcha, AWS WAF e bCaptcha, além de captchas de texto |
| Custo | Pontos cobrados por tipo de tarefa | A extensão é gratuita; você paga pelas chamadas de API que ela faz |
As duas formas usam a mesma conta, a mesma `clientKey` e o mesmo saldo.
## Três tipos de resultado
- **Token**: a maioria dos tipos de tarefa de reCAPTCHA, hCaptcha, Turnstile e FunCaptcha. Retorna uma string que, preenchida no formulário ou na requisição da página, passa pela verificação, sem precisar clicar em imagens. Todos são assíncronos: crie a tarefa e depois consulte o resultado a cada 5 segundos.
- **Resultado de reconhecimento de imagem**: tipos cujo nome termina em `Classification`. Você envia as imagens do captcha e recebe quais imagens ou posições devem ser clicadas; o clique é feito pelo seu programa no navegador. São síncronos: uma única requisição retorna o resultado.
- **Texto ou Cookie**: o reconhecimento de captcha alfanumérico de imagem retorna o texto da imagem; a página de desafio do Cloudflare retorna o Cookie obtido após passar pela verificação.
Todos os tipos e preços: [Tipos de tarefa e preços](https://docs.yescaptcha.com/pt/tasks.md).
## Comece por aqui
[Início rápido](https://docs.yescaptcha.com/pt/getting-started/quickstart.md)Cadastre-se, obtenha sua clientKey e envie a primeira requisição
[Endpoints](https://docs.yescaptcha.com/pt/getting-started/endpoints.md)Endpoint global e endpoint China
[Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md)Pontos, pré-cobrança, reembolso de pontos e reembolso de pontos após reportar
[Extensão do navegador](https://docs.yescaptcha.com/pt/extension.md)Reconheça captchas automaticamente no navegador, sem escrever código
## SDKs da comunidade
SDKs fornecidos por usuários, não oficiais; avalie por conta própria antes de usar: veja [Exemplos de código e SDKs](https://docs.yescaptcha.com/pt/samples.md).
---
# Início rápido
> Faça sua primeira requisição ao YesCaptcha em 5 minutos: cadastre-se, copie a clientKey, faça uma recarga e reconheça um captcha de imagem com curl, Python ou Node.js (ImageToTextTaskOcrBase, resposta síncrona, 2 pontos por imagem).
Source: https://docs.yescaptcha.com/pt/getting-started/quickstart/ · 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/getting-started/quickstart/
Esta página faz a primeira requisição com o tipo de tarefa mais simples, `ImageToTextTaskOcrBase` (reconhece letras e números em uma imagem). Ele é síncrono: uma única requisição `createTask` já retorna o resultado, custa 2 pontos (≈ US$0.30 / 1k) por imagem e não depende de sites de terceiros, o que o torna ideal para confirmar que a conta e o código estão funcionando.
1. **Crie uma conta**
Acesse [yescaptcha.com](https://yescaptcha.com/), cadastre-se e faça login.
2. **Copie a clientKey**
Depois de entrar, no Painel ([yescaptcha.com/dashboard.html](https://yescaptcha.com/dashboard.html)) encontre “Sua ClientKey” e clique em copiar. Copie o valor completo.
> **Cuidado:** Todas as requisições da API são autenticadas com a clientKey; quem tiver acesso a ela pode usar o seu saldo. Não a compartilhe nem a coloque em código público. Se vazar, você pode redefini-la no mesmo lugar.
3. **Faça uma recarga**
O saldo precisa ser maior que 10 pontos para criar tarefas. Formas de pagamento e bônus VIP: [Recarga e VIP](https://docs.yescaptcha.com/pt/account/recharge.md).
4. **Confirme que a clientKey funciona**
`getBalance` consulta o saldo e não cobra pontos:
```bash
curl -s https://api.yescaptcha.com/getBalance \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY"}'
```
Se retornar `{"errorId": 0, "balance": 12345, ...}`, está tudo certo; `balance` é o saldo restante em pontos. Se retornar `ERROR_KEY_DOES_NOT_EXIST`, a chave foi copiada incorretamente.
5. **Reconheça uma imagem**
Baixe a imagem de exemplo [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg) (ou use sua própria imagem de captcha), coloque a clientKey em uma variável de ambiente e execute um dos scripts:
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
**curl**
quickstart.sh
```bash
#!/usr/bin/env bash
# First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image)
# Usage: YESCAPTCHA_CLIENT_KEY=your_client_key bash quickstart.sh captcha.png
set -euo pipefail
IMAGE="${1:-captcha.png}"
BODY=$(base64 < "$IMAGE" | tr -d '\n') # no "data:" prefix, no line breaks
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\", \"task\": {\"type\": \"ImageToTextTaskOcrBase\", \"body\": \"${BODY}\"}}"
echo
```
**Python**
quickstart.py
```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).
Usage:
export YESCAPTCHA_CLIENT_KEY=your_client_key
python quickstart.py captcha.png
"""
import base64
import os
import sys
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
with open(image_path, "rb") as f:
body = base64.b64encode(f.read()).decode() # no "data:" prefix
r = requests.post(
"https://api.yescaptcha.com/createTask",
json={
"clientKey": CLIENT_KEY,
"task": {"type": "ImageToTextTaskOcrBase", "body": body},
},
timeout=30,
)
data = r.json()
if data.get("errorId"):
raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```
**Node.js**
quickstart.mjs
```js
// First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
// Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
import { readFileSync } from 'node:fs';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
const res = await fetch('https://api.yescaptcha.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
console.log('text:', data.solution.text);
```
Execute: `bash quickstart.sh captcha.jpg`, `python quickstart.py captcha.jpg` ou `node quickstart.mjs captcha.jpg`. O Python exige `pip install requests` antes; o Node.js exige a versão 18 ou superior.
6. **Veja o resultado**
Em caso de sucesso, a resposta é:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"text": "LMResm"
},
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
}
```
`errorId` igual a 0 indica sucesso, e o texto reconhecido está em `solution.text`. Se `errorId` for 1, consulte `errorCode`; os significados estão em [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md).
## Próximos passos
- Tarefas que retornam token, como reCAPTCHA e hCaptcha, são **assíncronas**: `createTask` retorna primeiro o `taskId`, e depois você chama `getTaskResult` a cada 5 segundos. O fluxo completo está em [Requisições e respostas](https://docs.yescaptcha.com/pt/api/overview.md); veja um exemplo em [reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md).
- Para escolher o tipo de tarefa: [Tipos de tarefa e preços](https://docs.yescaptcha.com/pt/tasks.md).
- Um cliente que você pode copiar direto para o projeto: [Python](https://docs.yescaptcha.com/pt/samples/python.md), [Node.js](https://docs.yescaptcha.com/pt/samples/nodejs.md).
- Sem escrever código: [extensão do navegador](https://docs.yescaptcha.com/pt/extension.md).
---
# Endpoints
> Os dois endpoints da API do YesCaptcha: global api.yescaptcha.com e China cn.yescaptcha.com. Aceita apenas HTTPS POST com JSON; crie e consulte a tarefa no mesmo endpoint.
Source: https://docs.yescaptcha.com/pt/getting-started/endpoints/ · 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/getting-started/endpoints/
A API do YesCaptcha tem dois endpoints, com métodos e parâmetros idênticos. Escolha conforme a localização do seu servidor:
| Endpoint | Endereço | Indicado para |
| --- | --- | --- |
| Endpoint global | `https://api.yescaptcha.com` | Servidores fora da China continental |
| Endpoint China | `https://cn.yescaptcha.com` | Servidores na China continental |
A URL de um método é o endereço do endpoint mais o nome do método, por exemplo, para criar uma tarefa:
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
## Regras
- Use apenas HTTPS.
- Todos os métodos, exceto [/useragent](https://docs.yescaptcha.com/pt/api/useragent.md), usam `POST` com corpo JSON e o cabeçalho `Content-Type: application/json`. O corpo da requisição não pode ultrapassar 6 MB.
- A autenticação é feita pela `clientKey` no corpo da requisição; nenhum outro cabeçalho é necessário.
> **Nota:** Consulte a tarefa com `getTaskResult` no mesmo endpoint em que a criou. Não misture os dois endpoints.
## Todos os métodos
| Método | Função | Observações |
| --- | --- | --- |
| [createTask](https://docs.yescaptcha.com/pt/api/create-task.md) | Criar uma tarefa | Tipos síncronos retornam o resultado diretamente |
| [getTaskResult](https://docs.yescaptcha.com/pt/api/get-task-result.md) | Consultar o resultado da tarefa | Nos tipos assíncronos, consulte a cada 5 segundos |
| [getBalance](https://docs.yescaptcha.com/pt/api/get-balance.md) | Consultar o saldo | Sem cobrança de pontos |
| [getSoftID](https://docs.yescaptcha.com/pt/api/get-soft-id.md) | Consultar o ID de desenvolvedor | Usado na participação do desenvolvedor |
| [report](https://docs.yescaptcha.com/pt/api/report.md) | Reportar o resultado do reconhecimento | Tipos de reconhecimento de imagem podem solicitar reembolso de pontos após reportar |
| [useragent](https://docs.yescaptcha.com/pt/api/useragent.md) | Obter o User-Agent recomendado | `GET`, usado com hCaptcha |
Se não conseguir se conectar à API, consulte [Problemas de conexão e rede](https://docs.yescaptcha.com/pt/help/troubleshooting.md).
---
# Cobrança e reembolso de pontos
> Como o YesCaptcha cobra pontos: 1,000 pontos = ¥1, com preço fixo por tipo de tarefa; tarefas com falha ou timeout têm os pontos reembolsados automaticamente, requisições que retornam erro não são cobradas; o saldo precisa ser maior que 10 pontos; reportes de falha no reconhecimento de imagem são reembolsados após cerca de 24 horas.
Source: https://docs.yescaptcha.com/pt/getting-started/billing/ · 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/getting-started/billing/
O YesCaptcha cobra pontos por tarefa: cada tipo de tarefa tem um preço fixo, com 1,000 pontos = ¥1. Por exemplo, `NoCaptchaTaskProxyless` custa 15 pontos (≈ US$2.25 / 1k) por tarefa. Os preços de cada tipo estão em [Tipos de tarefa e preços](https://docs.yescaptcha.com/pt/tasks.md).
> **Dica:** Você só paga por tarefas bem-sucedidas: tarefas com falha ou timeout têm os pontos reembolsados automaticamente, e requisições que retornam erro não são cobradas.
## Quando os pontos são cobrados
- **Tipos assíncronos** (a maioria dos tipos que retornam token): os pontos são cobrados quando a tarefa é criada com sucesso. Se depois ocorrer falha no reconhecimento (`ERROR_CAPTCHA_UNSOLVABLE` etc.) ou timeout (`ERROR_TASK_TIMEOUT`, normalmente 110 segundos), os pontos são reembolsados automaticamente.
- **Tipos síncronos** (reconhecimento de imagem, `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle`): os pontos são cobrados quando o resultado é retornado com sucesso.
- Requisições que retornam erro já na criação da tarefa (parâmetros incorretos, saldo insuficiente, limite de tarefas simultâneas excedido etc.) não são cobradas.
## Saldo
- O saldo precisa ser **maior que 10 pontos** para criar tarefas; caso contrário, é retornado `ERROR_ZERO_BALANCE`.
- Consulte o saldo com [getBalance](https://docs.yescaptcha.com/pt/api/get-balance.md), sem cobrança de pontos.
- Sobre recarga e bônus VIP, veja [Recarga e VIP](https://docs.yescaptcha.com/pt/account/recharge.md): quando a recarga acumulada atinge um nível VIP, cada recarga seguinte recebe pontos de bônus proporcionais.
## Tipos com preço que depende do caso
- **Reconhecimento de imagem do reCAPTCHA v2** (`ReCaptchaV2Classification`): imagens pequenas 1x1 e imagens grandes 3x3 e 4x4 têm preços diferentes; veja [Reconhecimento de imagem do reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md).
- **Reconhecimento de imagem do hCaptcha** (`HCaptchaClassification`): não há cobrança de pontos quando nenhum alvo é encontrado (resultado vazio).
## Reembolso de pontos após reportar um erro de reconhecimento
Se o resultado do reconhecimento de imagem clicou no lugar errado, você pode reportá-lo com [report](https://docs.yescaptcha.com/pt/api/report.md); os casos elegíveis têm os pontos reembolsados:
- Apenas 5 tipos de reconhecimento de imagem: `FunCaptchaClassification`, `HCaptchaClassification`, `ReCaptchaV2Classification`, `AwsClassification` e `bCaptchaClassification`.
- O reporte deve ser feito **em até 1 hora** após a criação da tarefa, e cada tarefa é contada apenas uma vez.
- O reembolso não é imediato: a liquidação é feita em lote **após cerca de 24 horas**.
- Na liquidação, a sua taxa de falha é comparada com a de outros usuários no mesmo período e com a mesma pergunta: se a taxa de falha reportada for claramente superior à do período, o reembolso é feito pela taxa de falha do período.
- Reporte sucessos e falhas com honestidade. Reportes que contêm apenas falhas não são usados como referência do período, e a taxa de falha é calculada sobre todas as tarefas que você criou.
- Se tiver dúvidas sobre o resultado da liquidação, [entre em contato com o suporte](https://docs.yescaptcha.com/pt/help/contact.md) para contestar.
Nos tipos que retornam token (reCAPTCHA, hCaptcha, Turnstile etc.), quem decide se o token é aprovado é o site de destino, portanto o reporte não gera reembolso de pontos.
## Quando não há cobrança de pontos
| Situação | Retorno |
| --- | --- |
| Parâmetros incorretos, tipo inexistente, `clientKey` incorreta | O código de erro correspondente |
| Saldo não maior que 10 pontos | `ERROR_ZERO_BALANCE` |
| Limite de tarefas simultâneas excedido | `ERROR_THREADS_MAXIMUM`, veja [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md) |
| Durante a pausa automática | `ERROR_IP_BLOCKED_5MIN` |
| sitekey ou domínio já considerado inválido (durante o período de cache) | O código de erro original, com `cached: true` |
| Falha no reconhecimento ou timeout | Os pontos já cobrados são reembolsados automaticamente |
## Participação e recompensas
- Ao usar o software ou a extensão de outra pessoa, as tarefas podem conter um ID de desenvolvedor, e o desenvolvedor recebe uma participação, sem afetar a cobrança de pontos para você. Se você desenvolve seu próprio software, veja [Participação do desenvolvedor](https://docs.yescaptcha.com/pt/account/developer.md).
- Para indicar outras pessoas, veja [Recompensa por indicação](https://docs.yescaptcha.com/pt/account/referral.md).
---
# Requisições e respostas
> Convenções gerais da API do YesCaptcha: POST com JSON, autenticação por clientKey, formato de resposta com errorId, tarefas síncronas e assíncronas, consulta a cada 5 segundos, timeout de 110 segundos, resultado guardado por cerca de 10 minutos, idioma das mensagens conforme Accept-Language.
Source: https://docs.yescaptcha.com/pt/api/overview/ · 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/api/overview/
Todos os métodos usam `POST` por HTTPS com um corpo JSON (só `/useragent` é `GET`), autenticam com o `clientKey` no corpo da requisição e respondem em JSON: `errorId` igual a 0 indica sucesso; igual a 1 indica falha, acompanhada de `errorCode`. Resolver um captcha tem dois passos: `createTask` cria a tarefa e `getTaskResult` é consultado a cada 5 segundos para obter o resultado. Os tipos síncronos devolvem o resultado diretamente em `createTask`.
## Requisição
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```
- Endpoint: `https://api.yescaptcha.com` (global) ou `https://cn.yescaptcha.com` (China). Veja [Endereços de acesso](https://docs.yescaptcha.com/pt/getting-started/endpoints.md).
- O corpo é JSON, enviado com o cabeçalho `Content-Type: application/json`, com no máximo 6 MB. O JSON não pode conter comentários.
- Toda requisição deve incluir `clientKey`, copiado por inteiro do Painel.
> **Cuidado:** Com o requests do Python, use `json=data` e não `data=data`. O segundo envia um formulário e retorna `ERROR_TASK_ABSENT` ou `ERROR_REQUIRED_FIELDS`.
## Resposta
Sucesso:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
Falha:
```json
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "帐户余额不足"
}
```
| Campo | Descrição |
| --- | --- |
| `errorId` | 0 sucesso, 1 falha |
| `errorCode` | Código de erro em caso de falha; significado e como resolver em [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md) |
| `errorDescription` | Descrição textual do motivo da falha |
| `taskId` | ID da tarefa |
| `status` | `processing` (em processamento) ou `ready` (concluída) |
| `solution` | Resultado do reconhecimento; os campos variam conforme o tipo de tarefa, veja a página de cada tipo |
Para avaliar o resultado, use `errorId` e `errorCode`. Não analise o texto de `errorDescription`, que pode mudar.
## Síncrono e assíncrono
| | Assíncrono | Síncrono |
| --- | --- | --- |
| Quais tipos | Tipos que retornam token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), página de desafio do Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | Reconhecimento de imagem (nomes terminados em `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` retorna | `taskId` | `status: "ready"` e `solution` |
| Como obter o resultado | Chamar `getTaskResult` a cada 5 segundos | Nada mais a fazer |
Para saber a qual grupo cada tipo pertence, veja a coluna “Modo de retorno” em [Tipos de tarefa e preços](https://docs.yescaptcha.com/pt/tasks.md).
## Consulta periódica
1. Depois que `createTask` retornar o `taskId`, aguarde 5 segundos e chame `getTaskResult`.
2. Se retornar `status: "processing"`, aguarde mais 5 segundos e tente de novo; se retornar `status: "ready"`, o resultado está em `solution`.
3. Se retornar `errorId: 1`, pare de consultar essa tarefa e trate o `errorCode`.
- Consultas repetidas do mesmo `taskId` em menos de 5 segundos retornam `processing` imediatamente; consultar com mais frequência não faz o resultado chegar mais rápido.
- Uma tarefa é processada por no máximo 110 segundos, em geral (alguns tipos levam de 180 a 220 segundos). Passado esse tempo, retorna `ERROR_TASK_TIMEOUT` e há reembolso de pontos automático.
- O resultado fica guardado no servidor por cerca de 10 minutos; depois disso o `taskId` expira e a consulta retorna `ERROR_TASKID_INVALID`.
- Consultar o resultado não cobra pontos; a cobrança de pontos ocorre apenas na criação da tarefa.
## Idioma das mensagens
Nas mensagens de pausa automática, de cache de parâmetros inválidos e de parada de consulta, o `errorDescription` segue o cabeçalho `Accept-Language`: se começar com `zh`, vem em chinês; para os demais idiomas, em inglês; sem o cabeçalho, vêm os dois idiomas. As descrições dos outros códigos de erro não são afetadas.
## Próximos passos
- [createTask: criar tarefa](https://docs.yescaptcha.com/pt/api/create-task.md)
- [getTaskResult: obter resultado](https://docs.yescaptcha.com/pt/api/get-task-result.md)
- [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md): erros em excesso causam uma pausa de alguns minutos
---
# createTask — criar tarefa
> POST /createTask cria uma tarefa de captcha. Campos da requisição (clientKey, task, softID), ordem das verificações, tipos assíncronos retornam um taskId e tipos síncronos retornam a solution; o saldo deve ser maior que 10 pontos.
Source: https://docs.yescaptcha.com/pt/api/create-task/ · 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/api/create-task/
`createTask` cria uma tarefa de reconhecimento; `task.type` indica qual captcha resolver. Os tipos assíncronos retornam um `taskId`, que você usa depois em [getTaskResult](https://docs.yescaptcha.com/pt/api/get-task-result.md) para obter o resultado; os tipos síncronos retornam o resultado diretamente.
> **Nota:** Os pontos são cobrados quando a tarefa é criada com sucesso, e o saldo deve ser maior que 10 pontos para criar uma tarefa. Tarefas que falham ou expiram têm os pontos reembolsados automaticamente.
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
## Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `clientKey` | string | Sim | Sua chave de conta, copiada no Painel de [yescaptcha.com](https://yescaptcha.com/) |
| `task` | object | Sim | O objeto da tarefa. Deve conter `type`; os demais campos dependem do tipo de tarefa (veja a página de cada tipo) |
| `softID` | integer | Não | ID de desenvolvedor. Envie o seu quando outras pessoas usarem o seu software, para receber a participação do desenvolvedor; veja [Participação do desenvolvedor](https://docs.yescaptcha.com/pt/account/developer.md) |
## Exemplos de requisição
Reconhecer um captcha de imagem (síncrono):
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
}
}
```
Obter um token do reCAPTCHA v2 (assíncrono):
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
Os campos de `task` de cada tipo estão nas páginas em [Tipos de tarefa e preços](https://docs.yescaptcha.com/pt/tasks.md).
## Resposta
Tipos assíncronos:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
Guarde o `taskId` e comece a chamar `getTaskResult` 5 segundos depois.
Tipos síncronos:
```json
{
"errorId": 0,
"status": "ready",
"taskId": "2376919c-1863-11ec-a012-94e6f7355a0b",
"solution": {
"text": "LMResm"
}
}
```
Falha:
```json
{
"errorId": 1,
"errorCode": "ERROR_TASK_NOT_SUPPORTED",
"errorDescription": "任务类型不正确或不受支持"
}
```
## Ordem das verificações
O servidor verifica a requisição nesta ordem e retorna o primeiro erro encontrado. Nenhum desses casos é cobrado:
1. O corpo é um JSON válido: `ERROR_REQUEST_FORMATS`
2. `clientKey` está presente: `ERROR_REQUIRED_FIELDS`
3. `clientKey` existe: `ERROR_KEY_DOES_NOT_EXIST`
4. A chave não está em pausa automática: `ERROR_IP_BLOCKED_5MIN` (veja [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md))
5. O saldo é maior que 10 pontos: `ERROR_ZERO_BALANCE`
6. `task` está presente: `ERROR_TASK_ABSENT`
7. `task.type` existe: `ERROR_TASK_NOT_SUPPORTED`
8. Todos os campos obrigatórios estão presentes: `ERROR_REQUIRED_FIELDS` (`errorDescription` indica qual campo está faltando)
9. Em tarefas de imagem, a imagem é válida: `ERROR_ZERO_CAPTCHA_FILESIZE`, `ERROR_IMAGE_TYPE_NOT_SUPPORTED` e outros
## Exemplo completo
Criar uma tarefa e consultar periodicamente o resultado (tipo assíncrono):
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
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):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
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 { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "NoCaptchaTaskProxyless",
websiteURL: "https://www.google.com/recaptcha/api2/demo",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```
---
# getTaskResult – obter o resultado
> POST /getTaskResult consulta o resultado de uma tarefa assíncrona. Consulte a cada 5 segundos, continue aguardando em processing, leia solution em ready e pare se houver erro; a tarefa leva no máximo cerca de 110 segundos, o resultado fica guardado por cerca de 10 minutos e a consulta não cobra pontos.
Source: https://docs.yescaptcha.com/pt/api/get-task-result/ · 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/api/get-task-result/
`getTaskResult` consulta o resultado de uma tarefa assíncrona. Depois de criar a tarefa, chame-o a cada 5 segundos: se retornar `processing`, continue aguardando; se retornar `ready`, o resultado está em `solution`; se retornar um erro, pare. A consulta não cobra pontos, não importa quantas vezes você a faça.
- POST `https://api.yescaptcha.com/getTaskResult` (Endpoint global)
- POST `https://cn.yescaptcha.com/getTaskResult` (Endpoint China)
## Parâmetros da requisição
| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `clientKey` | string | Sim | Sua `clientKey`, a mesma usada na criação da tarefa |
| `taskId` | string | Sim | ID da tarefa retornado por [createTask](https://docs.yescaptcha.com/pt/api/create-task.md) |
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
## Resposta
| Situação | Resposta | O que fazer |
| --- | --- | --- |
| Em processamento | `errorId` igual a 0, `status` igual a `processing` | Consulte de novo em 5 segundos |
| Concluída | `errorId` igual a 0, `status` igual a `ready`, resultado em `solution` | Leia `solution`; os campos estão na página de cada tipo de tarefa |
| Falha no reconhecimento | `errorId` igual a 1, `errorCode` igual a `ERROR_CAPTCHA_UNSOLVABLE` | Pontos já reembolsados; você pode criar uma nova tarefa |
| Tempo esgotado | `errorId` igual a 1, `errorCode` igual a `ERROR_TASK_TIMEOUT` | Pontos já reembolsados; você pode criar uma nova tarefa |
| Tarefa inexistente ou expirada | `errorId` igual a 1, `errorCode` igual a `ERROR_TASKID_INVALID` | Pare de consultar este `taskId` |
Exemplo de tarefa concluída (reCAPTCHA v2):
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
## Regras
- **Consulte a cada 5 segundos.** Consultas repetidas do mesmo `taskId` dentro de 5 segundos retornam `processing` imediatamente; consultar com mais frequência não torna o resultado mais rápido.
- **Uma tarefa leva no máximo cerca de 110 segundos** (180 a 220 segundos em alguns tipos). Depois disso, retorna `ERROR_TASK_TIMEOUT` e os pontos são reembolsados automaticamente. Recomendamos definir o limite de espera no seu código em cerca de 3 minutos.
- **O resultado fica guardado por cerca de 10 minutos**; depois disso o `taskId` perde a validade e retorna `ERROR_TASKID_INVALID`. Use o resultado o quanto antes: o próprio token tem validade mais curta (cerca de 120 segundos no reCAPTCHA).
- **Se houver erro, pare.** Depois de `errorId: 1`, continuar consultando o mesmo `taskId` não muda o resultado; a partir da 3ª consulta de uma tarefa já encerrada, o final de `errorDescription` avisa para parar de consultar. `ERROR_TASKID_INVALID` conta nos erros da [pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md) (para o mesmo ID, só a primeira vez).
- Consulte no mesmo endpoint em que a tarefa foi criada.
- `getTaskResult` não é afetado pela pausa automática: tarefas criadas antes da pausa continuam podendo ser consultadas.
---
# getBalance — consultar saldo
> POST /getBalance consulta o saldo da conta (pontos, 1,000 pontos = ¥1) e os saldos de participação do desenvolvedor e de recompensa por indicação. Não cobra pontos e serve para verificar a clientKey.
Source: https://docs.yescaptcha.com/pt/api/get-balance/ · 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/api/get-balance/
`getBalance` retorna os pontos restantes da conta (1,000 pontos = ¥1) e os saldos de participação do desenvolvedor e de recompensa por indicação (em yuan). Não cobra pontos e costuma ser usado para confirmar se a `clientKey` está correta.
- POST `https://api.yescaptcha.com/getBalance` (Endpoint global)
- POST `https://cn.yescaptcha.com/getBalance` (Endpoint China)
## Parâmetros da requisição
| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `clientKey` | string | Sim | Chave da conta |
```json
{
"clientKey": "YOUR_CLIENT_KEY"
}
```
## Resposta
```json
{
"errorId": 0,
"balance": 1071810,
"softBalance": 36.0098,
"inviteBalance": 0,
"inviteBy": 0
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `balance` | integer | Saldo da conta, em pontos (1,000 pontos = ¥1). Precisa ser maior que 10 pontos para criar tarefas |
| `softBalance` | number | Saldo de participação do desenvolvedor, em yuan; veja [Participação do desenvolvedor](https://docs.yescaptcha.com/pt/account/developer.md) |
| `inviteBalance` | number | Saldo de recompensa por indicação, em yuan; veja [Recompensa por indicação](https://docs.yescaptcha.com/pt/account/referral.md) |
| `inviteBy` | integer | ID de usuário de quem indicou você para o cadastro; 0 se não houver |
| `keyQuotaRemaining` | integer | Limite de gastos restante desta `clientKey` no período atual, em pontos. Só existe para uma `clientKey` com limite definido; nesse caso, `balance` é o menor valor entre o saldo da conta e o limite restante. Uma `clientKey` sem limite não tem este campo |
Uma `clientKey` incorreta retorna `ERROR_KEY_DOES_NOT_EXIST`; se a `clientKey` tem uma lista de IPs permitidos e a requisição vem de um IP fora dela, retorna `ERROR_KEY_IP_NOT_ALLOWED`. O `getBalance` é afetado pela [pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md): durante a pausa, retorna `ERROR_IP_BLOCKED_5MIN`.
## Exemplos
**curl**
get-balance.sh
```bash
#!/usr/bin/env bash
# Check the balance. getBalance is free and is a quick way to verify your clientKey
set -euo pipefail
curl -s https://api.yescaptcha.com/getBalance \
-H 'Content-Type: application/json' \
-d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\"}"
echo
```
**Python**
get_balance.py
```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
r = requests.post(
"https://api.yescaptcha.com/getBalance",
json={"clientKey": CLIENT_KEY},
timeout=30,
)
data = r.json()
if data.get("errorId"):
# e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
print("balance (points):", data["balance"])
```
**Node.js**
get-balance.mjs
```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const res = await fetch('https://api.yescaptcha.com/getBalance', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
// e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
console.log('error:', data.errorCode, data.errorDescription);
} else {
console.log('balance (points):', data.balance);
}
```
---
# getSoftID – consultar o ID de desenvolvedor
> POST /getSoftID retorna seu ID de desenvolvedor (softID) e o total acumulado da participação do desenvolvedor; inclua o softID nas requisições createTask feitas quando outras pessoas usam seu software para receber a participação.
Source: https://docs.yescaptcha.com/pt/api/get-soft-id/ · 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/api/get-soft-id/
`getSoftID` retorna seu ID de desenvolvedor (`softID`) e o total acumulado da participação do desenvolvedor (em yuans). Quando outras pessoas usam o software ou a extensão que você desenvolveu, inclua esse ID nas requisições `createTask` delas e você recebe uma participação sobre o que elas gastam. Regras de participação e saque: [Participação do desenvolvedor](https://docs.yescaptcha.com/pt/account/developer.md).
- POST `https://api.yescaptcha.com/getSoftID` (Endpoint global)
- POST `https://cn.yescaptcha.com/getSoftID` (Endpoint China)
## Parâmetros da requisição
| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `clientKey` | string | Sim | Sua própria `clientKey` (a do desenvolvedor) |
```json
{
"clientKey": "YOUR_CLIENT_KEY"
}
```
## Resposta
```json
{
"errorId": 0,
"softID": 3,
"balance": 0.004
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `softID` | integer | Seu ID de desenvolvedor |
| `balance` | number | Saldo acumulado da participação do desenvolvedor, em yuans |
## Como usar
Nas requisições `createTask` feitas pelos usuários do seu software, adicione o campo de nível superior `softID`:
```json
{
"clientKey": "THE_USERS_CLIENT_KEY",
"task": {
"type": "ImageToTextTaskOcrBase",
"body": "BASE64_IMAGE"
},
"softID": 3
}
```
> **Cuidado:** Coloque `softID` no nível superior do corpo da requisição, ao lado de `clientKey` e `task`, com exatamente esta grafia (maiúsculas e minúsculas). Dentro de `task`, ele não tem efeito.
`clientKey` é a chave do próprio usuário, e os pontos são cobrados dele; `softID` é o seu ID de desenvolvedor.
---
# report — reportar resultados
> POST /report informa se os resultados das tarefas estavam corretos; reporte sucessos e falhas de forma honesta. Tarefas de reconhecimento de imagem reportadas como falha até 1 hora após a criação têm o reembolso de pontos liquidado após cerca de 24 horas.
Source: https://docs.yescaptcha.com/pt/api/report/ · 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/api/report/
`report` informa se o resultado de um grupo de tarefas estava correto. **Reporte tanto sucessos quanto falhas.** Quando um tipo de reconhecimento de imagem é reportado como errado, os pontos são reembolsados após cerca de 24 horas se os requisitos forem atendidos; os resultados reportados também são usados para avaliar e melhorar o reconhecimento.
- POST `https://api.yescaptcha.com/report` (Endpoint global)
- POST `https://cn.yescaptcha.com/report` (Endpoint China)
## Parâmetros da requisição
| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | array of string | Sim | Lista de IDs de tarefa; é possível reportar várias de uma vez |
| `isSuccess` | boolean | Sim | `true` se o reconhecimento estava correto, `false` se estava errado |
`clientKey` não é necessário: o ID da tarefa já identifica a tarefa.
```json
{
"id": ["610ff5e0-68eb-11ef-95a6-22e70a0b794d", "65b88c06-68eb-11ef-8e9a-52540023ccb3"],
"isSuccess": false
}
```
## Resposta
```json
{
"errorId": 0,
"status": "success"
}
```
## Reporte de forma honesta
O reporte é usado tanto para liquidar o reembolso de pontos quanto para avaliar e melhorar o reconhecimento, por isso reporte o resultado real:
- Reporte `isSuccess: true` para tarefas reconhecidas corretamente e `false` para as erradas. Reportes que só marcam falhas, ou que marcam tudo como falha independentemente do resultado, não são usados como referência nas estatísticas nem na liquidação.
- A taxa de falha é calculada sobre todas as tarefas que você criou no período, não apenas sobre as que foram reportadas. Reportar mais falhas não gera mais reembolso: se a sua taxa de falha for claramente maior que a do mesmo período, o reembolso de pontos considera apenas a taxa de falha do período.
- Quando uma verificação usa várias imagens (por exemplo, o FunCaptcha pede 5 rodadas) e você não sabe qual delas errou, pode reportar todo o grupo de tarefas como falha; quando a verificação for aprovada, reporte todo o grupo como sucesso da mesma forma.
## Reembolso de pontos após reportar uma falha
- Apenas 5 tipos de reconhecimento de imagem têm reembolso de pontos: `FunCaptchaClassification`, `HCaptchaClassification`, `ReCaptchaV2Classification`, `AwsClassification` e `bCaptchaClassification`.
- Só valem reportes feitos **em até 1 hora** após a criação da tarefa; cada tarefa é reembolsada apenas uma vez.
- O reembolso não é imediato: é liquidado em lote **após cerca de 24 horas**.
- Na liquidação, a taxa de falha reportada é comparada com a de outros usuários no mesmo período e para a mesma pergunta; se for claramente maior que a do período, o reembolso de pontos é feito com base na taxa de falha do período.
- Em caso de dúvida sobre a liquidação, [entre em contato com o suporte](https://docs.yescaptcha.com/pt/help/contact.md) para contestar.
Nos tipos que retornam token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha etc.), quem decide se o token é aprovado é o site de destino, portanto o reporte não gera reembolso de pontos. Resumo das regras de cobrança: [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
---
# useragent
> GET https://api.yescaptcha.com/useragent retorna o User-Agent do navegador recomendado no momento (texto simples). O campo userAgent das tarefas de hCaptcha aceita somente esse valor.
Source: https://docs.yescaptcha.com/pt/api/useragent/ · 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/api/useragent/
`/useragent` retorna o User-Agent do navegador recomendado no momento, em texto simples. Não precisa de `clientKey` e não cobra pontos. O campo `userAgent` das tarefas de [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md) aceita somente esse valor; usá-lo também ao acessar o site de destino ajuda o token a ser aceito.
- GET `https://api.yescaptcha.com/useragent` (Endpoint global)
- GET `https://cn.yescaptcha.com/useragent` (Endpoint China)
## Exemplo
```bash
curl -s https://api.yescaptcha.com/useragent
```
Resposta (valor de 2026-10-15; muda conforme as versões do navegador):
```text
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36
```
> **Nota:** O valor muda com o tempo. Não o deixe fixo no código; basta buscá-lo uma vez a cada inicialização.
- Se o resultado trouxer um `userAgent`, use o valor do resultado ao enviar o token.
---
# Códigos de erro
> Todos os códigos de erro da API do YesCaptcha, com significado e como tratar cada um: formato da requisição, conta e saldo, tarefas simultâneas e pausa, resultado da tarefa, parâmetros do site, imagens, proxy e servidor. Requisições que retornam erro não são cobradas.
Source: https://docs.yescaptcha.com/pt/api/errors/ · 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/api/errors/
Quando ocorre um erro, a API retorna `errorId: 1`; `errorCode` é o código do erro e `errorDescription` é a descrição em texto. Requisições que retornam erro não cobram pontos: se o erro ocorre na criação da tarefa, nada é cobrado; se o reconhecimento falha ou expira depois da criação, há reembolso de pontos automático.
> **Dica:** No código, verifique `errorCode` e não o texto de `errorDescription`, que pode mudar.
```json
{
"errorId": 1,
"errorCode": "ERROR_ZERO_BALANCE",
"errorDescription": "帐户余额不足"
}
```
## Como tratar os erros
1. **Erros de parâmetros** (formato da requisição, clientKey, tipo de tarefa, parâmetros do site, imagens) não mudam ao reenviar; corrija a requisição primeiro.
2. **Falhas de reconhecimento e timeouts** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`) podem ser tentados de novo criando uma nova tarefa.
3. Após um erro, **pare de consultar** esse `taskId`. Não reenvie a mesma requisição em alta frequência.
4. Erros marcados como “conta para a pausa automática” fazem a criação de tarefas ser pausada por 5 minutos quando o mesmo `clientKey` acumula 100 deles em um minuto. Erros marcados como “em cache” não contam, mas, enquanto estiverem em cache, requisições idênticas recebem diretamente o mesmo erro. Veja [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md).
## Todos os códigos de erro
### Formato da requisição
| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Falta um campo obrigatório (como `clientKey`, ou `websiteURL` / `websiteKey` para o tipo de tarefa), ou o corpo da requisição não é JSON | Adicione os campos que faltam, listados na página do tipo de tarefa, e envie JSON com `POST` e `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Conta para a pausa automática) | O corpo da requisição não é um JSON válido | Gere o corpo com uma biblioteca de JSON em vez de concatenar strings; o JSON não pode conter comentários `//` |
| `ERROR_TASK_ABSENT` (Conta para a pausa automática) | O campo `task` está ausente em uma chamada a `createTask` | Coloque os parâmetros da tarefa em um objeto `task`. Com Python requests, use `json=data`, não `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Conta para a pausa automática) | `task.type` está escrito errado ou o tipo foi desativado | Copie o nome do tipo de "Tipos de tarefa e preços"; os nomes diferenciam maiúsculas de minúsculas |
| `ERROR_PAGE_NOT_FOUND` | O caminho solicitado não existe | Verifique a URL do endpoint, por exemplo `https://api.yescaptcha.com/createTask`; os nomes dos métodos diferenciam maiúsculas de minúsculas |
| `ERROR_BAD_REQUEST` | A requisição não pode ser processada, geralmente por causa de um método HTTP incorreto (GET em vez de POST) ou de valores de parâmetros inválidos | Envie JSON com `POST` e verifique os tipos e valores dos parâmetros |
| `ERROR_ILLEGAL_PARAMETERS` | O valor de um parâmetro é inválido. Típico da página de desafio do Cloudflare: `websiteURL` não é uma URL pública `http://` / `https://`, `postData` não é um objeto, ou `requiredCookies` não é um array de strings (retornado por createTask, sem cobrança de pontos); ou o domínio de destino não pôde ser resolvido pelo proxy (retornado por getTaskResult, com reembolso de pontos automático) | Corrija o valor conforme a tabela de parâmetros na página do tipo de tarefa. Se o domínio não pôde ser resolvido, verifique a grafia da URL e se o proxy consegue acessar o site |
### Conta e saldo
| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Conta para a pausa automática) | A `clientKey` não existe: caracteres foram acrescentados ou perdidos ao copiar, ou a chave foi redefinida no Painel | Copie a chave novamente no Painel do yescaptcha.com, sem espaços nem quebras de linha |
| `ERROR_KEY_EXPIRED` (Conta para a pausa automática) | A `clientKey` expirou (retornado por createTask e getBalance, sem cobrança de pontos). Ou ela ficou sem uso por muito tempo e o sistema definiu um prazo de expiração para proteger a conta (um e-mail de aviso é enviado antes de expirar), ou o prazo de validade definido para esta `clientKey` já passou | Faça login no Painel do yescaptcha.com. Se a chave expirou por ficar muito tempo sem uso, gere uma nova `clientKey`; o saldo é transferido automaticamente para a nova. Se foi definido um prazo de validade, altere-o ou use outra `clientKey`. Depois, atualize seu programa com a nova `clientKey` |
| `ERROR_KEY_IP_NOT_ALLOWED` | Esta `clientKey` tem uma lista de IPs permitidos e o IP de origem da requisição não está nela (retornado por createTask e getBalance, sem cobrança de pontos, não conta para a pausa automática) | Faça login no Painel do yescaptcha.com e adicione o IP público da máquina que envia as requisições à lista de IPs permitidos desta `clientKey`, ou use outra `clientKey`. Se várias máquinas chamam a API, adicione o IP público de cada uma (trata-se do IP que chama a API do YesCaptcha, não do proxy nos parâmetros da tarefa) |
| `ERROR_KEY_QUOTA_EXCEEDED` | Esta `clientKey` tem um limite de consumo e o que resta dele no período atual é menor que o custo desta tarefa (retornado por createTask, sem cobrança de pontos, não conta para a pausa automática). O limite considera os pontos efetivamente cobrados; os pontos com reembolso de pontos por tarefas que falharam ou expiraram voltam para o limite | Faça login no Painel do yescaptcha.com e aumente o limite desta `clientKey`, aguarde o próximo período (o limite é zerado todos os dias, toda segunda-feira ou no dia 1 de cada mês, no horário de Pequim; um limite único não é zerado), ou use outra `clientKey`. `getBalance` retorna o limite restante desta `clientKey` (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Saldo insuficiente. O saldo deve ser maior que 10 pontos para criar uma tarefa | Faça uma recarga e tente novamente. Use `getBalance` para consultar o saldo |
### Simultaneidade e pausas
| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Às vezes conta para a pausa automática) | Há tarefas simultâneas demais deste tipo em andamento na conta. `limit` na resposta é o limite de tarefas simultâneas atual. A requisição não foi processada e não houve cobrança de pontos | Aguarde as requisições em andamento retornarem, ou espere 1–2 segundos e tente novamente; limite o número de requisições aguardando resultado ao mesmo tempo |
| `ERROR_IP_BLOCKED_5MIN` | Esta `clientKey` gerou erros demais em pouco tempo e sofreu pausa automática. `retryAfter` é o número de segundos restantes e `blockReason` é o erro que causou a pausa | Corrija a requisição de acordo com `blockReason` e aguarde `retryAfter` segundos; enviar requisições durante a pausa não a prolonga |
| `ERROR_NO_SLOT_AVAILABLE` | O serviço de reconhecimento está temporariamente sobrecarregado. Quando retornado por createTask, nenhum ponto é cobrado; uma tarefa que ficou na fila por tempo demais também retorna esse erro em getTaskResult, e os pontos são reembolsados automaticamente | Aguarde alguns segundos e crie a tarefa novamente |
### Tarefas e resultados
| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Conta para a pausa automática) | O `taskId` não existe, expirou (os resultados são mantidos por cerca de 10 minutos), pertence a outra `clientKey` ou foi criado no outro endpoint | Pare de consultar periodicamente esta tarefa. Consulte usando o mesmo endpoint e a mesma `clientKey` que a criaram |
| `ERROR_TASK_TIMEOUT` | A tarefa não foi concluída dentro do tempo limite (geralmente 110 segundos); o reembolso de pontos foi feito automaticamente | Crie uma nova tarefa; se o timeout persistir, tente outro tipo de tarefa para o mesmo captcha |
| `ERROR_CAPTCHA_UNSOLVABLE` | Não foi possível resolver o captcha desta vez; o reembolso de pontos foi feito. Isso não conta para a pausa automática | Crie uma nova tarefa. Se continuar falhando, verifique `websiteURL`, `websiteKey` e os demais parâmetros, ou tente outro tipo de tarefa para o mesmo captcha |
| `ERROR_SETTLEMENT_FAILED` (Conta para a pausa automática) | O saldo era insuficiente no momento da liquidação, então nenhum resultado foi retornado | Faça uma recarga e crie uma nova tarefa |
| `ERROR_NO_SUCH_CAPCHA_ID` | A tarefa não é mais válida | Pare de consultar periodicamente esta tarefa e crie uma nova |
| `ERROR_RECAPTCHA_TIMEOUT` | O reconhecimento do captcha excedeu o tempo limite; o reembolso de pontos foi feito | Crie uma nova tarefa |
### Parâmetros do site de destino
| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (Em cache, não conta para a pausa) | A `websiteKey` é inválida | Encontre a sitekey na página novamente (veja os guias de como encontrar parâmetros). Requisições idênticas retornam este erro diretamente durante o período de cache, com `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (Em cache, não conta para a pausa) | O domínio de `websiteURL` não corresponde à `websiteKey` | Defina `websiteURL` como o endereço da página que exibe o captcha |
| `ERROR_INVALID_KEY_TYPE` (Em cache, não conta para a pausa) | A sitekey pertence a outro tipo de captcha, por exemplo, uma chave v3 usada com um tipo de tarefa v2 | Primeiro identifique o tipo de captcha (veja "Identificar o tipo de captcha") e escolha o tipo de tarefa correspondente; para o v2 invisível, defina `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (Em cache, não conta para a pausa) | Este site não é suportado | Tente outro tipo de tarefa para o mesmo captcha ou entre em contato com o suporte |
| `ERROR_HIGH_DEMAND_DOMAIN` (Conta para a pausa automática) | Este site não é suportado | Pare de enviar tarefas para este site e entre em contato com o suporte |
| `ERROR_FAILED_LOADING_WIDGET` | Não foi possível carregar o captcha com os parâmetros informados | Verifique `websiteURL` e `websiteKey`; para tipos de tarefa com proxy próprio, verifique se o proxy consegue acessar o site |
### Imagens
| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Conta para a pausa automática) | A imagem está vazia ou é pequena demais | Verifique se os dados em Base64 estão completos e sem o prefixo `data:image/...;base64,` |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Conta para a pausa automática) | A imagem é grande demais | Comprima ou redimensione a imagem; o corpo da requisição inteira deve ficar abaixo de 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Conta para a pausa automática) | O formato da imagem não é suportado, ou a imagem não é uma que este tipo de tarefa consiga processar. Uma única ocorrência pausa a chave por 30 minutos | Use JPG ou PNG e confirme que a imagem corresponde ao tipo de tarefa, por exemplo, o reconhecimento de imagem do reCAPTCHA exige 100x100, 300x300 ou 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Conta para a pausa automática) | O tamanho da imagem não atende aos requisitos deste tipo de tarefa | Redimensione a imagem conforme descrito na página do tipo de tarefa |
| `ERROR_PARSE_IMAGE_FAIL` | Não foi possível decodificar a imagem, geralmente porque o Base64 está truncado ou tem um prefixo | Verifique a codificação Base64 e remova o prefixo `data:` e as quebras de linha |
| `ERROR_UNKNOWN_QUESTION` | A `question` está errada, ou esta pergunta ainda não é suportada | Compare com a lista de perguntas na página do tipo de tarefa. Para perguntas não suportadas, entre em contato com o suporte; novas perguntas geralmente são suportadas em até 3 dias úteis |
| `ERROR_UNKNOW_450x450_QUESTION` | Esta pergunta ainda não é suportada para imagens 4x4 (450x450) | Recarregue o desafio na página para obter outra pergunta |
### Proxies
| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | O proxy recusou a conexão | Verifique o endereço, a porta e o protocolo do proxy, e confirme que ele aceita conexões externas (não pode ser um endereço local como 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | A conexão com o proxy excedeu o tempo limite | Use um proxy mais estável |
| `ERROR_PROXY_READ_TIMEOUT` | A leitura de dados pelo proxy excedeu o tempo limite | Use um proxy mais rápido |
| `ERROR_PROXY_BANNED` | O proxy está indisponível, ou o IP dele está bloqueado pelo site de destino | Use outro proxy |
| `ERROR_PROXY_INCORRECT` | Os parâmetros do proxy estão mal formatados | Verifique o formato de `proxyType`, `proxyAddress`, `proxyPort` (ou da string `proxy`) |
| `ERROR_PROXY_TRANSPARENT` | O proxy é transparente e expõe o IP real | Use um proxy anônimo (de alto anonimato) |
| `ERROR_PROXY_NOT_AUTHORISED` | O usuário ou a senha do proxy estão incorretos | Verifique `proxyLogin` e `proxyPassword` (ou as credenciais na string `proxy`) |
| `ERROR_PROXY_TLS_ERROR` | O handshake TLS com o proxy falhou, geralmente porque `proxyType` está errado (por exemplo, https definido para um proxy http) | Verifique o protocolo do proxy |
| `ERROR_PROXY_CONNECTION_FAILED` | Não foi possível conectar ao servidor proxy | Verifique o endereço e a porta do proxy e confirme que o proxy está funcionando |
### Servidor
| Código de erro | Significado | O que fazer |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | O serviço está temporariamente indisponível (o código é escrito `UNAVALIABLE`) | Tente novamente mais tarde; entre em contato com o suporte se persistir |
| `ERROR_INTERNAL_SERVER_ERROR` | Ocorreu um erro interno no servidor | Tente novamente mais tarde; se persistir, entre em contato com o suporte e informe o `taskId` |
| `ERROR_UNKNOWN` | Um erro não classificado | Tente novamente mais tarde; se persistir, entre em contato com o suporte e informe o `taskId` |
## Campos adicionais
Algumas respostas de erro trazem campos extras:
| Campo | Aparece em | Descrição |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, erros em cache | Quantos segundos ainda faltam para tentar de novo |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Código de erro que causou a pausa |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Tipo, URL e sitekey das requisições que causaram a pausa, para facilitar a localização |
| `cached` | Erros em cache | `true` indica que o resultado veio do cache e nada foi reconhecido |
| `badRequest` | Erros em cache | Parâmetros que atingiram o cache |
| `limit` | `ERROR_THREADS_MAXIMUM` | Seu limite atual de tarefas simultâneas |
As regras de idioma de `errorDescription` estão em [Requisição e resposta](https://docs.yescaptcha.com/pt/api/overview.md).
---
# Limite de tarefas simultâneas e pausa automática
> Limite de tarefas simultâneas do YesCaptcha (ERROR_THREADS_MAXIMUM, sem cobrança de pontos e sem contar para a pausa), pausa automática por excesso de erros (100 em um minuto pausam por 5 minutos, ERROR_IP_BLOCKED_5MIN) e cache de parâmetros inválidos (cached).
Source: https://docs.yescaptcha.com/pt/api/rate-limits/ · 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/api/rate-limits/
Para manter o reconhecimento rápido para todos os usuários, o YesCaptcha tem três regras de proteção: um limite de **tarefas em processamento ao mesmo tempo** por conta (limite de tarefas simultâneas); uma **pausa de alguns minutos** para o `clientKey` que gera erros demais em pouco tempo (pausa automática); e um **cache de parâmetros já considerados inválidos**, que devolve o erro original por um período. Em nenhum desses casos há cobrança de pontos.
## Limite de tarefas simultâneas
Limitamos, por conta e por tipo de tarefa, o número de tarefas em processamento no mesmo instante. O limite é de simultaneidade, não de requisições por minuto.
- A tarefa conta como “em processamento” desde a chamada a `createTask` até o retorno dessa chamada. Os tipos de reconhecimento de imagem devolvem o resultado diretamente em `createTask`, então **simultaneidade ≈ tarefas enviadas por segundo × tempo de cada tarefa**. Por exemplo, com 0.5 segundo por tarefa e 40 tarefas por segundo, a simultaneidade é de cerca de 20.
- As requisições da mesma conta são somadas; cada tipo de tarefa é contado separadamente.
- Requisições acima do limite retornam `ERROR_THREADS_MAXIMUM` imediatamente, e `limit` na resposta indica o seu limite atual. **Não há cobrança de pontos, e elas não contam para a pausa automática.**
- Quando os servidores de reconhecimento ficam sobrecarregados, a conta que mais ocupa tempo de reconhecimento tem o limite desse tipo de tarefa **reduzido pela metade temporariamente, com restauração automática após 10 minutos**. Isso só reduz a velocidade; a conta não é pausada.
- Se precisar de um limite maior, [fale com o suporte](https://docs.yescaptcha.com/pt/help/contact.md). Quando os limites padrão de cada tipo forem definidos, eles serão publicados nesta página e no [Registro de atualizações do serviço](https://docs.yescaptcha.com/pt/changelog.md).
```json
{
"errorId": 1,
"errorCode": "ERROR_THREADS_MAXIMUM",
"errorDescription": "This account already has 30 tasks of this type in progress, which is the limit. Lower the concurrency and wait for pending requests to return before sending more; rejected requests are not charged and do not lead to a block.",
"limit": 30
}
```
(Os números do exemplo são apenas ilustrativos.)
### Boas práticas
1. Limite no programa o “número de requisições aguardando resultado ao mesmo tempo”, por exemplo com um semáforo (Semaphore) ou um pool de threads de tamanho fixo, em vez de controlar apenas quantas são enviadas por segundo.
2. Ao receber `ERROR_THREADS_MAXIMUM`, espere as requisições já enviadas retornarem antes de enviar novas, ou aguarde 1 a 2 segundos e tente de novo. Não repita em loop imediato.
3. Distribua as tarefas em lote de forma uniforme; não envie milhares de tarefas de uma só vez.
Exemplo em Python (asyncio):
```python
import asyncio
import os
import aiohttp
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15 # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)
async def solve(session, task):
async with sem: # at most LIMIT requests in progress at a time
result = {}
for attempt in range(5):
async with session.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
) as resp:
result = await resp.json()
if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
return result
await asyncio.sleep(1 + attempt) # over the limit: wait and retry
return result
```
## Pausa automática
Quando o mesmo `clientKey` gera muitas requisições com erro em pouco tempo, a criação de tarefas é pausada automaticamente:
| Condição | Duração da pausa |
| --- | --- |
| 100 ocorrências dos erros listados abaixo no mesmo minuto do calendário | 5 minutos |
| 1 ocorrência de `ERROR_IMAGE_TYPE_NOT_SUPPORTED` | 30 minutos |
| 1000 acertos no “cache de parâmetros inválidos” no mesmo minuto do calendário | 5 minutos |
Erros que contam para a pausa:
- [`ERROR_REQUEST_FORMATS`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_REQUEST_FORMATS)
- [`ERROR_TASK_ABSENT`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_TASK_ABSENT)
- [`ERROR_TASK_NOT_SUPPORTED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_TASK_NOT_SUPPORTED)
- [`ERROR_KEY_DOES_NOT_EXIST`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_DOES_NOT_EXIST)
- [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_EXPIRED)
- [`ERROR_TASKID_INVALID`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_TASKID_INVALID)
- [`ERROR_SETTLEMENT_FAILED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_SETTLEMENT_FAILED)
- [`ERROR_HIGH_DEMAND_DOMAIN`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_HIGH_DEMAND_DOMAIN)
- [`ERROR_ZERO_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_ZERO_CAPTCHA_FILESIZE)
- [`ERROR_TOO_BIG_CAPTCHA_FILESIZE`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_TOO_BIG_CAPTCHA_FILESIZE)
- [`ERROR_IMAGE_TYPE_NOT_SUPPORTED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_IMAGE_TYPE_NOT_SUPPORTED)
- [`ERROR_ILLEGAL_IMAGE`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_ILLEGAL_IMAGE)
O `ERROR_THREADS_MAXIMUM` retornado pelo excesso de simultaneidade da conta (com o campo `limit`) não conta; o erro de mesmo nome retornado quando o serviço de reconhecimento está ocupado (sem `limit`) conta. Falha de reconhecimento (`ERROR_CAPTCHA_UNSOLVABLE`), saldo insuficiente (`ERROR_ZERO_BALANCE`), campos ausentes (`ERROR_REQUIRED_FIELDS`), pergunta não suportada (`ERROR_UNKNOWN_QUESTION`) e similares não contam.
Durante a pausa:
- Só `createTask` e `getBalance` são afetados e retornam `ERROR_IP_BLOCKED_5MIN`. `getTaskResult` não é afetado: as tarefas criadas antes da pausa continuam podendo ter o resultado consultado normalmente.
- A resposta traz `retryAfter` (quantos segundos faltam), `blockReason` (o código de erro que causou a pausa) e `blockDetail` (tipo, URL e sitekey dessas requisições); use-os para corrigir o programa.
- Continuar enviando requisições não prolonga a pausa. Ela termina automaticamente no prazo, sem precisar falar com o suporte.
- O painel em [yescaptcha.com](https://yescaptcha.com/) mostra o registro de pausas das últimas 24 horas.
```json
{
"errorId": 1,
"errorCode": "ERROR_IP_BLOCKED_5MIN",
"errorDescription": "...",
"retryAfter": 182,
"blockReason": "ERROR_TASK_NOT_SUPPORTED"
}
```
## Cache de parâmetros inválidos
Alguns erros dependem dos parâmetros da requisição, e reenviar os mesmos parâmetros não muda o resultado:
- [`ERROR_RECAPTCHA_INVALID_SITEKEY`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_RECAPTCHA_INVALID_SITEKEY)
- [`ERROR_RECAPTCHA_INVALID_DOMAIN`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_RECAPTCHA_INVALID_DOMAIN)
- [`ERROR_INVALID_KEY_TYPE`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_INVALID_KEY_TYPE)
- [`ERROR_DOMAIN_NOT_ALLOWED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_DOMAIN_NOT_ALLOWED)
Esses erros não contam para a pausa automática; em vez disso, ficam em cache em todo o site: 2 minutos após a primeira verificação e 10 minutos se forem confirmados novamente dentro de 1 hora. Durante o cache, requisições idênticas (mesmo tipo de tarefa e `websiteKey`, ou mesmo domínio do site) retornam diretamente o erro original, sem cobrança de pontos, com `"cached": true`, `retryAfter` (segundos restantes do cache) e `badRequest` (os parâmetros que coincidiram). Corrigir o `websiteKey` ou trocar o tipo de tarefa tem efeito imediato.
## Diferença entre o limite de tarefas simultâneas e a pausa automática
| | Limite de tarefas simultâneas | Pausa automática |
| --- | --- | --- |
| Causa | Tarefas demais em processamento ao mesmo tempo | Requisições com erro demais em pouco tempo |
| Efeito | Só as requisições excedentes são recusadas, com `ERROR_THREADS_MAXIMUM` | Este `clientKey` fica sem poder criar tarefas, com `ERROR_IP_BLOCKED_5MIN` |
| Recuperação | Assim que alguma requisição termina, já dá para enviar outra; a redução pela metade é restaurada após 10 minutos | Termina automaticamente no prazo |
| Cobrança de pontos | Não | Não |
---
# Tipos de tarefa e preços
> Preços (em pontos; 1,000 pontos = ¥1) e modos de retorno de todos os tipos de tarefa públicos do YesCaptcha. Token para reCAPTCHA, hCaptcha e Turnstile, cookies para a página de desafio do Cloudflare e resultado de reconhecimento para texto em imagem e reconhecimento de imagem.
Source: https://docs.yescaptcha.com/pt/tasks/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/
Cada tarefa é cobrada em um número fixo de pontos conforme o tipo (1,000 pontos = ¥1); tarefas que falham ou expiram têm os pontos reembolsados automaticamente. A tabela abaixo lista todos os tipos de tarefa públicos e pode ser pesquisada pelo nome. Versão legível por máquina: [/data/task-types.json](https://docs.yescaptcha.com/data/task-types.json).
| Captcha | Tipo de tarefa | Preço | Modo |
| --- | --- | --- | --- |
| [reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md) | `NoCaptchaTaskProxyless` | US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k | Assíncrono |
| [reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md) | `RecaptchaV2TaskProxyless` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono |
| [reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md) | `NoCaptchaTask` Proxy próprio | US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k | Assíncrono |
| [reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md) | `RecaptchaV2EnterpriseTaskProxyless` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono |
| [reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md) | `RecaptchaV2EnterpriseTask` Proxy próprio | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono |
| [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxyless` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono |
| [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1` | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono |
| [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1S7` | US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k | Assíncrono |
| [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md) | `RecaptchaV3TaskProxylessM1S9` | US$5.25 / 1k; 35 pontos/tarefa · ¥35 / 1k | Assíncrono |
| [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md) | `RecaptchaV3EnterpriseTask` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono |
| [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md) | `RecaptchaV3EnterpriseTaskM1` | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono |
| [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md) | `HCaptchaTaskProxyless` | US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k | Assíncrono |
| [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md) | `HCaptchaTaskProxylessM1` | US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k | Assíncrono |
| [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md) | `HCaptchaTask` Proxy próprio | US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k | Assíncrono |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md) | `TurnstileTaskProxyless` | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md) | `TurnstileTaskProxylessM1` | US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k | Assíncrono |
| [Cloudflare Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md) | `TurnstileTask` Proxy próprio | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono |
| [Página de desafio do Cloudflare](https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge.md) | `CloudFlareTaskS2` Proxy próprio | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono |
| [Página de desafio do Cloudflare](https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge.md) | `CloudFlareTaskS3` Proxy próprio | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono |
| [Imagem para texto](https://docs.yescaptcha.com/pt/tasks/image-to-text.md) | `ImageToTextTaskOcrBase` | US$0.30 / 1k; 2 pontos/tarefa · ¥2 / 1k | Síncrono |
| [Imagem para texto](https://docs.yescaptcha.com/pt/tasks/image-to-text.md) | `ImageToTextTaskMuggle` | US$0.30 / 1k; 2 pontos/tarefa · ¥2 / 1k | Síncrono |
| [Imagem para texto](https://docs.yescaptcha.com/pt/tasks/image-to-text.md) | `ImageToTextTask` | US$0.60 / 1k; 4 pontos/tarefa · ¥4 / 1k | Assíncrono |
| [Imagem para texto](https://docs.yescaptcha.com/pt/tasks/image-to-text.md) | `ImageToTextTaskM1` | US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k | Assíncrono |
| [Reconhecimento de imagem do reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md) | `ReCaptchaV2Classification` | US$0.90 / 1k; 6 pontos/tarefa · ¥6 / 1k | Síncrono |
| [Reconhecimento de imagem do hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification.md) | `HCaptchaClassification` | US$1.20 / 1k; 8 pontos/tarefa · ¥8 / 1k | Síncrono |
| [Reconhecimento de imagem do FunCaptcha](https://docs.yescaptcha.com/pt/tasks/funcaptcha-classification.md) | `FunCaptchaClassification` | US$0.45 / 1k; 3 pontos/tarefa · ¥3 / 1k | Síncrono |
| [Reconhecimento de imagem do AWS WAF / bCaptcha](https://docs.yescaptcha.com/pt/tasks/aws-bcaptcha-classification.md) | `AwsClassification` | US$1.20 / 1k; 8 pontos/tarefa · ¥8 / 1k | Síncrono |
| [Reconhecimento de imagem do AWS WAF / bCaptcha](https://docs.yescaptcha.com/pt/tasks/aws-bcaptcha-classification.md) | `bCaptchaClassification` | US$1.20 / 1k; 8 pontos/tarefa · ¥8 / 1k | Síncrono |
Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67 (2026-10-27). As tarefas são cobradas em pontos: 1,000 pontos = ¥1 ao fazer uma recarga em CNY; recargas em dólares americanos (PayPal, criptomoedas) são convertidas para CNY pela taxa de câmbio vigente no momento do pagamento e, depois, em pontos.
## Qual escolher
| O que você quer fazer | Qual usar | O que retorna |
| --- | --- | --- |
| Obter um token e enviá-lo diretamente, sem clicar em imagens | [reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md), [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md), [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md), [Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md) | Token, assíncrono |
| Passar pela página de verificação “Just a moment…” do Cloudflare | [Página de desafio do Cloudflare](https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge.md) | Cookies, User-Agent e conteúdo da página, assíncrono |
| Clicar nas imagens você mesmo, no navegador | [Reconhecimento de imagem do reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md), [Reconhecimento de imagem do hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification.md), [Reconhecimento de imagem do FunCaptcha](https://docs.yescaptcha.com/pt/tasks/funcaptcha-classification.md), [Reconhecimento de imagem do AWS WAF / bCaptcha](https://docs.yescaptcha.com/pt/tasks/aws-bcaptcha-classification.md) | Quais imagens ou posições clicar, síncrono |
| Reconhecer os caracteres em uma imagem | [Reconhecimento de texto em imagem](https://docs.yescaptcha.com/pt/tasks/image-to-text.md) | Texto, na maioria síncrono |
Não sabe qual captcha é? Veja [Como identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md).
## Padrão dos nomes
- **`Proxyless`**: o captcha é carregado pela nossa rede, sem necessidade de proxy. Os tipos sem `Proxyless` no nome (como `NoCaptchaTask` e `HCaptchaTask`) usam o seu próprio proxy e exigem os campos de proxy; são indicados quando o site de destino verifica o IP de acesso.
- **Sufixos como `M1`**: outra rota para o mesmo captcha, com os mesmos parâmetros e preço diferente. Se uma delas não tiver uma taxa de aprovação satisfatória, troque pela outra; também podem servir de reserva uma para a outra.
- **`Classification`**: reconhecimento de imagem; retorna onde clicar, não um token.
- **`Enterprise`**: reCAPTCHA Enterprise.
## Observações
- O reconhecimento de imagem do reCAPTCHA v2 é cobrado conforme o tamanho da imagem, e o do hCaptcha não cobra pontos quando nenhum alvo é encontrado; veja a página de cada um.
- Os preços valem conforme esta página. A API cobra pontos por tipo de tarefa na criação; consultar o resultado não é cobrado. Regras de cobrança: [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
---
# reCAPTCHA v2
> Obtenha tokens do reCAPTCHA v2 (checkbox, invisível e Enterprise) com o YesCaptcha. Tipos de tarefa e preços, parâmetros da requisição, exemplos em curl/Python/Node.js e o formato do resultado.
Source: https://docs.yescaptcha.com/pt/tasks/recaptcha-v2/ · 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/recaptcha-v2/
Uma tarefa do reCAPTCHA v2 retorna um token (`gRecaptchaResponse`) que você envia ao site de destino para passar na verificação, sem clicar em nenhuma imagem. O tipo mais usado, `NoCaptchaTaskProxyless`, custa 15 pontos (≈ US$2.25 / 1k) por tarefa e é assíncrono: crie a tarefa com `createTask` e depois chame `getTaskResult` a cada 5 segundos para obter o resultado. Tarefas que falham ou expiram têm os pontos reembolsados automaticamente.
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
O corpo da requisição é JSON e a autenticação usa a sua `clientKey` (copie no painel de [yescaptcha.com](https://yescaptcha.com/)). Consulte o resultado no mesmo endpoint em que criou a tarefa.
## Quando usar
- A página mostra a caixa “Não sou um robô” (I’m not a robot): versão com checkbox.
- Não há checkbox e o desafio de imagens só aparece depois de clicar no botão de envio: versão invisível. Adicione `"isInvisible": true`.
- A página carrega `recaptcha/enterprise.js`, ou os endereços das requisições contêm `enterprise`: reCAPTCHA Enterprise. Use um tipo com `Enterprise` no nome.
Se não tiver certeza de qual é o seu caso, veja [Identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md). Se a taxa de aprovação dos tokens não for boa, experimente o [reconhecimento de imagem do reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md): a API indica quais imagens clicar, e você clica nelas no navegador.
## Tipos e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `NoCaptchaTaskProxyless` | US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k | Assíncrono | |
| `RecaptchaV2TaskProxyless` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono | Mesmos parâmetros de NoCaptchaTaskProxyless, mas em outra rota; use qualquer um como alternativa |
| `NoCaptchaTask` | US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k | Assíncrono | Proxy próprio |
| `RecaptchaV2EnterpriseTaskProxyless` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono | |
| `RecaptchaV2EnterpriseTask` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono | Proxy próprio |
Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.
- `NoCaptchaTaskProxyless` e `RecaptchaV2TaskProxyless` têm os mesmos parâmetros, mas usam rotas diferentes. Se um deles não tiver boa taxa de aprovação, experimente o outro.
- Os tipos sem `Proxyless` no nome (`NoCaptchaTask`, `RecaptchaV2EnterpriseTask`) carregam o captcha pelo seu próprio proxy e exigem `proxyType`, `proxyAddress`, `proxyPort` e campos relacionados. Use-os quando o site de destino verifica o IP do visitante.
## Parâmetros da requisição
Campos do objeto `task` em `createTask`:
| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `type` | string | Sim | Tipo de tarefa; veja "Tipos de tarefa e preços" nesta página |
| `websiteURL` | string | Sim | URL completa da página que exibe o captcha. Use o site em que você vê o captcha, não o domínio do fornecedor do captcha |
| `websiteKey` | string | Sim | A chave do site (sitekey), encontrada no código-fonte da página ou nas requisições de rede; normalmente não muda |
| `isInvisible` | boolean | Não | Defina como true para a variante invisível; caso contrário, omita |
| `proxyType` | string | Alguns tipos | Protocolo do proxy: `http`, `https`, `socks4` ou `socks5` (Obrigatório para NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `proxyAddress` | string | Alguns tipos | Endereço IP ou nome de host do proxy. Endereços locais ou privados, como 127.0.0.1 ou 192.168.x.x, não funcionam porque nossos servidores não conseguem acessá-los (Obrigatório para NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `proxyPort` | integer | Alguns tipos | Porta do proxy (Obrigatório para NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `proxyLogin` | string | Não | Nome de usuário do proxy, se o proxy exigir autenticação (somente NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `proxyPassword` | string | Não | Senha do proxy, se o proxy exigir autenticação (somente NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `userAgent` | string | Não | User-Agent do navegador. Se o resultado contiver um `userAgent`, use esse valor ao enviar o token (somente NoCaptchaTask, RecaptchaV2EnterpriseTask) |
| `enterprisePayload` | object | Não | Parâmetros extras da versão Enterprise, como o valor `s` do reCAPTCHA Enterprise: `{"s": "..."}`. Omita se a página não o usar (somente RecaptchaV2EnterpriseTaskProxyless, RecaptchaV2EnterpriseTask) |
Para saber como encontrar `websiteURL` e `websiteKey`, veja [Encontrar os parâmetros do reCAPTCHA](https://docs.yescaptcha.com/pt/guides/find-recaptcha-parameters.md).
## Exemplo de requisição
Usando a página de demonstração oficial do Google:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}
```
Código completo que cria a tarefa, consulta a cada 5 segundos e imprime o token. Antes de executar, coloque a sua clientKey na variável de ambiente `YESCAPTCHA_CLIENT_KEY`:
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
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):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
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 { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "NoCaptchaTaskProxyless",
websiteURL: "https://www.google.com/recaptcha/api2/demo",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```
Para o reCAPTCHA Enterprise, se a página enviar um valor `s` ao reCAPTCHA, coloque-o em `enterprisePayload`:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"enterprisePayload": {
"s": "S_VALUE_FROM_THE_PAGE"
}
}
}
```
Com o seu próprio proxy:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "NoCaptchaTask",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"proxyType": "http",
"proxyAddress": "proxy.example.com",
"proxyPort": 8080,
"proxyLogin": "user",
"proxyPassword": "pass"
}
}
```
## Resultado
`createTask` retorna o ID da tarefa:
```json
{
"errorId": 0,
"taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```
Use-o para chamar `getTaskResult`. Enquanto a tarefa ainda está em processamento, a resposta é `{"errorId": 0, "status": "processing"}`; consulte novamente após 5 segundos. Quando concluída:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `gRecaptchaResponse` | string | O token a ser enviado ao site de destino. Uso único, válido por cerca de 120 segundos; use-o em até 60 segundos |
Uma tarefa é processada por no máximo cerca de 110 segundos; depois disso retorna `ERROR_TASK_TIMEOUT` e os pontos são reembolsados. Em caso de erro, `errorId` é 1; trate-o pelo `errorCode`, conforme [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md). Para saber como enviar o token, veja [Enviar um token do reCAPTCHA](https://docs.yescaptcha.com/pt/guides/submit-recaptcha-token.md).
> **Dica:** O token é de uso único e válido por cerca de 120 segundos; recomendamos enviá-lo em até 60 segundos após recebê-lo.
## Perguntas frequentes
### Por que os tokens do mesmo site às vezes passam e às vezes não?
Quem decide é o site de destino. Ele atribui uma pontuação a cada verificação e define um limite que pode mudar a qualquer momento, por isso a taxa de aprovação varia de site para site e nem todo token passa. Você pode comparar a taxa de aprovação com outro tipo de tarefa do mesmo captcha ou mudar para o [reconhecimento de imagem](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md).
### Por quanto tempo um token é válido?
É de uso único e válido por cerca de 120 segundos; recomendamos enviá-lo em até 60 segundos após recebê-lo. O prazo de validade é definido pelo Google.
### Sou cobrado quando a resolução falha?
Não. Tarefas que retornam `ERROR_CAPTCHA_UNSOLVABLE` ou que expiram têm os pontos reembolsados automaticamente. Veja [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
## Tutoriais relacionados
- [Identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md)
- [Encontrar os parâmetros do reCAPTCHA](https://docs.yescaptcha.com/pt/guides/find-recaptcha-parameters.md)
- [Enviar um token do reCAPTCHA](https://docs.yescaptcha.com/pt/guides/submit-recaptcha-token.md)
- [Clique em imagens do reCAPTCHA v2 com Selenium](https://docs.yescaptcha.com/pt/guides/recaptcha-click-selenium.md)
---
# reCAPTCHA v3
> Obtenha tokens do reCAPTCHA v3 (incluindo a versão Enterprise) com o YesCaptcha: como preencher pageAction, os tipos com pontuação fixa de 0.7 e 0.9, tipos de tarefa e preços, parâmetros, exemplos e o formato do resultado.
Source: https://docs.yescaptcha.com/pt/tasks/recaptcha-v3/ · 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/recaptcha-v3/
O reCAPTCHA v3 não tem caixa de seleção nem imagens: a página pontua os visitantes em segundo plano. O YesCaptcha retorna um token (`gRecaptchaResponse`) que você envia ao site de destino. `RecaptchaV3TaskProxyless` custa 20 pontos (≈ US$3.00 / 1k) por tarefa e é assíncrono: primeiro `createTask`, depois `getTaskResult` a cada 5 segundos. Tarefas com falha ou que expiram têm os pontos reembolsados automaticamente.
- 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`. Consulte o resultado no mesmo endpoint em que a tarefa foi criada.
## Quando usar
- O código-fonte da página contém `grecaptcha.execute(...)`, ou carrega `recaptcha/api.js?render=CHAVE_DO_SITE`: reCAPTCHA v3 padrão.
- Chama `grecaptcha.enterprise.execute(...)` ou carrega `recaptcha/enterprise.js`: reCAPTCHA v3 Enterprise. Use `RecaptchaV3EnterpriseTask` ou `RecaptchaV3EnterpriseTaskM1`.
Como identificar: [Identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md).
## Tipos de tarefa e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `RecaptchaV3TaskProxyless` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono | |
| `RecaptchaV3TaskProxylessM1` | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono | |
| `RecaptchaV3TaskProxylessM1S7` | US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k | Assíncrono | Solicita uma pontuação de 0.7; não precisa de parâmetro extra |
| `RecaptchaV3TaskProxylessM1S9` | US$5.25 / 1k; 35 pontos/tarefa · ¥35 / 1k | Assíncrono | Solicita uma pontuação de 0.9; não precisa de parâmetro extra |
| `RecaptchaV3EnterpriseTask` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono | |
| `RecaptchaV3EnterpriseTaskM1` | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 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.
- `RecaptchaV3TaskProxyless` e `RecaptchaV3TaskProxylessM1` têm os mesmos parâmetros, mas usam rotas diferentes; um pode servir de reserva para o outro.
- Se o site de destino exige uma pontuação alta, use `RecaptchaV3TaskProxylessM1S7` (0.7) ou `RecaptchaV3TaskProxylessM1S9` (0.9); não é necessário nenhum parâmetro adicional.
## 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 |
| `websiteURL` | string | Sim | URL completa da página que exibe o captcha. Use o site em que você vê o captcha, não o domínio do fornecedor do captcha |
| `websiteKey` | string | Sim | A chave do site (sitekey), encontrada no código-fonte da página ou nas requisições de rede; normalmente não muda |
| `pageAction` | string | Não | A action do reCAPTCHA v3; deve corresponder ao valor que a página passa para `grecaptcha.execute`, ou o token pode ser rejeitado |
`pageAction` deve ser igual ao `action` que a página passa em `grecaptcha.execute(CHAVE_DO_SITE, {action: '...'})`; se estiver errado, o site pode rejeitar o token. Como encontrar: [Encontrar os parâmetros do reCAPTCHA](https://docs.yescaptcha.com/pt/guides/find-recaptcha-parameters.md).
## Exemplo de requisição
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
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):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "SITE_KEY_OF_THE_PAGE",
"pageAction": "login",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
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 { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "RecaptchaV3TaskProxyless",
websiteURL: "https://example.com/login",
websiteKey: "SITE_KEY_OF_THE_PAGE",
pageAction: "login",
});
console.log(solution.gRecaptchaResponse);
```
Substitua `websiteURL`, `websiteKey` e `pageAction` pelos valores do site de destino.
## Resultado
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
}
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `gRecaptchaResponse` | string | O token a ser enviado ao site de destino. Uso único, válido por cerca de 120 segundos; use-o em até 60 segundos |
Enquanto a tarefa está em andamento, a resposta é `{"errorId": 0, "status": "processing"}`; consulte novamente após 5 segundos. Trate os erros pelo `errorCode`, conforme [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md). Para saber como enviar o token, veja [Concluir o reCAPTCHA com um token](https://docs.yescaptcha.com/pt/guides/submit-recaptcha-token.md).
## Perguntas frequentes
### Por que alguns tokens não são aceitos pelo site?
No v3, o site de destino decide com base na pontuação, e pode alterar o limite a qualquer momento; por isso, nem todo token passa. Confirme que `pageAction` está correto; se o site exige pontuação alta, experimente `M1S7` ou `M1S9`; você também pode comparar com outros tipos semelhantes.
### Como preencher o v3 Enterprise?
Da mesma forma que o v3 padrão: `websiteURL`, `websiteKey` e `pageAction`, trocando o tipo para `RecaptchaV3EnterpriseTask` ou `RecaptchaV3EnterpriseTaskM1`.
### Por quanto tempo o token é válido?
É de uso único e válido por cerca de 120 segundos. Recomenda-se enviá-lo em até 60 segundos.
## Guias relacionados
- [Identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md)
- [Encontrar os parâmetros do reCAPTCHA](https://docs.yescaptcha.com/pt/guides/find-recaptcha-parameters.md) (inclui como encontrar `pageAction`)
- [Concluir o reCAPTCHA com um token](https://docs.yescaptcha.com/pt/guides/submit-recaptcha-token.md)
---
# hCaptcha
> Obtenha tokens do hCaptcha com a YesCaptcha: HCaptchaTaskProxyless, HCaptchaTaskProxylessM1 e HCaptchaTask com proxy próprio, como preencher userAgent e rqdata e como usar o respKey retornado.
Source: https://docs.yescaptcha.com/pt/tasks/hcaptcha/ · 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/hcaptcha/
Uma tarefa de hCaptcha retorna um token (`gRecaptchaResponse`). Envie-o ao site de destino junto com o `userAgent` retornado (e com o `respKey`, quando houver) para passar na verificação. `HCaptchaTaskProxyless` custa 30 pontos (≈ US$4.50 / 1k) por tarefa e `HCaptchaTask` (com proxy próprio) custa 15 pontos (≈ US$2.25 / 1k) por tarefa; ambas são assíncronas: `createTask` e, depois, `getTaskResult` a cada 5 segundos. Tarefas com falha ou que expiram têm os pontos reembolsados automaticamente.
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
O corpo da requisição é JSON, autenticado com a `clientKey`. Consulte o resultado no mesmo endpoint em que criou a tarefa.
## Quando usar
A página exibe a caixa de seleção “Sou humano” do hCaptcha ou um desafio de imagens do hCaptcha. Para obter um token e enviá-lo diretamente, use os tipos desta página; para clicar nas imagens você mesmo no navegador, use [reconhecimento de imagem do hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification.md).
> **Nota:** A taxa de aprovação do hCaptcha varia muito de site para site; teste primeiro com um lote pequeno.
## Tipos e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `HCaptchaTaskProxyless` | US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k | Assíncrono | |
| `HCaptchaTaskProxylessM1` | US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k | Assíncrono | Mesmos parâmetros de HCaptchaTaskProxyless, mas em outra rota; use qualquer um como alternativa |
| `HCaptchaTask` | US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k | Assíncrono | Proxy próprio |
Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.
- `HCaptchaTaskProxyless` e `HCaptchaTaskProxylessM1` têm os mesmos parâmetros, mas usam rotas diferentes; um pode servir de reserva para o outro.
- `HCaptchaTask` carrega o captcha pelo seu próprio proxy e exige os campos de proxy; use-o quando o site verifica o IP de acesso.
## 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 |
| `websiteURL` | string | Sim | URL completa da página que exibe o captcha. Use o site em que você vê o captcha, não o domínio do fornecedor do captcha |
| `websiteKey` | string | Sim | A chave do site (sitekey) do hCaptcha, normalmente um UUID |
| `userAgent` | string | Não | User-Agent do navegador. Recomendado, mas apenas o valor retornado por `GET https://api.yescaptcha.com/useragent` é aceito; envie o token com o `userAgent` do resultado |
| `isInvisible` | boolean | Não | Defina como true para a variante invisível; caso contrário, omita |
| `rqdata` | string | Não | rqdata do hCaptcha Enterprise; exigido por alguns sites e normalmente encontrado na requisição que carrega o captcha |
| `proxyType` | string | Alguns tipos | Protocolo do proxy: `http`, `https`, `socks4` ou `socks5` (Obrigatório para HCaptchaTask) |
| `proxyAddress` | string | Alguns tipos | Endereço IP ou nome de host do proxy. Endereços locais ou privados, como 127.0.0.1 ou 192.168.x.x, não funcionam porque nossos servidores não conseguem acessá-los (Obrigatório para HCaptchaTask) |
| `proxyPort` | integer | Alguns tipos | Porta do proxy (Obrigatório para HCaptchaTask) |
| `proxyLogin` | string | Não | Nome de usuário do proxy, se o proxy exigir autenticação (somente HCaptchaTask) |
| `proxyPassword` | string | Não | Senha do proxy, se o proxy exigir autenticação (somente HCaptchaTask) |
- `websiteURL` é a página em que o captcha aparece, **não** hcaptcha.com.
- `userAgent` é recomendado, mas só aceita o valor retornado por [/useragent](https://docs.yescaptcha.com/pt/api/useragent.md).
- `rqdata`: exigido por sites que usam o hCaptcha Enterprise (por exemplo, alguns sites sociais e de chat); geralmente é encontrado na requisição que carrega o captcha. Em sites comuns, não envie.
Para saber como encontrar os parâmetros, veja [Encontrar os parâmetros do hCaptcha](https://docs.yescaptcha.com/pt/guides/find-hcaptcha-parameters.md).
## Exemplo de requisição
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
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):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```
**Node.js**
solve.mjs
```js
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 { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "HCaptchaTaskProxyless",
websiteURL: "https://accounts.hcaptcha.com/demo",
websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
});
console.log(solution.gRecaptchaResponse);
```
Com proxy próprio:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaTask",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
"proxyType": "http",
"proxyAddress": "proxy.example.com",
"proxyPort": 8080,
"proxyLogin": "user",
"proxyPassword": "pass"
}
}
```
## Resultado
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
"respKey": "E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `gRecaptchaResponse` | string | O token a ser enviado ao site de destino. Uso único, válido por cerca de 120 segundos; use-o em até 60 segundos |
| `userAgent` | string | O User-Agent usado para obter o token. Use este valor ao enviar o token, mesmo que seja diferente do que você enviou |
| `respKey` | string | Um valor que alguns sites exigem junto com o token; envie-o, se estiver presente |
Para enviar:
1. Coloque o token no campo `h-captcha-response` da página (e em `g-recaptcha-response`, se existir), ou no campo que a API do site exigir.
2. Ao enviar a requisição, use como User-Agent o `userAgent` retornado.
3. Se um `respKey` foi retornado, envie-o também, conforme a exigência do site.
Enquanto a tarefa está em processamento, a resposta é `{"errorId": 0, "status": "processing"}`; consulte novamente após 5 segundos. Em caso de erro, trate-o pelo `errorCode`, conforme [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md).
## Perguntas frequentes
### Por que a taxa de aprovação é instável?
O hCaptcha decide com base nas configurações do site, no IP de acesso e no ambiente do navegador, então a taxa de aprovação varia conforme o site. Confirme que está usando o `userAgent` retornado; em sites sensíveis ao IP, use `HCaptchaTask` com proxy próprio e faça o envio pelo mesmo proxy; também é possível comparar com `HCaptchaTaskProxylessM1`.
### Por quanto tempo o token é válido?
É de uso único e válido por cerca de 120 segundos. Envie-o o quanto antes.
## Tutoriais relacionados
- [Encontrar os parâmetros do hCaptcha](https://docs.yescaptcha.com/pt/guides/find-hcaptcha-parameters.md)
- [Cliques simulados no hCaptcha com reconhecimento de imagem (Selenium)](https://docs.yescaptcha.com/pt/guides/hcaptcha-click-selenium.md)
---
# Cloudflare Turnstile
> Obtenha tokens do Cloudflare Turnstile com o YesCaptcha: TurnstileTaskProxyless, TurnstileTaskProxylessM1 e TurnstileTask com proxy próprio, parâmetros, exemplos e formato do resultado, e a diferença em relação à página de desafio do Cloudflare.
Source: https://docs.yescaptcha.com/pt/tasks/turnstile/ · Last verified: 2026-10-21
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/turnstile/
Uma tarefa do Cloudflare Turnstile retorna um token (`token`) que você envia ao site de destino para passar na verificação. `TurnstileTaskProxyless` custa 25 pontos (≈ US$3.75 / 1k) por tarefa e é assíncrona: primeiro `createTask`, depois `getTaskResult` a cada 5 segundos. Tarefas com falha ou que expiram têm reembolso de pontos automático.
- 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`. Consulte o resultado no mesmo endpoint em que criou a tarefa.
## Quando usar
Um widget de verificação do Cloudflare (“Confirme que você é humano”) está embutido em um formulário da página, e a página carrega um script de `challenges.cloudflare.com/turnstile`.
Se a página inteira é bloqueada pelo Cloudflare e exibe “Just a moment…” ou “Verificando seu navegador”, isso é a página de desafio do Cloudflare, não o Turnstile; use [página de desafio do Cloudflare](https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge.md). A diferença está em [Identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md).
## Tipos de tarefa e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `TurnstileTaskProxyless` | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono | |
| `TurnstileTaskProxylessM1` | US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k | Assíncrono | |
| `TurnstileTask` | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono | Proxy próprio |
Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.
- `TurnstileTaskProxyless` e `TurnstileTaskProxylessM1` têm os mesmos parâmetros e rotas diferentes; um pode servir de reserva para o outro.
- `TurnstileTask` carrega o captcha pelo seu próprio proxy e exige os campos de proxy.
## 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 |
| `websiteURL` | string | Sim | URL completa da página que exibe o captcha. Use o site em que você vê o captcha, não o domínio do fornecedor do captcha |
| `websiteKey` | string | Sim | A chave do site (sitekey) do Turnstile, normalmente começando com 0x |
| `pageAction` | string | Não | A `action` que a página passa ao Turnstile (uma opção de `turnstile.render`, ou `data-action` no elemento do widget), por exemplo `login`. Não é necessária na maioria dos casos; adicione somente quando as tarefas continuarem falhando |
| `data` | string | Não | O `cData` que a página passa ao Turnstile (uma opção de `turnstile.render`, ou `data-cdata` no elemento do widget), por exemplo `c0bd4b36-7419-4e18-83c6-378699f2a9a2`. Não é necessário na maioria dos casos; adicione somente quando as tarefas continuarem falhando |
| `proxyType` | string | Alguns tipos | Protocolo do proxy: `http`, `https`, `socks4` ou `socks5` (Obrigatório para TurnstileTask) |
| `proxyAddress` | string | Alguns tipos | Endereço IP ou nome de host do proxy. Endereços locais ou privados, como 127.0.0.1 ou 192.168.x.x, não funcionam porque nossos servidores não conseguem acessá-los (Obrigatório para TurnstileTask) |
| `proxyPort` | integer | Alguns tipos | Porta do proxy (Obrigatório para TurnstileTask) |
| `proxyLogin` | string | Não | Nome de usuário do proxy, se o proxy exigir autenticação (somente TurnstileTask) |
| `proxyPassword` | string | Não | Senha do proxy, se o proxy exigir autenticação (somente TurnstileTask) |
| `userAgent` | string | Não | User-Agent do navegador. Se o resultado contiver um `userAgent`, use esse valor ao enviar o token (somente TurnstileTask) |
`websiteKey` geralmente começa com `0x`. Como encontrá-lo: [Encontrar os parâmetros do Turnstile](https://docs.yescaptcha.com/pt/guides/find-turnstile-parameters.md).
### Se as tarefas continuam falhando: pageAction e data
Na maioria dos casos, basta enviar `websiteURL` e `websiteKey`; esses dois parâmetros não são necessários. Se você tem certeza de que `websiteURL` e `websiteKey` estão corretos e a tarefa ainda falha, verifique se a página passa `action` e `cData` ao Turnstile (opções de `turnstile.render`, ou `data-action` e `data-cdata` no elemento do widget). Se passar, envie-os exatamente como estão:
- `pageAction`: o `action` da página, por exemplo `login`
- `data`: o `cData` da página, por exemplo `c0bd4b36-7419-4e18-83c6-378699f2a9a2`
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY",
"pageAction": "login",
"data": "c0bd4b36-7419-4e18-83c6-378699f2a9a2"
}
}
```
## Exemplo de requisição
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY"
}
}
```
**curl**
```bash
curl -s https://api.yescaptcha.com/createTask \
-H 'Content-Type: application/json' \
-d '{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY"
}
}'
# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
-H 'Content-Type: application/json' \
-d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```
**Python**
solve.py
```python
import os
import time
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):
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # Poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(task_id)
solution = solve({
"type": "TurnstileTaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAA_SITE_KEY",
})
print(solution["token"])
```
**Node.js**
solve.mjs
```js
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 { taskId } = await call('createTask', { task });
for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
await new Promise((r) => setTimeout(r, 5000));
const result = await call('getTaskResult', { taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`timeout: ${taskId}`);
}
const solution = await solve({
type: "TurnstileTaskProxyless",
websiteURL: "https://example.com/login",
websiteKey: "0x4AAAAAAA_SITE_KEY",
});
console.log(solution.token);
```
Substitua `websiteURL` e `websiteKey` pelos valores do site de destino.
## Resultado
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.ufq5RgSVZd11DPSX1brdrxnEs28KcVlKj2ORchqxSy2q9yAW6ciq3hriXDF4x...",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
}
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `token` | string | O token a ser enviado ao site de destino. Uso único; envie-o o quanto antes |
| `userAgent` | string | O User-Agent usado para obter o token. Use este valor ao enviar o token, mesmo que seja diferente do que você enviou |
Preencha o campo `cf-turnstile-response` da página (ou o campo exigido pela API do site de destino) com o `token` e envie, usando como User-Agent da requisição o `userAgent` retornado.
Enquanto a tarefa está em andamento, a resposta é `{"errorId": 0, "status": "processing"}`; consulte novamente após 5 segundos. Em caso de erro, trate conforme o `errorCode`; veja [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md).
## Perguntas frequentes
### Por quanto tempo um token é válido?
É de uso único. Envie-o o quanto antes após recebê-lo (o token do Turnstile geralmente expira em alguns minutos, conforme definido pelo Cloudflare).
### O site continua rejeitando o envio
Confirme que `websiteURL` é a página em que o widget aparece, que `websiteKey` está correto e que o envio usa o `userAgent` retornado. Se a página passa `action` e `cData`, envie-os como `pageAction` e `data`; veja [Se as tarefas continuam falhando](#se-as-tarefas-continuam-falhando-pageaction-e-data). Se o site também verifica o IP, use `TurnstileTask` e faça o envio pelo mesmo proxy.
## Guias relacionados
- [Identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md)
- [Encontrar os parâmetros do Turnstile](https://docs.yescaptcha.com/pt/guides/find-turnstile-parameters.md)
---
# Página de desafio do Cloudflare
> Use o YesCaptcha para passar pela página de verificação "Just a moment..." do Cloudflare e obter cookies como cf_clearance, o User-Agent e o conteúdo da página. Parâmetros de CloudFlareTaskS2 e CloudFlareTaskS3, requisitos de proxy, resultado, como usá-lo e erros comuns.
Source: https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/cloudflare-challenge/
A página de desafio do Cloudflare é a página de verificação que bloqueia o site inteiro e exibe “Just a moment…” ou “Verificando seu navegador”. O YesCaptcha abre a página pelo proxy que você informa, passa pela verificação e retorna cookies como `cf_clearance`, o User-Agent usado, os cabeçalhos da requisição e da resposta e o HTML da página após a verificação. `CloudFlareTaskS2` custa 25 pontos (≈ US$3.75 / 1k) por tarefa e `CloudFlareTaskS3` custa 20 pontos (≈ US$3.00 / 1k) por tarefa; os dois tipos têm os mesmos parâmetros, resultado e eficácia, e diferem apenas no preço. As tarefas são assíncronas e normalmente levam de 6 a 35 segundos, com grande variação entre sites. Tarefas que falham ou expiram têm reembolso de pontos automático.
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
## Quando usar
- O código-fonte da página contém `__cf_chl_rt_tk` ou `cdn-cgi/challenge-platform` e o título é `Just a moment...`: trata-se da página de desafio. Páginas de verificação que pedem para marcar a caixa “Confirmar que você é humano” também são resolvidas aqui.
- Se há apenas um widget do Cloudflare incorporado em um formulário, é o [Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md), e não esta página.
- Se, ao usar uma biblioteca como requests, você recebe 403 com “Just a moment…” mas o navegador abre a página normalmente, provavelmente o bloqueio é só pela impressão digital TLS. Use uma biblioteca que imite a impressão digital TLS de um navegador (como curl\_cffi); não é necessário resolver o desafio.
## Tipos e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `CloudFlareTaskS2` | US$3.75 / 1k; 25 pontos/tarefa · ¥25 / 1k | Assíncrono | Proxy próprio |
| `CloudFlareTaskS3` | US$3.00 / 1k; 20 pontos/tarefa · ¥20 / 1k | Assíncrono | Proxy próprio |
Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.
## 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 |
| `websiteURL` | string | Sim | URL completa da página protegida pelo desafio. Deve ser uma URL pública `http://` ou `https://`; endereços IP privados e nomes de host locais ou internos, como `localhost`, são rejeitados |
| `proxy` | string | Sim | Proxy em uma única string: `http://user:pass@proxy.example.com:8080` (proxy HTTP, credenciais opcionais) ou `socks5://proxy.example.com:1080` (sem credenciais). Proxies `https://` e SOCKS5 com credenciais não são suportados, e endereços locais ou privados são rejeitados. Todas as requisições à página de destino passam por esse proxy |
| `userAgent` | string | Não | Normalmente deixe de fora. Apenas um User-Agent do Chrome para desktop no Linux é utilizado; qualquer outro (Windows, macOS, celular, outros navegadores) é ignorado. Use sempre o `user_agent` do resultado nas requisições seguintes |
| `waitLoad` | boolean | Não | O padrão é false. Se true, depois de passar na verificação a tarefa espera a atividade de rede da página se estabilizar antes de retornar, de modo que `content` inclua mais conteúdo carregado dinamicamente; leva alguns segundos a mais |
| `requiredCookies` | array | Não | Nomes dos cookies que devem ser obtidos, como um array de strings, por exemplo `["cf_clearance"]`. Se definido, a tarefa só tem sucesso quando todos forem obtidos; caso contrário, retorna `ERROR_CAPTCHA_UNSOLVABLE` e há reembolso de pontos. Se omitido, a tarefa ainda tenta obter `cf_clearance`, mas tem sucesso (com cobrança de pontos) com quaisquer outros cookies obtidos; portanto, informe-o explicitamente se precisar de `cf_clearance` |
| `blockImage` | boolean | Não | Se true, as imagens da página de destino não são carregadas (exceto as que a própria verificação do Cloudflare precisa), economizando tráfego do proxy |
| `postData` | object | Não | Se definido, é enviado a `websiteURL` como um POST de formulário HTML comum (`application/x-www-form-urlencoded`): cada chave é um campo do formulário e os valores são enviados como strings, por exemplo `{"name": "hi"}`. Deve ser um objeto |
### Requisitos de proxy
`proxy` é obrigatório, e todas as requisições para abrir a página de destino passam por ele. O `cf_clearance` está vinculado ao IP de saída, portanto use o mesmo proxy ao acessar o site depois.
| Formato | Suporte |
| --- | --- |
| `http://user:pass@proxy.example.com:8080` | Sim: proxy HTTP com usuário e senha |
| `http://proxy.example.com:8080` | Sim: proxy HTTP sem usuário e senha |
| `socks5://proxy.example.com:1080` | Sim: proxy SOCKS5 sem usuário e senha; `socks5h://` é tratado como `socks5://` |
| `socks5://user:pass@proxy.example.com:1080` | Não, retorna `ERROR_PROXY_INCORRECT`; se precisar de usuário e senha, use um proxy HTTP |
| `https://proxy.example.com:443` ou outros protocolos, ou sem porta | Não, retorna `ERROR_PROXY_INCORRECT` |
| Endereços locais, de rede interna ou reservados, como `127.0.0.1`, `192.168.x.x`, `10.x.x.x`, ou domínios que resolvem para eles | Recusado, retorna `ERROR_PROXY_BANNED` |
> **Verificado na criação da tarefa:** Se a URL ou o proxy forem inválidos, `createTask` retorna o erro imediatamente, sem cobrança de pontos. Se um mesmo proxy falhar ao conectar várias vezes em pouco tempo, por um período as tarefas criadas com ele também retornam `ERROR_PROXY_BANNED`; troque de proxy ou tente novamente mais tarde.
### User-Agent
Em geral, não informe `userAgent`. A verificação é feita com o Chrome desktop para Linux, então só é usado um User-Agent do Chrome desktop para Linux; qualquer outro (Windows, macOS, celular ou outros navegadores) é ignorado: em nossos testes, a verificação do Cloudflare não passa quando o User-Agent não corresponde ao ambiente real do navegador. Nas requisições seguintes, use sempre o `user_agent` do resultado.
## Exemplo de requisição
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "CloudFlareTaskS3",
"websiteURL": "https://example.com/",
"proxy": "http://user:pass@proxy.example.com:8080",
"requiredCookies": ["cf_clearance"]
}
}
```
- Para usar `CloudFlareTaskS2`, altere apenas `type`; o restante permanece igual.
- Com `requiredCookies` definido como `["cf_clearance"]`, a tarefa falha e há reembolso de pontos se o `cf_clearance` não for obtido. Sem esse parâmetro, se a tarefa obtiver outros cookies mas não o `cf_clearance`, ela ainda é considerada bem-sucedida e os pontos são cobrados.
- Para enviar um formulário, adicione `postData`, por exemplo `{"name": "hi"}`; ele é enviado a `websiteURL` como um formulário POST.
Depois de criar a tarefa, chame `getTaskResult` a cada 5 segundos, como em qualquer outra tarefa assíncrona; veja [getTaskResult](https://docs.yescaptcha.com/pt/api/get-task-result.md).
## Resultado
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
"cookies": {
"cf_clearance": "Wq3vXk9...-1760860800-1.2.1.1-..."
},
"request_headers": {
"accept-language": "en-US,en;q=0.9",
"user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
},
"headers": {
"content-type": "text/html; charset=UTF-8",
"server": "cloudflare"
},
"content": "..."
}
}
```
O valor do cookie e os cabeçalhos acima são ilustrativos; use o que a API retornar.
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `cookies` | object | Todos os cookies do navegador após passar na verificação (objeto de nome para valor), normalmente incluindo `cf_clearance`; se você informou `requiredCookies`, todos eles estarão incluídos. Use-os junto com o `user_agent` retornado e o proxy que você informou |
| `user_agent` | string | O User-Agent que o navegador realmente usou para passar na verificação (Chrome desktop no Linux). O `cf_clearance` está vinculado a ele, então use-o em todas as requisições seguintes |
| `request_headers` | object | Cabeçalhos de requisição que o navegador enviou na última requisição à página de destino; reutilize-os nas requisições seguintes |
| `headers` | object | Cabeçalhos de resposta da página de destino após passar na verificação |
| `content` | string | Código-fonte HTML da página de destino após passar na verificação |
## Como usar o resultado
1. Nas requisições seguintes, use **ao mesmo tempo** os `cookies` retornados, o `user_agent` retornado e o mesmo proxy usado ao criar a tarefa. O `cf_clearance` está vinculado ao User-Agent e ao IP de saída; se qualquer um dos três mudar, a página de desafio volta a aparecer.
2. Envie também os cabeçalhos de `request_headers`, sempre que possível, e use uma impressão digital TLS compatível com a de um navegador (por exemplo, a opção `impersonate` do curl\_cffi).
3. O `cf_clearance` tem prazo de validade (definido pelo site de destino; em alguns casos chega a 1 hora). Dentro desse prazo não é preciso passar pelo desafio de novo, mas uma frequência de requisições muito alta pode levar o Cloudflare a bloquear o IP.
4. Se você só precisa do conteúdo da página, use `content` diretamente, sem fazer outra requisição.
## Erros comuns
Erros retornados na criação da tarefa não geram cobrança de pontos; tarefas que falham ou expiram depois de criadas têm reembolso de pontos automático. A API retorna apenas o código de erro e uma descrição genérica; consulte a tabela abaixo para identificar a causa.
| Código de erro | Quando é retornado | O que fazer |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Na criação da tarefa: falta `websiteURL` ou `proxy` | Informe os dois campos obrigatórios |
| `ERROR_ILLEGAL_PARAMETERS` | Na criação da tarefa: `websiteURL` não é uma URL pública iniciada por `http://` / `https://`, `postData` não é um objeto ou `requiredCookies` não é um array de strings. Na consulta do resultado: não foi possível resolver o domínio de destino pelo proxy | Corrija os parâmetros; verifique a grafia da URL e se o proxy consegue acessar o site |
| `ERROR_PROXY_INCORRECT` | Na criação da tarefa: formato de proxy incorreto, sem porta, proxy `https://` ou SOCKS5 com usuário e senha | Use um dos formatos de “Requisitos de proxy”; se precisar de usuário e senha, use um proxy HTTP |
| `ERROR_PROXY_BANNED` | Na criação da tarefa: o proxy é um endereço local, de rede interna ou reservado, ou falhou ao conectar várias vezes em pouco tempo. Na consulta do resultado: o Cloudflare do site bloqueou diretamente o IP do proxy (páginas “Sorry, you have been blocked” e “Access denied”) | Troque de proxy; quanto melhor a qualidade do IP, mais fácil é passar |
| `ERROR_PROXY_CONNECT_REFUSED` | Não foi possível conectar ao proxy (conexão recusada, domínio do proxy não resolvido) ou a conexão foi recusada ou redefinida ao abrir a página pelo proxy | Verifique o endereço e a porta do proxy e confirme que ele está online e aceita acesso externo; se continuar falhando, troque de proxy |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Tempo esgotado ao conectar ao proxy ou ao abrir a página por ele | Use um proxy mais rápido e estável |
| `ERROR_PROXY_NOT_AUTHORISED` | Usuário ou senha do proxy incorretos | Verifique o usuário e a senha em `proxy`; codifique caracteres especiais com URL encoding |
| `ERROR_PROXY_TLS_ERROR` | Erro no handshake TLS ao abrir a página pelo proxy | Confirme que o endereço, a porta e o protocolo do proxy estão corretos; se continuar falhando, troque de proxy |
| `ERROR_CAPTCHA_UNSOLVABLE` | A verificação não foi aprovada no tempo previsto, a página continuou no desafio após a aprovação ou não foi possível obter o cookie exigido em `requiredCookies` | Tente novamente com outro proxy; para sites específicos, entre em contato com o suporte |
| `ERROR_NO_SLOT_AVAILABLE` | Na criação da tarefa: a fila está cheia. Na consulta do resultado: a tarefa esperou tempo demais na fila sem começar, e os pontos foram reembolsados | Aguarde alguns segundos e crie a tarefa novamente |
| `ERROR_TASK_TIMEOUT` | A tarefa não foi concluída no tempo previsto | Crie a tarefa novamente; timeouts repetidos geralmente indicam que o proxy está lento demais |
Veja todos os códigos de erro em [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md).
## Relacionados
- [Identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md): diferença entre a página de desafio e o Turnstile
- [Cloudflare Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md)
---
# 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)
---
# Reconhecimento de imagem do reCAPTCHA v2
> Reconheça os desafios de imagem do reCAPTCHA v2 com o YesCaptcha (ReCaptchaV2Classification): envie uma imagem 3x3, 4x4 ou 1x1 com o ID da pergunta e receba de forma síncrona as células a clicar; preço por tamanho da imagem, tabela de IDs de perguntas.
Source: https://docs.yescaptcha.com/pt/tasks/recaptcha-classification/ · 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/recaptcha-classification/
`ReCaptchaV2Classification` reconhece os desafios de imagem exibidos pelo reCAPTCHA v2: você envia a imagem e o ID da pergunta, e recebe quais células devem ser clicadas; o clique é feito pelo seu programa no navegador. Ele **não retorna token**. A resposta é síncrona: uma única requisição `createTask` já traz o resultado. Cada imagem 3x3 ou 4x4 custa 6 pontos (≈ US$0.90 / 1k), e a imagem pequena 1x1 é mais barata (veja a tabela abaixo).
> **Dica:** Se não quiser escrever a lógica de clique, use a [extensão do navegador](https://docs.yescaptcha.com/pt/extension.md), que clica automaticamente com base nesta mesma API.
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
## Tipos e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `ReCaptchaV2Classification` | US$0.90 / 1k; 6 pontos/tarefa · ¥6 / 1k | Síncrono | 2 pontos para uma peça 1x1 (100x100); 6 pontos para 3x3 (300x300) e 4x4 (450x450) |
Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.
## 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 |
| `image` | string | Sim | Imagem do desafio codificada em Base64, sem o prefixo `data:` |
| `question` | string | Sim | ID da pergunta, como `/m/0k4j`; veja "IDs de perguntas" nesta página |
| `confidence` | number | Não | Limite de confiança de 0 a 1, usado apenas em imagens 3x3. Se informado (0.5 é um bom ponto de partida), todas as células acima desse valor são retornadas; se omitido, as 3 células mais prováveis são retornadas |
> **Cuidado:** A imagem deve ser redimensionada para um dos tamanhos padrão da tabela abaixo; o servidor identifica o tipo de desafio pelo tamanho.
| Tipo de desafio | Tamanho da imagem | Retorno |
| --- | --- | --- |
| Grade 3x3 (“Select all images with …”) | 300 × 300 | `objects`: células a clicar |
| Grade 4x4 (“Select all squares with …”) | 450 × 450 | `objects`: células a clicar |
| Imagem pequena 1x1 (imagem única que aparece após clicar na grade 3x3) | 100 × 100 | `hasObject`: se esta imagem deve ser clicada |
Se você trabalha com capturas de tela, identifique o tipo pelo texto da pergunta: a 3x3 diz “Select all images with …” e a 4x4 diz “Select all squares with …”.
## Exemplo de requisição
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "ReCaptchaV2Classification",
"image": "BASE64_IMAGE",
"question": "/m/0k4j"
}
}
```
## Resultado
3x3 e 4x4:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [1, 5, 8],
"type": "multi"
},
"taskId": "3a9e8cb8-3871-11ec-9794-94e6f7355a0b"
}
```
Imagem pequena 1x1:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"hasObject": true,
"type": "single"
}
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `objects` | array | Índices das imagens a clicar, começando em 0, da esquerda para a direita e de cima para baixo |
| `hasObject` | boolean | Retornado para uma imagem 1x1; indica se a imagem contém o alvo |
| `type` | string | Tipo de desafio: `multi` (imagem 3x3 ou 4x4, veja `objects`), `single` (imagem 1x1, veja `hasObject`); `drag` para perguntas de arrastar do hCaptcha |
As células são numeradas a partir de 0, da esquerda para a direita e de cima para baixo:
## confidence: receber de uma vez todas as células que correspondem
Depois que você clica na grade 3x3, normalmente aparecem imagens pequenas 1x1 que também precisam ser avaliadas. Se for difícil capturar essas imagens (por exemplo, em desenvolvimento para celular), envie `confidence`:
- Sem `confidence`, a imagem 3x3 retorna as 3 células com maior pontuação (o reCAPTCHA exige pelo menos 3 cliques).
- Com `confidence` (recomendado `0.5`), retorna todas as células com pontuação acima desse valor, que podem ser mais ou menos de 3; se nenhuma corresponder, retorna um array vazio. Assim você não precisa mais capturar as imagens 1x1.
- Não tem efeito em imagens 4x4 e 1x1.
## IDs de perguntas
Em `question`, informe o ID da pergunta (começa com `/m/`), não o texto. O ID vem junto com a imagem na resposta da requisição que o reCAPTCHA usa para carregar o desafio (`reload` ou `userverify`). A tabela abaixo lista as perguntas mais comuns; o texto em chinês serve apenas de referência:
16 no total
| ID da pergunta | Pergunta (inglês) |
| --- | --- |
| `/m/0pg52` | `taxis` |
| `/m/01bjv` | `bus` |
| `/m/04_sv` | `motorcycles` |
| `/m/013xlm` | `tractors` |
| `/m/01jk_4` | `chimneys` |
| `/m/014xcs` | `crosswalks` |
| `/m/015qff` | `traffic lights` |
| `/m/0199g` | `bicycles` |
| `/m/015qbp` | `parking meters` |
| `/m/0k4j` | `cars` |
| `/m/015kr` | `bridges` |
| `/m/019jd` | `boats` |
| `/m/0cdl1` | `palm trees` |
| `/m/09d_r` | `mountains or hills` |
| `/m/01pns0` | `fire hydrant` |
| `/m/01lynh` | `stairs` |
Nenhuma pergunta correspondente
`ERROR_UNKNOWN_QUESTION` indica que o ID está errado ou que a pergunta ainda não é suportada. `ERROR_UNKNOW_450x450_QUESTION` indica que a pergunta ainda não é suportada em imagens 4x4; basta recarregar o desafio na página para obter outra.
## Reportar e reembolso de pontos
Se a verificação falhar após o clique, você pode reportar com [report](https://docs.yescaptcha.com/pt/api/report.md) em até 1 hora; o reembolso de pontos é liquidado após cerca de 24 horas. As regras estão em [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md). Quando a verificação for aprovada, reporte também com `isSuccess: true`.
## Tutoriais relacionados
- [Reconhecimento de imagem do reCAPTCHA v2 com cliques simulados (Selenium)](https://docs.yescaptcha.com/pt/guides/recaptcha-click-selenium.md)
- [reCAPTCHA v2 (retorna token)](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md)
---
# Reconhecimento de imagem do hCaptcha
> Reconheça os desafios de imagem do hCaptcha com o YesCaptcha (HCaptchaClassification): seleção em grade 3×3, clique em posição indicada, arrastar até a posição indicada e perguntas com animação; resposta síncrona, sem cobrança de pontos quando nenhum alvo é encontrado.
Source: https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification/ · 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/hcaptcha-classification/
`HCaptchaClassification` reconhece os desafios de imagem exibidos pelo hCaptcha: você envia a pergunta e as imagens, e recebe quais imagens selecionar, qual posição clicar ou de onde para onde arrastar; seu programa executa a ação no navegador. Ele **não retorna token**. A resposta é síncrona, cada requisição custa 8 pontos (≈ US$1.20 / 1k), e não há cobrança de pontos quando nenhum alvo é encontrado (resultado vazio).
> **Dica:** Se não quiser escrever a lógica de cliques, use a [extensão do navegador](https://docs.yescaptcha.com/pt/extension.md), que oferece suporte a todos esses tipos de desafio. Se precisa de um token em vez de posições de clique, use [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md).
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
## Tipos de tarefa e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `HCaptchaClassification` | US$1.20 / 1k; 8 pontos/tarefa · ¥8 / 1k | Síncrono | Não há cobrança de pontos quando nenhum alvo é encontrado |
Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.
## 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 |
| `queries` | array | Sim | Lista de imagens da pergunta codificadas em Base64, na ordem da página (9 imagens pequenas para uma grade 3×3) |
| `question` | string | Não | A pergunta completa, como aparece na página (recomendado chinês simplificado ou inglês), por exemplo `Please click each image containing a bicycle`. Envie pelo menos um entre `question` e `anchors`; recomendamos enviar os dois |
| `anchors` | array | Não | Lista de imagens de exemplo (exibidas ao lado da pergunta) codificadas em Base64; obrigatória para perguntas que as tenham |
- Envie em `question` a frase completa exatamente como aparece na página; não é necessário traduzi-la, mas recomendamos mudar o idioma do hCaptcha para chinês simplificado ou inglês. Novas perguntas costumam ser suportadas rapidamente; categorias totalmente novas, em até 3 dias úteis.
> **Cuidado:** Se a pergunta tiver uma imagem de exemplo pequena no canto superior direito, envie-a em `anchors`. Desafios que só podem ser resolvidos olhando a imagem de exemplo não são reconhecidos sem `anchors`.
## Seleção em grade 3×3
A pergunta é do tipo “Please click each image containing …” e há 9 imagens pequenas abaixo. Em `queries`, envie as 9 imagens em Base64, na ordem em que aparecem:
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaClassification",
"question": "Please click each image containing a bicycle",
"queries": ["BASE64_IMAGE_1", "BASE64_IMAGE_2"]
}
}
```
Resposta:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [true, false, false, true, true, false, true, true, false],
"top_k": [0, 3, 4, 6, 7],
"confidences": [1.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0, 0.0]
}
}
```
`objects` e `top_k` trazem a mesma informação: o primeiro indica, para cada imagem, se ela é um alvo; o segundo lista os índices das imagens-alvo (a partir de 0). Basta clicar nessas imagens.
## Clique em posição indicada
A pergunta é do tipo “Please click on …” e abaixo há uma imagem grande, na qual você deve clicar em uma ou mais posições.
1. Use em `question` a pergunta exibida na página; se houver imagens de exemplo, envie-as em `anchors`.
2. Em `queries`, envie uma imagem: o ideal é a imagem original exportada diretamente do canvas (recomendamos converter para JPG). Se só for possível fazer captura de tela, capture a área da imagem grande marcada em vermelho abaixo, sem sobrar nem faltar.
3. O `box` retornado contém as coordenadas a clicar, na ordem x1, y1, x2, y2…, com origem no canto superior esquerdo da imagem enviada.
4. Se o tamanho da imagem enviada for diferente do tamanho exibido na página, faça a conversão: x na página = x retornado × largura exibida ÷ largura da imagem enviada (y segue a mesma lógica). Por exemplo, se o x retornado é 769, a largura exibida do canvas é 350 e a largura da imagem enviada é 1000, deve-se clicar em 769 × 350 ÷ 1000 ≈ 269 na página.
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "HCaptchaClassification",
"question": "Please click on the entity present in the sample image.",
"anchors": ["BASE64_ANCHOR_1", "BASE64_ANCHOR_2", "BASE64_ANCHOR_3"],
"queries": ["BASE64_OF_THE_BIG_IMAGE"]
}
}
```
Resposta:
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"box": ["221", "213"]
}
}
```
Quando há vários alvos para clicar, `box` traz vários pares de coordenadas em sequência: `["221", "213", "340", "118", ...]`.
## Arrastar até a posição indicada
A pergunta é do tipo “Drag … to …”: você deve arrastar as peças da direita até o local correspondente na imagem.
1. Use em `question` a pergunta exibida na página.
2. Envie em `queries` uma captura de tela que mostre **ao mesmo tempo** as peças a arrastar e as posições de destino, com cada lado da imagem de no mínimo 260 pixels.
3. Cada item de `box` na resposta é um arrasto: `start` é a posição da peça e `end` é a posição para onde arrastá-la. Havendo várias peças, arraste uma de cada vez.
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"type": "drag",
"box": [
{
"start": [644, 218],
"end": [239, 315]
}
]
}
}
```
Se você obteve dados do protocolo (imagens das peças, coordenadas das peças e a imagem de fundo) em vez de uma captura de tela, primeiro cole as peças na imagem de fundo conforme as coordenadas, montando uma imagem com o mesmo aspecto da captura de tela da página, e só então envie.
## Perguntas com animação
Quando a imagem do desafio é uma animação, envie em `queries` a animação (GIF ou formato similar) em Base64. Recomendamos uma animação de pelo menos 3 segundos, de preferência 5 a 6 segundos, a cerca de 12 FPS.
## Reportar e reembolso de pontos
Se a validação falhar após os cliques, você pode reportar a tarefa com [report](https://docs.yescaptcha.com/pt/api/report.md) em até 1 hora; o reembolso de pontos é liquidado após cerca de 24 horas. Veja as regras em [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
## Tutoriais relacionados
- [Reconhecimento de imagem do hCaptcha com cliques simulados (Selenium)](https://docs.yescaptcha.com/pt/guides/hcaptcha-click-selenium.md)
---
# Reconhecimento de imagem do FunCaptcha
> Reconheça os desafios de imagem do FunCaptcha (Arkose Labs) com o YesCaptcha (FunCaptchaClassification). Envie a imagem do desafio (grade de 6 imagens ou desafio de setas com duas metades) e a pergunta em inglês, e receba de forma síncrona qual imagem escolher; todos os tipos de desafio são suportados.
Source: https://docs.yescaptcha.com/pt/tasks/funcaptcha-classification/ · Last verified: 2026-10-16
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/funcaptcha-classification/
`FunCaptchaClassification` reconhece os desafios de imagem do FunCaptcha (Arkose Labs): envie a imagem do desafio e a pergunta em inglês, e a API retorna qual imagem escolher; seu programa faz o clique no navegador. Ele **não retorna token**. É síncrono e custa 3 pontos (≈ US$0.45 / 1k) por requisição.
> **Dica:** Sem escrever código, use a [extensão do navegador](https://docs.yescaptcha.com/pt/extension.md) para resolver automaticamente na página.
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
## Tipos de tarefa e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `FunCaptchaClassification` | US$0.45 / 1k; 3 pontos/tarefa · ¥3 / 1k | Sí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.
## 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 |
| `image` | string | Sim | Imagem do desafio codificada em Base64, sem o prefixo `data:` |
| `question` | string | Sim | O texto da pergunta em inglês (por exemplo, `Pick the image that is the correct way up`); as perguntas compatíveis estão listadas nesta página |
- `image` deve conter apenas a parte de imagem do desafio (grade de 6 imagens, ou a imagem com as duas metades do desafio de setas), sem o título nem os botões acima. A captura deve estar completa; faltar um pedaço prejudica o reconhecimento. Grades de 6 imagens em layout vertical podem ser enviadas como estão.
- `question` é o texto completo da pergunta em inglês, exatamente como aparece na página, com maiúsculas e minúsculas corretas; não traduza por conta própria. Se a página estiver em outro idioma, mude o captcha para inglês antes. O servidor identifica o tipo de desafio pela pergunta, então ela deve estar exata.
## Exemplo de requisição
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "FunCaptchaClassification",
"image": "BASE64_IMAGE",
"question": "Pick the bread"
}
}
```
## Resultado
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"objects": [4],
"labels": ["parrot", "panda", "octopus", "owl", "bread", "dog"]
},
"taskId": "04a3fa76-11a0-11ed-a58c-0ef20f419382"
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `objects` | array | Índice da imagem a selecionar, começando em 0, da esquerda para a direita e de cima para baixo |
| `labels` | array | Rótulos reconhecidos |
`objects: [4]` significa escolher a 5ª imagem (índices começam em 0, da esquerda para a direita e de cima para baixo). Um desafio costuma ter várias rodadas seguidas; a cada rodada, faça uma nova captura e uma nova chamada.
## Perguntas suportadas
**Todos os tipos de desafio são suportados**, não é preciso consultar uma lista antes: envie a pergunta em inglês e a imagem do desafio exibidas na página. Se receber `ERROR_UNKNOWN_QUESTION`, [entre em contato com o suporte](https://docs.yescaptcha.com/pt/help/contact.md).
Hoje o mais comum é o desafio de setas com duas metades: o lado esquerdo é o exemplo a ser comparado e o lado direito é a imagem atual, que você troca com as setas na página até encontrar a que corresponde à pergunta. Envie a imagem inteira (as duas metades) como aparece na página. Por exemplo:
`Use the arrows to change the number of objects until it matches the left image`Quantidade igual à da imagem da esquerda
`use the arrows to choose the image where all the darts add up to the number in the left image`A soma dos números dos dardos é igual ao número da imagem da esquerda
`use the arrows to find the jigsaw puzzle that is missing the puzzle piece shown on the left`Falta exatamente a peça do quebra-cabeça mostrada à esquerda
`find the image that has the prize on the left held by the claw in the machine on the right`A garra segura o prêmio da esquerda
O outro tipo é a grade de 6 imagens (como `Pick the bread`): envie apenas a parte da grade de 6 imagens, como no exemplo de requisição acima.
## Reportar e reembolso de pontos
Se o envio final de um conjunto de desafios falhar e você não souber qual rodada errou, reporte todos os IDs de tarefa do conjunto com [report](https://docs.yescaptcha.com/pt/api/report.md) (em até 1 hora); o reembolso de pontos após reportar é liquidado após cerca de 24 horas. Regras em [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
---
# Reconhecimento de imagem AWS WAF / bCaptcha
> Reconheça os desafios de imagem em grade 3×3 do AWS WAF CAPTCHA e do bCaptcha com o YesCaptcha (AwsClassification, bCaptchaClassification): envie a imagem inteira e a pergunta e receba, de forma síncrona, as células a clicar.
Source: https://docs.yescaptcha.com/pt/tasks/aws-bcaptcha-classification/ · 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/aws-bcaptcha-classification/
`AwsClassification` reconhece os desafios de imagem em grade 3×3 do AWS WAF CAPTCHA, e `bCaptchaClassification` reconhece os do bCaptcha: envie a imagem inteira e a pergunta, e a API retorna quais células clicar; o clique é feito pelo seu programa no navegador. Esses tipos **não retornam token**. O retorno é síncrono e cada requisição custa 8 pontos (≈ US$1.20 / 1k).
Se não quiser escrever código, use a [extensão do navegador](https://docs.yescaptcha.com/pt/extension.md).
- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)
## Tipos e preços
| Tipo de tarefa | Preço | Modo | Observações |
| --- | --- | --- | --- |
| `AwsClassification` | US$1.20 / 1k; 8 pontos/tarefa · ¥8 / 1k | Síncrono | |
| `bCaptchaClassification` | US$1.20 / 1k; 8 pontos/tarefa · ¥8 / 1k | Sí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.
Os dois tipos usam os mesmos parâmetros e retornam o mesmo formato; escolha conforme a origem do captcha: `AwsClassification` para AWS WAF e `bCaptchaClassification` para bCaptcha.
## 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 |
| `queries` | string | Sim | Base64 da imagem completa da grade 3×3 (uma única imagem) |
| `question` | string | Não | A pergunta completa, como aparece na página, por exemplo `Select all hats`; outros idiomas são traduzidos automaticamente |
`queries` recebe a imagem **inteira** da grade 3×3 (uma só imagem, não 9 miniaturas). Use em `question` a pergunta completa exatamente como aparece na página; inglês e chinês funcionam, e outros idiomas são traduzidos automaticamente.
## Exemplo de requisição
POST https://api.yescaptcha.com/createTask
```json
{
"clientKey": "YOUR_CLIENT_KEY",
"task": {
"type": "AwsClassification",
"queries": "BASE64_IMAGE",
"question": "Select all hats"
}
}
```
## Resultado
```json
{
"errorId": 0,
"status": "ready",
"solution": {
"label": "Select All Hats",
"objects": [false, true, false, false, true, true, true, true, false],
"top_k": [1, 4, 5, 6, 7],
"confidences": [0.0, 1.0, 0.0, 0.255, 1.0, 1.0, 0.9637, 0.9999, 0.0]
},
"taskId": "2053f690-3c3b-11f0-8ffb-d2c180657082"
}
```
| Campo | Tipo | Descrição |
| --- | --- | --- |
| `label` | string | O alvo reconhecido da pergunta |
| `objects` | array | Se cada uma das 9 células é um alvo (true / false), da esquerda para a direita e de cima para baixo |
| `top_k` | array | Índices (a partir de 0) das imagens que são alvos; mesmo significado de `objects`, use um dos dois |
| `confidences` | array | Confiança de cada resultado |
As 9 células são numeradas de 0 a 8, da esquerda para a direita e de cima para baixo na grade 3×3. `objects` e `top_k` trazem a mesma informação; use um dos dois: clique nas células em que `objects` é `true`, ou nos índices de `top_k`.
## Reportar e reembolso de pontos
Se a verificação falhar após os cliques, reporte com [report](https://docs.yescaptcha.com/pt/api/report.md) em até 1 hora; o reembolso de pontos é liquidado após cerca de 24 horas. Regras em [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
---
# YesCaptcha Assistant
> YesCaptcha Assistant, a extensão do navegador para Chrome e Firefox que reconhece e clica automaticamente em reCAPTCHA, hCaptcha, FunCaptcha, AWS WAF e outros captchas. A extensão é gratuita; a cobrança de pontos segue as APIs usadas no reconhecimento. Links das lojas, download dos pacotes e vídeos de instalação para Chrome, BitBrowser e Kiwi Browser.
Source: https://docs.yescaptcha.com/pt/extension/ · Last verified: 2026-10-24
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/extension/
O YesCaptcha Assistant é uma extensão do navegador para Chrome e Firefox: ao abrir uma página com captcha, ela envia a imagem do captcha ao YesCaptcha para reconhecimento e clica automaticamente, sem precisar escrever código. A extensão é gratuita; no reconhecimento, os pontos são cobrados conforme as APIs usadas, na mesma conta e com o mesmo saldo da API.
## O que ela faz
- Reconhece e clica automaticamente nas perguntas com imagens de reCAPTCHA v2, hCaptcha, FunCaptcha, AWS WAF e bCaptcha.
- Captchas de caracteres comuns: clique com o botão direito na imagem e escolha “Marcar como captcha”, depois clique com o botão direito no campo de entrada e escolha “Inserir captcha”; a extensão reconhece a imagem e preenche a resposta.
- Nas configurações, é possível ativar ou desativar cada tipo de captcha separadamente e ajustar a velocidade dos cliques, as novas tentativas em caso de falha e outras opções.
> **Nota:** Nem todos os sites podem ser superados; recomendamos testar antes.
## Instalação
**Pela loja (recomendado, atualiza automaticamente):**
- Chrome (e navegadores baseados em Chromium, como o Edge): [Chrome Web Store](https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl)
- Firefox: [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/yescaptcha-assistant/)
Abra a página da extensão na Chrome Web Store, clique em “Usar no Chrome”, depois clique no ícone da extensão na barra de ferramentas e informe sua `clientKey`:
Seu navegador não consegue reproduzir este vídeo. Baixe-o: [Vídeo: instalação pela Chrome Web Store (34 s)](https://docs.yescaptcha.com/videos/extension-chrome-store.mp4)
Vídeo: instalação pela Chrome Web Store (34 s)
**Se não conseguir abrir a loja, baixe o pacote:**
Chrome
Versão
1.4.12
Tamanho
1.1 MB
Atualizado em
2026-11-10
[Baixar](https://api.yescaptcha.com/extension/chrome/latest)[Chrome Web Store](https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl)
Firefox
Versão
0.4.6
Tamanho
0.9 MB
Atualizado em
2026-10-31
[Baixar](https://api.yescaptcha.com/extension/firefox/latest)[Firefox Add-ons](https://addons.mozilla.org/firefox/addon/yescaptcha-assistant/)
A versão da loja do Firefox pode ser mais antiga que o pacote disponível aqui; para ter a versão mais recente, use o pacote.
### Instalar o pacote no Chrome
1. Baixe o arquivo zip e extraia-o em uma pasta fixa.
2. Abra `chrome://extensions` na barra de endereços e ative o “Modo do desenvolvedor” no canto superior direito.
3. Clique em “Carregar sem compactação” e selecione a pasta extraída.
4. Clique no ícone da extensão na barra de ferramentas e informe sua `clientKey`.
Antes de carregar, você também pode abrir o `config.js` extraído em um editor de texto, colocar sua `clientKey` entre as aspas de `clientKey: ''` e salvar; depois da instalação, não será preciso informá-la de novo. Isso poupa trabalho ao instalar a extensão em vários ambientes de navegador.
Seu navegador não consegue reproduzir este vídeo. Baixe-o: [Vídeo: instalação do pacote no Chrome, com a clientKey preenchida antes no config.js (44 s; o vídeo usa uma versão antiga, os passos são os mesmos)](https://docs.yescaptcha.com/videos/extension-chrome-zip.mp4)
Vídeo: instalação do pacote no Chrome, com a clientKey preenchida antes no config.js (44 s; o vídeo usa uma versão antiga, os passos são os mesmos)
> **Cuidado:** Depois não apague nem mova a pasta extraída, ou o navegador não conseguirá carregar a extensão. Instalações feitas pelo pacote não são atualizadas automaticamente; quando houver uma nova versão, baixe o pacote de novo.
### Instalar o pacote no Firefox
1. Baixe o arquivo `.xpi`.
2. Abra `about:addons` na barra de endereços, clique no ícone de engrenagem, escolha “Instalar extensão a partir de arquivo” e selecione o arquivo baixado.
3. Clique no ícone da extensão na barra de ferramentas e informe sua `clientKey`.
## Instalação no BitBrowser
Navegadores antidetecção como o BitBrowser usam o núcleo do Chrome. A extensão deve ser adicionada na Central de Extensões e, depois, pode ser liberada para todas as janelas ou apenas para janelas específicas. Os passos e os vídeos abaixo foram gravados com o BitBrowser 6.0, cuja interface está em chinês; versões mais novas podem ter uma interface um pouco diferente.
### Adicionar pela Chrome Web Store
1. No BitBrowser, clique em “Central de Extensões” na barra lateral esquerda, clique em “Adicionar extensão personalizada” e escolha “Adicionar extensão da Chrome Web Store”.
2. No campo de URL de detalhes da extensão, cole o endereço da extensão na Chrome Web Store, `https://chromewebstore.google.com/detail/yescaptcha-assistant/jiofmdifioeejeilfkpegipdjiopiekl`, e clique no botão à direita do campo para identificá-la. Quando aparecer “YesCaptcha Assistant”, clique em “Confirmar”.
3. Depois de adicionar, clique em “Configurações” no cartão do YesCaptcha Assistant e, em “Definir como a extensão é ativada”, escolha “Todas as janelas” ou escolha “Janelas específicas” e marque as janelas desejadas; clique em “Confirmar”.
4. Abra uma janela do navegador, clique no ícone de extensões na barra de ferramentas, localize o YesCaptcha Assistant e informe sua `clientKey`; quando o saldo aparecer, a configuração está pronta.
Seu navegador não consegue reproduzir este vídeo. Baixe-o: [Vídeo: adicionar pela Chrome Web Store no BitBrowser (30 s)](https://docs.yescaptcha.com/videos/extension-bit-store.mp4)
Vídeo: adicionar pela Chrome Web Store no BitBrowser (30 s)
### Adicionar pelo pacote
1. Baixe o pacote do Chrome acima e extraia-o em uma pasta fixa.
2. (Opcional) Abra o `config.js` da pasta em um editor de texto, coloque sua `clientKey` entre as aspas de `clientKey: ''` e salve. Assim, não será preciso informá-la em cada janela depois da instalação.
3. Na Central de Extensões, clique em “Adicionar extensão personalizada”, escolha “Adicionar extensão local” e, em “Enviar extensão”, selecione a pasta extraída (o nível que contém o `manifest.json`); clique em “Confirmar”.
4. Depois do envio, clique em “Configurações” no cartão do YesCaptcha Assistant, escolha como ativá-lo (todas as janelas ou janelas específicas) e clique em “Confirmar”.
5. Abra uma janela do navegador e clique no YesCaptcha Assistant no ícone de extensões; quando a chave e o saldo aparecerem, a configuração está pronta.
Seu navegador não consegue reproduzir este vídeo. Baixe-o: [Vídeo: adicionar o pacote no BitBrowser (46 s; o vídeo usa uma versão antiga, os passos são os mesmos)](https://docs.yescaptcha.com/videos/extension-bit-zip.mp4)
Vídeo: adicionar o pacote no BitBrowser (46 s; o vídeo usa uma versão antiga, os passos são os mesmos)
## No celular Android (Kiwi Browser)
> **Cuidado:** O Kiwi Browser deixou de ser mantido em janeiro de 2025 e foi removido do Google Play, portanto não recebe mais atualizações nem correções de segurança. Os passos e o vídeo abaixo vêm da documentação antiga e servem de referência para quem ainda usa o Kiwi Browser; a versão atual da extensão não foi testada novamente nele.
1. Baixe o pacote do Chrome (`.zip`) no celular, sem extrair. Se quiser deixar a chave preenchida, extraia o pacote antes em um computador, edite o `config.js` e compacte de novo em zip (o `manifest.json` deve ficar no nível mais externo do arquivo compactado).
2. No Kiwi Browser, toque no menu no canto superior direito e escolha “Extensions” (Extensões).
3. Ative o “Developer mode” (Modo do desenvolvedor), toque em “+ (from .zip/.crx/.user.js)” e selecione o pacote baixado.
4. Toque novamente no menu no canto superior direito; o YesCaptcha Assistant aparece no final. Abra-o e informe sua `clientKey`; quando o saldo aparecer, a configuração está pronta.
Seu navegador não consegue reproduzir este vídeo. Baixe-o: [Vídeo: instalação no Kiwi Browser (16 s; o vídeo usa uma versão antiga, os passos são os mesmos)](https://docs.yescaptcha.com/videos/extension-kiwi.mp4)
Vídeo: instalação no Kiwi Browser (16 s; o vídeo usa uma versão antiga, os passos são os mesmos)
## Configuração
1. Cadastre-se e recarregue em [yescaptcha.com](https://yescaptcha.com/) e copie sua `clientKey` no Painel; veja o [Início rápido](https://docs.yescaptcha.com/pt/getting-started/quickstart.md).
2. Clique no ícone da extensão e informe a chave no painel de configurações; quando o saldo aparecer, a configuração está pronta.
3. Abra uma página com captcha; a extensão começa a reconhecer automaticamente.
## Custos
A extensão é gratuita. No reconhecimento, os pontos são cobrados conforme o tipo usado: por exemplo, as perguntas com imagens do reCAPTCHA seguem o preço de [reconhecimento de imagem do reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md) e o hCaptcha segue o de [reconhecimento de imagem do hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification.md). Resultados errados podem ser reportados para reembolso de pontos após reportar; veja [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
---
# Identificar o tipo de captcha
> Como saber qual captcha uma página usa (reCAPTCHA v2, v2 invisível, v3, Enterprise, hCaptcha, Cloudflare Turnstile versus a página de desafio do Cloudflare) e qual tipo de tarefa do YesCaptcha usar.
Source: https://docs.yescaptcha.com/pt/guides/identify-captcha/ · 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/guides/identify-captcha/
O primeiro passo para escolher o tipo de tarefa certo é reconhecer o captcha. A forma mais confiável é abrir as ferramentas de desenvolvedor do navegador (F12) e ver, no painel Network (Rede), qual script de captcha a página carrega; também dá para identificar pela aparência.
## Identificar pela aparência
Como cada captcha aparece na página (ilustrações animadas, não capturas de tela); clique em um cartão para abrir a página do tipo de tarefa. Se a aparência não for suficiente, confirme com a referência rápida e o painel Network abaixo.
- [reCAPTCHA v2: Caixa de seleção · Invisível](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md)
- [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md)
- [Reconhecimento de imagem do reCAPTCHA v2: Grade 3×3 · Grade 4×4 · Imagem única 1x1](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md)
- [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md)
- [Reconhecimento de imagem do hCaptcha: Grade de imagens · Clicar em um ponto · Arrastar e soltar · Animada](https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification.md)
- [Cloudflare Turnstile: Automático · Caixa de seleção](https://docs.yescaptcha.com/pt/tasks/turnstile.md)
- [Página de desafio do Cloudflare: Automático · Caixa de seleção](https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge.md)
- [Reconhecimento de imagem do FunCaptcha: Setas · Grade de 6 imagens](https://docs.yescaptcha.com/pt/tasks/funcaptcha-classification.md)
- [Reconhecimento de imagem AWS WAF / bCaptcha: AWS WAF · bCaptcha](https://docs.yescaptcha.com/pt/tasks/aws-bcaptcha-classification.md)
- [Imagem para texto: Com ruído · Linhas de ruído · Matemático](https://docs.yescaptcha.com/pt/tasks/image-to-text.md)
## Referência rápida
| O que você vê | O que é | Tipo de tarefa |
| --- | --- | --- |
| Uma caixa de seleção “Não sou um robô” / “I’m not a robot” | reCAPTCHA v2 | [reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-v2.md) |
| Sem caixa de seleção; o desafio de imagens aparece só depois de clicar em enviar; um pequeno selo do reCAPTCHA no canto inferior direito | reCAPTCHA v2 invisível (ou v3) | Veja “Versões do reCAPTCHA” abaixo |
| Nenhuma interação; só o selo do reCAPTCHA no canto inferior direito | reCAPTCHA v3 | [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md) |
| Uma caixa de seleção “Sou humano”; desafios de imagens com a marca hCaptcha | hCaptcha | [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md) |
| Uma caixa de verificação do Cloudflare dentro de um formulário; a página não muda depois de marcar | Cloudflare Turnstile | [Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md) |
| A página inteira mostra “Aguarde… / Verificando sua conexão” e redireciona sozinha | Página de desafio do Cloudflare | [Página de desafio do Cloudflare](https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge.md) |
| Quebra-cabeças ou desafios de imagens da Arkose Labs (como “escolha a imagem virada para o lado certo”) | FunCaptcha | [Reconhecimento de imagem do FunCaptcha](https://docs.yescaptcha.com/pt/tasks/funcaptcha-classification.md) |
| Uma imagem com letras e números distorcidos | Captcha de caracteres | [Imagem para texto](https://docs.yescaptcha.com/pt/tasks/image-to-text.md) |
## Versões do reCAPTCHA
Procure `api.js` ou `enterprise.js` no painel Network:
| Script carregado | Versão |
| --- | --- |
| `recaptcha/api.js`, sem o parâmetro `render` ou com `render=explicit` | v2 padrão |
| Igual ao anterior, e a URL da requisição `anchor` contém `size=invisible` | v2 invisível: adicione `"isInvisible": true` à tarefa |
| `recaptcha/api.js?render=CHAVE_DO_SITE` (`render` diferente de `explicit`) | v3 padrão |
| `recaptcha/enterprise.js`, sem o parâmetro `render` ou com `render=explicit` | v2 Enterprise |
| `recaptcha/enterprise.js?render=CHAVE_DO_SITE` | v3 Enterprise |
Exemplos:
```text
https://www.google.com/recaptcha/api.js?onload=onloadcallback&render=explicit → v2
https://www.google.com/recaptcha/api.js?render=6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696 → v3
https://www.google.com/recaptcha/enterprise.js?render=explicit → v2 Enterprise
```
A v2 invisível às vezes só passa com o tipo da v3; teste os dois.
Você também pode executar o código abaixo no Console do navegador. Ele lista todos os reCAPTCHAs da página com versão, chave do site, URL da página e função de callback:
find-recaptcha-clients.js
```js
// Paste into the browser DevTools console on a page with reCAPTCHA, then run findRecaptchaClients().
// Lists every reCAPTCHA on the page: version (V2/V3), sitekey, page URL and the callback function.
function findRecaptchaClients() {
if (typeof ___grecaptcha_cfg === 'undefined') return [];
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([, value]) => value && typeof value === 'object');
objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(
([, value]) => value && typeof value === 'object' && 'sitekey' in value && 'size' in value,
);
if (toplevel instanceof HTMLElement && toplevel.tagName === 'DIV') data.pageurl = toplevel.baseURI;
if (found) {
const [sublevelKey, sublevel] = found;
data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
findRecaptchaClients();
```
Exemplo de resultado:
```json
[
{
"id": "0",
"version": "V2",
"sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"function": "onSuccess",
"callback": "___grecaptcha_cfg.clients['0']['l']['l']['callback']",
"pageurl": "https://www.google.com/recaptcha/api2/demo"
}
]
```
As páginas de demonstração oficiais do Google servem para comparação: v2 padrão `https://www.google.com/recaptcha/api2/demo`, v2 invisível `https://www.google.com/recaptcha/api2/demo?invisible=true`.
## Turnstile e página de desafio do Cloudflare
Os dois vêm do Cloudflare, mas não são a mesma coisa:
- **Turnstile** é uma caixa de verificação embutida no formulário da página. Concluída a verificação, aparece um sinal de marcado e a própria página não muda. A página carrega `challenges.cloudflare.com/turnstile/v0/api.js`. Use [Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md).
- **A página de desafio do Cloudflare** substitui a página inteira pela tela de verificação do Cloudflare, que mostra “Aguarde…” e “xx.com precisa verificar a segurança da sua conexão antes de continuar”; ela também pode conter uma caixa de verificação. Depois de passar, redireciona para a página real. O código-fonte contém `__cf_chl_rt_tk` ou `cdn-cgi/challenge-platform`. Use [Página de desafio do Cloudflare](https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge.md).
Se uma requisição feita por programa recebe 403 com “Just a moment…”, mas o navegador abre a página normalmente, provavelmente só a impressão digital TLS está sendo bloqueada. Use uma biblioteca que imite a impressão digital TLS de um navegador (como curl\_cffi); isso resolve a requisição e não é preciso passar pelo desafio.
---
# Encontrar os parâmetros do reCAPTCHA
> Como encontrar o websiteKey (sitekey), o websiteURL, o pageAction do v3 e a função de callback do reCAPTCHA nos painéis Network, Sources e Console das ferramentas do desenvolvedor, com um script de busca automática.
Source: https://docs.yescaptcha.com/pt/guides/find-recaptcha-parameters/ · 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/guides/find-recaptcha-parameters/
Para criar uma tarefa de reCAPTCHA, você precisa do `websiteURL` (endereço da página onde aparece o captcha) e do `websiteKey` (chave do site); o v3 também exige `pageAction`. Ao simular o envio com ferramentas como o Selenium, você também precisa conhecer a função de callback. Tudo isso pode ser encontrado nas ferramentas do desenvolvedor do navegador (F12).
## O jeito mais rápido: script de busca automática
Abra a página onde aparece o captcha, pressione F12 para abrir o Console, cole o script abaixo e execute:
find-recaptcha-clients.js
```js
// Paste into the browser DevTools console on a page with reCAPTCHA, then run findRecaptchaClients().
// Lists every reCAPTCHA on the page: version (V2/V3), sitekey, page URL and the callback function.
function findRecaptchaClients() {
if (typeof ___grecaptcha_cfg === 'undefined') return [];
return Object.entries(___grecaptcha_cfg.clients).map(([cid, client]) => {
const data = { id: cid, version: cid >= 10000 ? 'V3' : 'V2' };
const objects = Object.entries(client).filter(([, value]) => value && typeof value === 'object');
objects.forEach(([toplevelKey, toplevel]) => {
const found = Object.entries(toplevel).find(
([, value]) => value && typeof value === 'object' && 'sitekey' in value && 'size' in value,
);
if (toplevel instanceof HTMLElement && toplevel.tagName === 'DIV') data.pageurl = toplevel.baseURI;
if (found) {
const [sublevelKey, sublevel] = found;
data.sitekey = sublevel.sitekey;
const callbackKey = data.version === 'V2' ? 'callback' : 'promise-callback';
const callback = sublevel[callbackKey];
if (!callback) {
data.callback = null;
data.function = null;
} else {
data.function = callback;
const keys = [cid, toplevelKey, sublevelKey, callbackKey].map((key) => `['${key}']`).join('');
data.callback = `___grecaptcha_cfg.clients${keys}`;
}
}
});
return data;
});
}
findRecaptchaClients();
```
No resultado, `sitekey` é o `websiteKey`, `pageurl` é o `websiteURL`, `version` indica se é v2 ou v3, e `function` e `callback` correspondem à função de callback:
```json
[
{
"id": "0",
"version": "V2",
"sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
"function": "onSuccess",
"callback": "___grecaptcha_cfg.clients['0']['l']['l']['callback']",
"pageurl": "https://www.google.com/recaptcha/api2/demo"
}
]
```
Um array vazio significa que a página ainda não carregou o reCAPTCHA; execute novamente depois que o captcha aparecer.
## websiteKey e websiteURL
No painel Network, pesquise por `anchor` e encontre uma requisição como esta:
```text
https://www.google.com/recaptcha/api2/anchor?ar=1&k=6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9&co=...&hl=en&size=normal
```
- O valor depois de `k=` é o `websiteKey`.
- Em `websiteURL`, informe o endereço completo da página onde aparece o captcha (normalmente é o `Referer` dessa requisição).
Você também pode pesquisar `data-sitekey` no código-fonte da página.
## pageAction (v3)
`pageAction` é o `action` que a página passa ao chamar `grecaptcha.execute(chave do site, {action: '...'})`, e deve ser igual ao da página.
**Método 1: pesquisar no código-fonte.** No painel Sources das ferramentas do desenvolvedor, clique com o botão direito e escolha “Search in all files”. Para o v3 comum, pesquise `.execute(`; para o v3 Enterprise, pesquise `.enterprise.execute`; depois veja o `action` que vem a seguir:
```js
grecaptcha.ready(function () {
grecaptcha.execute('6LdpS-gUAAAAAL3Qr2yP7rkrQjkKBVvEY_48JS5l', { action: 'login' }).then(function (token) {
// ...
});
});
```
Aqui o `pageAction` é `login`.
**Método 2: ponto de interrupção.** Se o código estiver ofuscado e a pesquisa não encontrar nada, execute `debug(grecaptcha.execute)` no console (`debug(grecaptcha.enterprise.execute)` para o Enterprise) e, em seguida, faça na página a ação que dispara a verificação (por exemplo, clicar em login). Quando a execução parar no ponto de interrupção, veja o valor de `action` em Scope, à direita.
Um site pode usar `action` diferentes em etapas diferentes (por exemplo, no cadastro, primeiro `signup/submit_email` e depois `signup/success`); use o valor da etapa que você precisa passar. Pressione F8 para continuar a execução e ver o próximo `action`.
## Função de callback
Ao preencher o token no navegador com Selenium ou ferramentas semelhantes, depois de preencher é preciso chamar a função de callback da página para avisar que a verificação foi concluída:
- No painel Elements, pesquise `data-callback`; o valor é o nome da função de callback, por exemplo `data-callback="onSuccess"`.
- Ou pesquise `grecaptcha.render` e veja o `callback` nos parâmetros.
- Ou consulte `___grecaptcha_cfg.clients` no console, ou use o script de busca automática acima.
Como chamar:
```python
driver.execute_script("onSuccess(arguments[0])", g_recaptcha_response)
```
Algumas páginas não têm função de callback; nesse caso, preencha o token na caixa de texto `g-recaptcha-response` e envie o formulário diretamente. Veja o fluxo completo em [Concluir o reCAPTCHA com um token](https://docs.yescaptcha.com/pt/guides/submit-recaptcha-token.md).
---
# Encontrar os parâmetros do hCaptcha
> Como encontrar o websiteKey (sitekey), o websiteURL e o rqdata da versão Enterprise do hCaptcha: pesquise data-sitekey no código-fonte da página ou procure as requisições checksiteconfig e getcaptcha na aba Network.
Source: https://docs.yescaptcha.com/pt/guides/find-hcaptcha-parameters/ · 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/guides/find-hcaptcha-parameters/
Para criar uma tarefa do [hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha.md), você precisa de `websiteURL` (o endereço da página em que o captcha aparece) e `websiteKey` (a chave do site, em formato UUID); em sites com a versão Enterprise, às vezes também é necessário `rqdata`. Todos podem ser encontrados nas ferramentas de desenvolvedor do navegador (F12).
## websiteKey
**Método 1: código-fonte da página.** No painel Elements, pressione Ctrl+F (Cmd+F no Mac) e pesquise `data-sitekey`:
```html
```
O valor de `data-sitekey` é o `websiteKey`.
**Método 2: requisições de rede.** No painel Network, pesquise `hcaptcha` e encontre a requisição `checksiteconfig`; o valor depois de `sitekey=` na URL é o `websiteKey`:
```text
https://api.hcaptcha.com/checksiteconfig?v=...&host=example.com&sitekey=51829642-2cda-4b09-896c-594f89d700cc&sc=1&swa=1
```
## websiteURL
Informe o endereço completo da página em que o captcha aparece, **não** `hcaptcha.com`. O `host=` da requisição acima é o domínio dessa página.
## rqdata (Enterprise)
Alguns sites usam o hCaptcha Enterprise e, a cada carregamento do captcha, emitem um `rqdata`; sem ele, não é possível passar. Em geral, ele aparece na resposta da própria API do site (por exemplo, `captcha_rqdata` retornado pela API de login) ou é passado ao chamar `hcaptcha.render` / `hcaptcha.setData`. Depois de obtê-lo, coloque-o no campo `rqdata` da tarefa; o `rqdata` normalmente só pode ser usado uma vez, então obtenha um novo a cada vez.
## userAgent
O `userAgent` deve ser apenas o valor retornado por [/useragent](https://docs.yescaptcha.com/pt/api/useragent.md); ao enviar o token, use o `userAgent` retornado no resultado do reconhecimento.
---
# Encontrar os parâmetros do Turnstile
> Como encontrar o websiteKey (sitekey, começa com 0x) e o websiteURL do Cloudflare Turnstile: busque data-sitekey ou turnstile.render no código-fonte da página, ou veja as requisições para challenges.cloudflare.com na aba Network.
Source: https://docs.yescaptcha.com/pt/guides/find-turnstile-parameters/ · Last verified: 2026-10-21
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/guides/find-turnstile-parameters/
Criar uma tarefa [Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md) exige `websiteURL` (o endereço da página em que aparece a caixa de verificação) e `websiteKey` (a chave do site, geralmente começa com `0x`). Primeiro confirme que é Turnstile e não a página de desafio do Cloudflare; veja [Identificar o tipo de captcha](https://docs.yescaptcha.com/pt/guides/identify-captcha.md).
## websiteKey
**Método 1: código-fonte da página.** No painel Elements das ferramentas do desenvolvedor (F12), busque `data-sitekey`:
```html
```
**Método 2: scripts.** Se a caixa de verificação for renderizada com JavaScript, clique com o botão direito no painel Sources, escolha “Search in all files”, busque `turnstile.render` e veja o `sitekey` nos parâmetros:
```js
turnstile.render('#container', { sitekey: '0x4AAAAAAAxxxxxxxxxxxxxx', callback: onDone });
```
**Método 3: requisições de rede.** Busque `challenges.cloudflare.com` no painel Network; o endereço do iframe da caixa de verificação contém a chave do site, que começa com `0x`.
## websiteURL
Informe o endereço completo da página em que aparece a caixa de verificação, por exemplo `https://example.com/login`.
## action e cData (geralmente desnecessários)
Na grande maioria dos casos não são necessários. Procure por eles apenas quando tiver certeza de que `websiteKey` e `websiteURL` estão corretos e a tarefa ainda assim não passa: nos parâmetros de `turnstile.render` ou no elemento da caixa de verificação, veja se existem `action` e `cData` (no elemento são `data-action` e `data-cdata`):
```js
turnstile.render('#container', { sitekey: '0x4AAAAAAAxxxxxxxxxxxxxx', action: 'login', cData: 'c0bd4b36-7419-4e18-83c6-378699f2a9a2' });
```
Se existirem, ao criar a tarefa informe `action` em `pageAction` e `cData` em `data`; veja [Turnstile](https://docs.yescaptcha.com/pt/tasks/turnstile.md).
## Enviar o token
Quando a tarefa for concluída, coloque o `token` no campo oculto do formulário chamado `cf-turnstile-response` (se a página usa `turnstile.render` com `callback`, chame essa função de callback passando o token) e envie o formulário. Na requisição de envio, use como User-Agent o `userAgent` do resultado.
---
# Usar o token para concluir o reCAPTCHA
> O que fazer com o token do reCAPTCHA (gRecaptchaResponse) depois de obtê-lo: como funciona, envio direto por requisição (campo g-recaptcha-response) e preenchimento no navegador com chamada da função de callback, com exemplos completos em Python na página de demonstração do Google.
Source: https://docs.yescaptcha.com/pt/guides/submit-recaptcha-token/ · 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/guides/submit-recaptcha-token/
O `gRecaptchaResponse` retornado pelo YesCaptcha é o mesmo resultado que o Google entrega à página depois que alguém conclui o captcha. Depois de obtê-lo, você precisa **enviá-lo ao site de destino** (não ao Google nem ao YesCaptcha), como um navegador faria; o site o verifica com o Google e libera o acesso. Há duas formas: enviar a requisição diretamente ou preencher o token na página, em um navegador, e enviar o formulário.
## Como funciona
No acesso normal, o fluxo é:
1. A página carrega o reCAPTCHA e o usuário conclui a verificação;
2. O Google entrega um token à página, que o coloca no campo de texto `g-recaptcha-response` (ou o passa a uma função de callback);
3. O usuário envia o formulário e o token segue com ele para o servidor do site;
4. O servidor do site verifica o token com o Google e, se for válido, libera o acesso.
Com o YesCaptcha, os passos 1 e 2 são feitos por nós: você cria uma tarefa com `websiteURL` e `websiteKey`, obtém o token e continua a partir do passo 3.
> **Cuidado:** O token é de uso único e válido por cerca de 120 segundos; recomendamos enviá-lo em até 60 segundos após obtê-lo. Sites não aceitam tokens expirados.
## Método 1: enviar a requisição diretamente (recomendado)
1. Faça o processo uma vez manualmente no navegador: abra o painel Network (F12), conclua o captcha, envie o formulário e localize a requisição que o submete.
2. No Payload (ou Form Data) da requisição, encontre o campo que carrega o token, geralmente `g-recaptcha-response`, com valor começando por `03A`. Alguns sites o renomeiam, por exemplo `grecaptcharesponse` ou `captcha`.
3. No seu programa, envie uma requisição idêntica, trocando o valor desse campo pelo token retornado pelo YesCaptcha. Os demais campos, cookies e cabeçalhos também devem ser iguais aos do navegador, pois os sites costumam verificá-los em conjunto.
Exemplo completo na página de demonstração do Google: primeiro obtém-se o token e depois ele é enviado de volta à página de demonstração no campo `g-recaptcha-response`:
recaptcha_requests.py
```python
"""Solve reCAPTCHA v2 on Google's demo page and submit the token with plain HTTP (no browser).
Run: pip install requests
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_requests.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
WEBSITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
def call(method, payload):
data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def get_token():
task = {"type": "NoCaptchaTaskProxyless", "websiteURL": WEBSITE_URL, "websiteKey": WEBSITE_KEY}
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36): # poll every 5 seconds, for up to about 3 minutes
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]["gRecaptchaResponse"]
raise TimeoutError(task_id)
token = get_token()
print("token:", token[:40], "...")
# Submit the token the same way the browser does: the demo form posts the field
# "g-recaptcha-response" back to the page. Check your own site's request in DevTools > Network.
page = requests.post(WEBSITE_URL, data={"g-recaptcha-response": token}, timeout=30)
print("passed" if "Verification Success" in page.text else "not passed", page.status_code)
```
## Método 2: preencher no navegador (Selenium etc.)
Ao controlar um navegador real com ferramentas como Selenium ou Playwright:
1. Leia o `data-sitekey` da página e use-o para criar uma tarefa e obter o token.
2. Escreva o token no campo de texto `g-recaptcha-response` da página.
3. Se a página define uma função de callback (`data-callback="..."`), chame-a passando o token; em alguns sites o botão de envio só fica clicável depois que o callback é chamado.
4. Envie o formulário.
```js
// Step 2: write the token (run in the page)
document.getElementById('g-recaptcha-response').value = 'TOKEN';
// Step 3: call the callback if there is one, e.g. data-callback="onSuccess"
onSuccess('TOKEN');
```
Quando há vários reCAPTCHAs na página, o id do campo de texto pode ser algo como `g-recaptcha-response-1`. Se não encontrar o campo, conclua a verificação manualmente uma vez, procure por `03A` em Elements e veja onde o resultado foi colocado. Para saber como encontrar a função de callback, veja [Encontrar os parâmetros do reCAPTCHA](https://docs.yescaptcha.com/pt/guides/find-recaptcha-parameters.md).
Exemplo completo (Selenium 4):
recaptcha_selenium.py
```python
"""Solve reCAPTCHA v2 on Google's demo page in a real browser with Selenium 4:
get a token from YesCaptcha, put it into the page, then submit the form.
Run: pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_selenium.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time
import requests
from selenium import webdriver
from selenium.webdriver.common.by import By
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
def call(method, payload):
data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data
def get_token(website_url, website_key):
task = {"type": "NoCaptchaTaskProxyless", "websiteURL": website_url, "websiteKey": website_key}
task_id = call("createTask", {"task": task})["taskId"]
for _ in range(36):
time.sleep(5)
result = call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]["gRecaptchaResponse"]
raise TimeoutError(task_id)
driver = webdriver.Chrome() # Selenium 4 downloads a matching chromedriver automatically
try:
driver.get(WEBSITE_URL)
site_key = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-sitekey")
token = get_token(WEBSITE_URL, site_key)
# Put the token where reCAPTCHA keeps it ...
driver.execute_script(
"document.getElementById('g-recaptcha-response').value = arguments[0];", token
)
# ... and, if the page uses a callback (data-callback="..."), call it:
callback = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-callback")
if callback:
driver.execute_script(f"window[{callback!r}](arguments[0]);", token)
driver.find_element(By.ID, "recaptcha-demo-submit").click()
time.sleep(2)
print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
driver.quit()
```
## reCAPTCHA v3
O v3 não tem caixa de seleção. A página chama `grecaptcha.execute(chave do site, {action: '...'})` quando precisa de um token e o coloca em sua própria requisição (o nome do campo é definido pelo site; os mais comuns são `g-recaptcha-response`, `token` e `recaptchaToken`). O procedimento é o mesmo do Método 1: encontre no Network a requisição que carrega o token e reproduza-a; ao criar a tarefa, `pageAction` deve ser igual ao `action` da página.
## Enviei e ainda não passa
- O token expirou: envie-o assim que obtê-lo, sem passar de 60 segundos.
- O campo enviado não é o que o site verifica, ou faltam outros campos ou cookies: compare item por item com a requisição do navegador.
- O site também verifica IP, User-Agent etc.: use um tipo com proxy próprio (como `NoCaptchaTask`) e envie pelo mesmo proxy.
- Pontuação do v3 insuficiente: confirme o `pageAction` ou use um tipo de pontuação alta fixa; veja [reCAPTCHA v3](https://docs.yescaptcha.com/pt/tasks/recaptcha-v3.md).
- O controle de risco do site também considera outros sinais de comportamento. Se a taxa de aprovação com token for baixa, use [reconhecimento de imagem](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md) com cliques reais no navegador, ou a [extensão do navegador](https://docs.yescaptcha.com/pt/extension.md).
---
# Cliques em imagens do reCAPTCHA com Selenium
> Use Python, Selenium 4 e ReCaptchaV2Classification para clicar nos desafios de imagem do reCAPTCHA v2 em um navegador real. Dispare o captcha, leia a pergunta e a imagem, chame a API, clique nos quadrados e envie; código de exemplo completo.
Source: https://docs.yescaptcha.com/pt/guides/recaptcha-click-selenium/ · 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/guides/recaptcha-click-selenium/
Este tutorial abre a página de demonstração do reCAPTCHA do Google com Selenium 4 e resolve o desafio de imagem em um navegador real: lê a pergunta e a imagem, pede ao [reconhecimento de imagem do reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md) (`ReCaptchaV2Classification`) quais quadrados clicar e simula os cliques. Em comparação com obter um token, a verificação é concluída no próprio navegador, o que ajuda em sites onde os tokens raramente passam.
Se preferir não escrever código, a [extensão do navegador](https://docs.yescaptcha.com/pt/extension.md) faz o mesmo usando a mesma API.
## Preparação
```bash
pip install requests selenium pillow
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
O Chrome precisa estar instalado. O Selenium 4 baixa automaticamente o chromedriver compatível.
## Fluxo
1. **Clique na caixa de seleção.** Ela fica no iframe com `title="reCAPTCHA"`; mude para ele e clique em `#recaptcha-anchor`.
2. **Mude para o iframe do desafio.** O desafio fica em outro iframe (cujo title contém “challenge”).
3. **Leia a pergunta.** O texto em negrito em `.rc-imageselect-desc-wrapper strong` é o alvo, por exemplo “traffic lights”. A API pede o ID da pergunta, então converta o nome em ID (`/m/015qff`) usando a tabela de correspondência em [IDs de pergunta](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md). Com a interface do navegador em inglês, a correspondência fica mais fácil.
4. **Obtenha a imagem.** Os quadrados são fatias de uma única imagem grande; baixe o `src` de `td.rc-imageselect-tile img`. Redimensione para 300×300 as imagens de 9 quadrados (3x3) e para 450×450 as de 16 quadrados (4x4), e converta para Base64.
5. **Reconheça.** Chame `createTask` com o tipo `ReCaptchaV2Classification`, `image` e `question`. Ao adicionar `"confidence": 0.5`, as imagens 3x3 retornam todos os quadrados correspondentes de uma só vez, sem precisar tratar as imagens pequenas que aparecem depois do clique.
6. **Clique.** `objects` lista os índices dos quadrados, a partir de 0, da esquerda para a direita e de cima para baixo; clique nos `td` correspondentes em sequência.
7. **Verifique.** Clique em `#recaptcha-verify-button`. Se aparecer uma nova rodada, volte ao passo 3; quando a janela do desafio fechar, a verificação foi aprovada.
8. **Envie o formulário.** Volte à página principal e clique no botão de envio.
## Código completo
recaptcha_click_selenium.py
```python
"""Click through a reCAPTCHA v2 image challenge with Selenium 4 and ReCaptchaV2Classification.
Flow: open the page -> click the checkbox -> read the target name and the grid image ->
ask YesCaptcha which tiles to click -> click them -> press Verify. Repeat if a new challenge appears.
Run: pip install requests selenium pillow
export YESCAPTCHA_CLIENT_KEY=your_client_key
python recaptcha_click_selenium.py
Each recognized image is charged (see the price list). reCAPTCHA's page structure can change;
adjust the selectors below if a step stops working.
"""
import base64
import io
import os
import time
import requests
from PIL import Image
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
PAGE_URL = "https://www.google.com/recaptcha/api2/demo"
# Target names shown in the challenge (English UI) -> question IDs.
# Full list: https://docs.yescaptcha.com/en/tasks/recaptcha-classification/
QUESTION_IDS = {
"taxis": "/m/0pg52", "bus": "/m/01bjv", "buses": "/m/01bjv", "motorcycles": "/m/04_sv",
"tractors": "/m/013xlm", "chimneys": "/m/01jk_4", "crosswalks": "/m/014xcs",
"traffic lights": "/m/015qff", "bicycles": "/m/0199g", "parking meters": "/m/015qbp",
"cars": "/m/0k4j", "bridges": "/m/015kr", "boats": "/m/019jd", "palm trees": "/m/0cdl1",
"mountains or hills": "/m/09d_r", "fire hydrants": "/m/01pns0", "a fire hydrant": "/m/01pns0",
"stairs": "/m/01lynh",
}
def classify(image_b64, question):
task = {"type": "ReCaptchaV2Classification", "image": image_b64, "question": question, "confidence": 0.5}
data = requests.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
timeout=30,
).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data["solution"] # synchronous: the solution comes back right away
def grid_image_b64(url, size):
"""Download the challenge image and scale it to the standard size (300 for 3x3, 450 for 4x4)."""
img = Image.open(io.BytesIO(requests.get(url, timeout=30).content)).convert("RGB")
img = img.resize((size, size))
buf = io.BytesIO()
img.save(buf, format="JPEG")
return base64.b64encode(buf.getvalue()).decode()
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)
try:
driver.get(PAGE_URL)
# 1. Click the checkbox (inside the "reCAPTCHA" iframe)
wait.until(EC.frame_to_be_available_and_switch_to_it((By.CSS_SELECTOR, 'iframe[title="reCAPTCHA"]')))
wait.until(EC.element_to_be_clickable((By.ID, "recaptcha-anchor"))).click()
driver.switch_to.default_content()
# 2. Switch to the challenge iframe and solve rounds until it closes
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.XPATH, '//iframe[contains(@title, "challenge")]')))
for _ in range(5):
target = wait.until(EC.presence_of_element_located(
(By.CSS_SELECTOR, ".rc-imageselect-desc-wrapper strong"))).text.strip().lower()
question = QUESTION_IDS.get(target)
if not question:
print("unsupported target, reloading:", target)
driver.find_element(By.ID, "recaptcha-reload-button").click()
time.sleep(2)
continue
tiles = driver.find_elements(By.CSS_SELECTOR, "td.rc-imageselect-tile")
size = 450 if len(tiles) == 16 else 300
url = driver.find_element(By.CSS_SELECTOR, "td.rc-imageselect-tile img").get_attribute("src")
solution = classify(grid_image_b64(url, size), question)
for index in solution.get("objects", []):
tiles[index].click()
time.sleep(0.3)
time.sleep(1)
driver.find_element(By.ID, "recaptcha-verify-button").click()
time.sleep(3)
driver.switch_to.default_content()
frame = driver.find_element(By.XPATH, '//iframe[contains(@title, "challenge")]')
if not frame.is_displayed(): # challenge closed: passed
break
driver.switch_to.frame(frame)
driver.switch_to.default_content()
driver.find_element(By.ID, "recaptcha-demo-submit").click()
time.sleep(2)
print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
driver.quit()
```
## Observações
- A estrutura da página do reCAPTCHA muda com o tempo; ajuste os seletores se algum deixar de funcionar.
- Cada imagem reconhecida gera cobrança de pontos (preços em [reconhecimento de imagem do reCAPTCHA v2](https://docs.yescaptcha.com/pt/tasks/recaptcha-classification.md)). Tarefas cuja verificação falhou após os cliques podem ser [reportadas](https://docs.yescaptcha.com/pt/api/report.md) em até 1 hora para solicitar o reembolso de pontos.
- Se a pergunta não estiver na tabela de correspondência, clique no botão de recarregar para trocar de desafio ou entre em contato com o suporte para pedir que seja adicionada.
---
# Clique em imagens do hCaptcha com Selenium
> Use Python, Selenium 4 e HCaptchaClassification para resolver desafios de imagens em grade 3×3 do hCaptcha em um navegador real. Clique na caixa de seleção, leia a pergunta e as 9 imagens, chame a API, clique e envie; código de exemplo completo.
Source: https://docs.yescaptcha.com/pt/guides/hcaptcha-click-selenium/ · 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/guides/hcaptcha-click-selenium/
Este tutorial abre a página de demonstração do hCaptcha com Selenium 4 e resolve o desafio de imagens em grade 3×3 em um navegador real: lê a pergunta e as 9 imagens, pede ao [reconhecimento de imagem do hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification.md) (`HCaptchaClassification`) quais são os alvos e simula os cliques.
O hCaptcha também tem desafios de clicar em uma posição e de arrastar, que retornam coordenadas em vez de células; veja [reconhecimento de imagem do hCaptcha](https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification.md). Se não quiser escrever código, a [extensão do navegador](https://docs.yescaptcha.com/pt/extension.md) cobre todos esses tipos.
## Preparação
```bash
pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## Fluxo
1. **Clique na caixa de seleção.** Ela fica no iframe do hCaptcha cuja URL contém `frame=checkbox`; entre nele e clique em `#checkbox`.
2. **Mude para o iframe do desafio.** Ele é o iframe cuja URL contém `frame=challenge`.
3. **Leia a pergunta.** O texto de `.prompt-text` é a pergunta; envie-o exatamente como está (recomenda-se mudar o idioma da interface do hCaptcha para chinês simplificado ou inglês). Se houver uma imagem de exemplo ao lado da pergunta, coloque-a também em `anchors`.
4. **Obtenha as imagens.** O `.task-image .image` de cada célula tem uma imagem como plano de fundo; baixe-as em ordem, converta para Base64 e monte a lista `queries`.
5. **Reconheça.** Chame `createTask` com o tipo `HCaptchaClassification`. Os `objects` retornados correspondem às células, uma a uma; `true` indica um alvo.
6. **Clique e envie.** Clique nas células que são alvos e no botão de envio. Podem vir várias rodadas em sequência; repita os passos 3 a 6.
7. **Concluído.** Após a aprovação, o campo `h-captcha-response` da página contém o token; envie-o junto com o formulário.
## Código completo
hcaptcha_click_selenium.py
```python
"""Click through an hCaptcha 3x3 image challenge with Selenium 4 and HCaptchaClassification.
Flow: open the page -> click the checkbox -> read the question and the 9 images ->
ask YesCaptcha which images match -> click them -> submit. Repeat while new rounds appear.
Run: pip install requests selenium
export YESCAPTCHA_CLIENT_KEY=your_client_key
python hcaptcha_click_selenium.py
Each recognized round is charged (see the price list; rounds with no target found are free).
hCaptcha changes its page structure often; adjust the selectors below if a step stops working.
Click and drag questions return coordinates instead; see the HCaptchaClassification page.
"""
import base64
import os
import re
import time
import requests
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.wait import WebDriverWait
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
PAGE_URL = "https://accounts.hcaptcha.com/demo"
def classify(question, images_b64):
task = {"type": "HCaptchaClassification", "question": question, "queries": images_b64}
data = requests.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
timeout=60,
).json()
if data.get("errorId"):
raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
return data["solution"] # synchronous
def background_image_b64(element):
"""The tiles are s with a CSS background image; download it and Base64-encode it."""
style = element.get_attribute("style") or ""
match = re.search(r'url\("?(.*?)"?\)', style)
if not match:
return None
return base64.b64encode(requests.get(match.group(1), timeout=30).content).decode()
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 15)
try:
driver.get(PAGE_URL)
# 1. Click the checkbox (inside the first hCaptcha iframe)
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.CSS_SELECTOR, 'iframe[src*="hcaptcha"][src*="frame=checkbox"]')))
wait.until(EC.element_to_be_clickable((By.ID, "checkbox"))).click()
driver.switch_to.default_content()
# 2. Solve rounds in the challenge iframe
wait.until(EC.frame_to_be_available_and_switch_to_it(
(By.CSS_SELECTOR, 'iframe[src*="hcaptcha"][src*="frame=challenge"]')))
for _ in range(5):
question = wait.until(EC.presence_of_element_located((By.CSS_SELECTOR, ".prompt-text"))).text.strip()
tiles = driver.find_elements(By.CSS_SELECTOR, ".task-image")
images = [background_image_b64(t.find_element(By.CSS_SELECTOR, ".image")) for t in tiles]
if not tiles or None in images:
print("not a 3x3 image challenge; see the docs for click/drag questions")
break
solution = classify(question, images)
for tile, hit in zip(tiles, solution.get("objects", [])):
if hit:
tile.click()
time.sleep(0.3)
driver.find_element(By.CSS_SELECTOR, ".button-submit").click()
time.sleep(3)
if not driver.find_elements(By.CSS_SELECTOR, ".task-image"):
break
driver.switch_to.default_content()
token = driver.find_element(By.NAME, "h-captcha-response").get_attribute("value")
print("token received" if token else "not passed")
finally:
driver.quit()
```
## Observações
- A estrutura da página do hCaptcha muda com frequência; se os seletores do código deixarem de funcionar, ajuste-os conforme a página real.
- Cada rodada reconhecida gera cobrança de pontos; rodadas em que nenhum alvo é encontrado não são cobradas. Se a verificação falhar após os cliques, você pode [reportar](https://docs.yescaptcha.com/pt/api/report.md) em até 1 hora para solicitar o reembolso de pontos.
- Se uma pergunta nova retornar `ERROR_UNKNOWN_QUESTION`, atualize para obter outro desafio ou entre em contato com o suporte.
---
# Exemplos de código e SDKs
> Exemplos de código executáveis do YesCaptcha (Python, Node.js, curl, C#, Easy Language) e SDKs não oficiais da comunidade (Python, Node.js, Go).
Source: https://docs.yescaptcha.com/pt/samples/ · 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/samples/
Os exemplos aqui são arquivos completos, prontos para executar, que leem a clientKey da variável de ambiente `YESCAPTCHA_CLIENT_KEY`. As páginas de cada tipo de tarefa também trazem exemplos em curl, Python e Node.js gerados para o respectivo tipo.
[Python](https://docs.yescaptcha.com/pt/samples/python.md)Consulta de saldo, primeira requisição, cliente reutilizável, controle de simultaneidade, Selenium
[Node.js](https://docs.yescaptcha.com/pt/samples/nodejs.md)Node.js 18+, sem bibliotecas de terceiros
[C#](https://docs.yescaptcha.com/pt/samples/csharp.md).NET 6+
[Easy Language](https://docs.yescaptcha.com/pt/samples/easy-language.md)Exemplos de cliques simulados contribuídos por usuários
Para testar apenas pela linha de comando, veja os exemplos em curl em [Início rápido](https://docs.yescaptcha.com/pt/getting-started/quickstart.md) e [getBalance](https://docs.yescaptcha.com/pt/api/get-balance.md).
## SDKs da comunidade
Os SDKs abaixo foram contribuídos por usuários e **não são oficiais**. Não revisamos o código deles; avalie-os por conta própria antes de usar e, em caso de problemas, entre em contato com os autores:
| Linguagem | Projeto |
| --- | --- |
| Python | [github.com/yescaptcha/yescaptcha-python](https://github.com/yescaptcha/yescaptcha-python) |
| Node.js | [github.com/ScoLib/yescaptcha](https://github.com/ScoLib/yescaptcha) |
| Go | [github.com/FreedWu/yescaptcha](https://github.com/FreedWu/yescaptcha) |
| Go | [github.com/deanxv/yescaptcha-go](https://github.com/deanxv/yescaptcha-go) |
Ao usar qualquer SDK, confirme que ele chama `api.yescaptcha.com` ou `cn.yescaptcha.com` e que os nomes dos tipos de tarefa coincidem com os deste site.
---
# Python
> Exemplos em Python do YesCaptcha: consultar o saldo, reconhecer um captcha de imagem, uma classe de cliente reutilizável (cria a tarefa e consulta periodicamente a cada 5 segundos), controle de tarefas simultâneas com asyncio e envio de reCAPTCHA com requests e Selenium.
Source: https://docs.yescaptcha.com/pt/samples/python/ · 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/samples/python/
Requisitos: Python 3.8 ou superior e `pip install requests`. Antes de executar, defina a variável de ambiente:
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## Consultar o saldo
Não cobra pontos; serve para confirmar que a `clientKey` está correta:
get_balance.py
```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
r = requests.post(
"https://api.yescaptcha.com/getBalance",
json={"clientKey": CLIENT_KEY},
timeout=30,
)
data = r.json()
if data.get("errorId"):
# e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
print("balance (points):", data["balance"])
```
## Reconhecer um captcha de imagem
O tipo síncrono `ImageToTextTaskOcrBase` retorna o resultado em uma única requisição. Imagem de exemplo: [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg).
quickstart.py
```python
"""First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
(synchronous, 2 points per image).
Usage:
export YESCAPTCHA_CLIENT_KEY=your_client_key
python quickstart.py captcha.png
"""
import base64
import os
import sys
import requests
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
with open(image_path, "rb") as f:
body = base64.b64encode(f.read()).decode() # no "data:" prefix
r = requests.post(
"https://api.yescaptcha.com/createTask",
json={
"clientKey": CLIENT_KEY,
"task": {"type": "ImageToTextTaskOcrBase", "body": body},
},
timeout=30,
)
data = r.json()
if data.get("errorId"):
raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
print("text:", data["solution"]["text"])
```
## Um cliente reutilizável
Copie o arquivo abaixo para o seu projeto; ele funciona com tipos síncronos e assíncronos:
yescaptcha.py
```python
"""A small client you can copy into your project: create tasks, poll results, check the balance.
from yescaptcha import YesCaptcha
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
"""
import os
import time
import requests
class YesCaptchaError(Exception):
def __init__(self, code, description):
super().__init__(f"{code}: {description}")
self.code = code
self.description = description
class YesCaptcha:
def __init__(self, client_key, endpoint="https://api.yescaptcha.com", poll_interval=5, timeout=180):
self.client_key = client_key
self.endpoint = endpoint.rstrip("/")
self.poll_interval = poll_interval # 5 s: polling the same taskId more often only returns "processing"
self.timeout = timeout
self.session = requests.Session()
def call(self, method, payload=None):
body = {"clientKey": self.client_key, **(payload or {})}
data = self.session.post(f"{self.endpoint}/{method}", json=body, timeout=30).json()
if data.get("errorId"):
raise YesCaptchaError(data.get("errorCode"), data.get("errorDescription"))
return data
def balance(self):
return self.call("getBalance")["balance"]
def solve(self, task):
created = self.call("createTask", {"task": task})
if created.get("status") == "ready": # synchronous types return the solution directly
return created["solution"]
task_id = created["taskId"]
deadline = time.time() + self.timeout
while time.time() < deadline:
time.sleep(self.poll_interval)
result = self.call("getTaskResult", {"taskId": task_id})
if result.get("status") == "ready":
return result["solution"]
raise TimeoutError(f"task {task_id} not ready after {self.timeout}s")
if __name__ == "__main__":
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
print("balance:", client.balance())
```
```python
from yescaptcha import YesCaptcha
client = YesCaptcha(os.environ["YESCAPTCHA_CLIENT_KEY"])
solution = client.solve({
"type": "HCaptchaTaskProxyless",
"websiteURL": "https://accounts.hcaptcha.com/demo",
"websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
print(solution["gRecaptchaResponse"])
```
Em caso de erro, é lançada a exceção `YesCaptchaError`; `e.code` é o código de erro (veja [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md)).
## Controlar a simultaneidade
Ao enviar tarefas em lote, limite o número de requisições em processamento ao mesmo tempo e, ao receber `ERROR_THREADS_MAXIMUM`, aguarde um pouco antes de tentar de novo (requer `pip install aiohttp`). Detalhes em [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md):
concurrency.py
```python
"""Limit concurrency: keep the number of requests waiting for a result below your limit, and back off
on ERROR_THREADS_MAXIMUM (rejected requests are not charged). Requires: pip install aiohttp"""
import asyncio
import os
import aiohttp
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
LIMIT = 15 # below your concurrency limit
sem = asyncio.Semaphore(LIMIT)
async def solve(session, task):
async with sem: # at most LIMIT requests in progress at a time
result = {}
for attempt in range(5):
async with session.post(
"https://api.yescaptcha.com/createTask",
json={"clientKey": CLIENT_KEY, "task": task},
) as resp:
result = await resp.json()
if result.get("errorCode") != "ERROR_THREADS_MAXIMUM":
return result
await asyncio.sleep(1 + attempt) # over the limit: wait and retry
return result
async def main(tasks):
async with aiohttp.ClientSession() as session:
return await asyncio.gather(*(solve(session, t) for t in tasks))
if __name__ == "__main__":
print(asyncio.run(main([])))
```
## Enviar o token do reCAPTCHA
- Enviar diretamente com requests: veja [Concluir o reCAPTCHA com um token](https://docs.yescaptcha.com/pt/guides/submit-recaptcha-token.md)
- Preencher no navegador com Selenium: veja [Concluir o reCAPTCHA com um token](https://docs.yescaptcha.com/pt/guides/submit-recaptcha-token.md)
- Simular cliques nas perguntas com imagens usando Selenium: veja [Cliques simulados no reconhecimento de imagem do reCAPTCHA v2](https://docs.yescaptcha.com/pt/guides/recaptcha-click-selenium.md) e [Cliques simulados no reconhecimento de imagem do hCaptcha](https://docs.yescaptcha.com/pt/guides/hcaptcha-click-selenium.md)
---
# Node.js
> Exemplos de Node.js para o YesCaptcha (Node.js 18+, com o fetch nativo, sem bibliotecas de terceiros): consultar o saldo, reconhecer um captcha de imagem e uma classe de cliente reutilizável (criar tarefa, consultar a cada 5 segundos).
Source: https://docs.yescaptcha.com/pt/samples/nodejs/ · 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/samples/nodejs/
Ambiente: Node.js 18 ou superior (com `fetch` nativo). Os exemplos são ES modules (`.mjs`) e não exigem bibliotecas de terceiros. Antes de executar, defina a variável de ambiente:
```bash
export YESCAPTCHA_CLIENT_KEY=your_client_key
```
## Consultar o saldo
Não cobra pontos; serve para confirmar que a clientKey está correta:
get-balance.mjs
```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const res = await fetch('https://api.yescaptcha.com/getBalance', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
// e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
console.log('error:', data.errorCode, data.errorDescription);
} else {
console.log('balance (points):', data.balance);
}
```
## Reconhecer um captcha de imagem
O tipo síncrono `ImageToTextTaskOcrBase` retorna o resultado em uma única requisição. Imagem de exemplo: [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg). Execute `node quickstart.mjs captcha.jpg`.
quickstart.mjs
```js
// First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
// Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
import { readFileSync } from 'node:fs';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
const res = await fetch('https://api.yescaptcha.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
});
const data = await res.json();
if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
console.log('text:', data.solution.text);
```
## Um cliente reutilizável
yescaptcha.mjs
```js
// A small client you can copy into your project: create tasks, poll results, check the balance. Node.js 18+
//
// import { YesCaptcha } from './yescaptcha.mjs';
// const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
// const solution = await client.solve({ type: 'NoCaptchaTaskProxyless', websiteURL: '...', websiteKey: '...' });
export class YesCaptchaError extends Error {
constructor(code, description) {
super(`${code}: ${description}`);
this.code = code;
}
}
export class YesCaptcha {
constructor(clientKey, { endpoint = 'https://api.yescaptcha.com', pollInterval = 5000, timeout = 180000 } = {}) {
this.clientKey = clientKey;
this.endpoint = endpoint.replace(/\/$/, '');
this.pollInterval = pollInterval; // 5 s: polling the same taskId more often only returns "processing"
this.timeout = timeout;
}
async call(method, payload = {}) {
const res = await fetch(`${this.endpoint}/${method}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientKey: this.clientKey, ...payload }),
});
const data = await res.json();
if (data.errorId) throw new YesCaptchaError(data.errorCode, data.errorDescription);
return data;
}
async balance() {
return (await this.call('getBalance')).balance;
}
async solve(task) {
const created = await this.call('createTask', { task });
if (created.status === 'ready') return created.solution; // synchronous types return the solution directly
const deadline = Date.now() + this.timeout;
while (Date.now() < deadline) {
await new Promise((r) => setTimeout(r, this.pollInterval));
const result = await this.call('getTaskResult', { taskId: created.taskId });
if (result.status === 'ready') return result.solution;
}
throw new Error(`task ${created.taskId} not ready after ${this.timeout} ms`);
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
console.log('balance:', await client.balance());
}
```
```js
import { YesCaptcha } from './yescaptcha.mjs';
const client = new YesCaptcha(process.env.YESCAPTCHA_CLIENT_KEY);
const solution = await client.solve({
type: 'TurnstileTaskProxyless',
websiteURL: 'https://example.com/login',
websiteKey: '0x4AAAAAAA_SITE_KEY',
});
console.log(solution.token);
```
Em caso de erro, é lançado `YesCaptchaError`; `err.code` é o código de erro (veja [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md)).
---
# C#
> Exemplo em C# do YesCaptcha (.NET 6+, HttpClient + System.Text.Json): consulta o saldo, cria uma tarefa reCAPTCHA v2 e consulta o resultado a cada 5 segundos.
Source: https://docs.yescaptcha.com/pt/samples/csharp/ · 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/samples/csharp/
Ambiente: .NET 6 ou superior, apenas a biblioteca padrão (`HttpClient`, `System.Text.Json`).
```bash
dotnet new console -o YesCaptchaDemo
cd YesCaptchaDemo
# replace Program.cs with the code below
export YESCAPTCHA_CLIENT_KEY=your_client_key
dotnet run
```
Program.cs
```csharp
// YesCaptcha C# sample (.NET 6+): check the balance, then solve a reCAPTCHA v2.
// Run: dotnet new console -o YesCaptchaDemo, replace Program.cs with this file, set YESCAPTCHA_CLIENT_KEY, then dotnet run
using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Threading.Tasks;
class Program
{
const string Api = "https://api.yescaptcha.com";
static readonly HttpClient Http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
static readonly string ClientKey = Environment.GetEnvironmentVariable("YESCAPTCHA_CLIENT_KEY") ?? "";
static async Task Call(string method, JsonObject payload)
{
payload["clientKey"] = ClientKey;
var res = await Http.PostAsJsonAsync($"{Api}/{method}", payload);
var data = JsonNode.Parse(await res.Content.ReadAsStringAsync())!;
if ((int?)data["errorId"] != 0)
throw new Exception($"{data["errorCode"]}: {data["errorDescription"]}");
return data;
}
static async Task Solve(JsonObject task)
{
var created = await Call("createTask", new JsonObject { ["task"] = task });
if ((string?)created["status"] == "ready") return created["solution"]!; // synchronous types
var taskId = (string)created["taskId"]!;
for (var i = 0; i < 36; i++) // poll every 5 seconds, for up to about 3 minutes
{
await Task.Delay(5000);
var result = await Call("getTaskResult", new JsonObject { ["taskId"] = taskId });
if ((string?)result["status"] == "ready") return result["solution"]!;
}
throw new TimeoutException(taskId);
}
static async Task Main()
{
var balance = await Call("getBalance", new JsonObject());
Console.WriteLine($"balance (points): {balance["balance"]}");
var solution = await Solve(new JsonObject
{
["type"] = "NoCaptchaTaskProxyless",
["websiteURL"] = "https://www.google.com/recaptcha/api2/demo",
["websiteKey"] = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
Console.WriteLine(solution["gRecaptchaResponse"]);
}
}
```
Para usar outros tipos de tarefa, basta alterar o objeto de tarefa em `Solve`; os campos estão nas páginas de cada [tipo de tarefa](https://docs.yescaptcha.com/pt/tasks.md). Os tipos síncronos (reconhecimento de imagem, `ImageToTextTaskOcrBase`) retornam o resultado diretamente em `createTask`, caso que `Solve` já trata.
---
# Easy Language
> Exemplos de YesCaptcha em Easy Language contribuídos por usuários. Cliques simulados em reCAPTCHA e hCaptcha, reconhecimento de imagem do FunCaptcha e envio de token do reCAPTCHA; pacotes para download e pontos principais para chamar a API.
Source: https://docs.yescaptcha.com/pt/samples/easy-language/ · 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/samples/easy-language/
Os exemplos em Easy Language foram contribuídos por usuários (南方填表, 松 e outros) e servem apenas como referência; não os revisamos linha por linha. Os exemplos incluem:
- Cliques simulados em reCAPTCHA e hCaptcha (abre o navegador, reconhece e clica automaticamente)
- Reconhecimento de imagem do FunCaptcha
- Envio de token do reCAPTCHA
> **Pacotes para download:** Os pacotes de exemplo (o maior tem cerca de 87 MB e inclui um navegador) estão sendo migrados para um novo endereço de download. Por enquanto, [entre em contato com o suporte](https://docs.yescaptcha.com/pt/help/contact.md) para obtê-los.
## Pontos principais para chamar a API em Easy Language
Você não precisa dos pacotes de exemplo: o comando de acesso web (POST) do Easy Language é suficiente para chamar a API:
1. URL `https://api.yescaptcha.com/createTask`, método `POST`, com o cabeçalho `Content-Type: application/json`.
2. O corpo é um texto JSON, por exemplo `{"clientKey":"YOUR_CLIENT_KEY","task":{"type":"ImageToTextTaskOcrBase","body":"BASE64_IMAGE"}}`.
3. Na resposta JSON, `errorId` igual a 0 indica sucesso. Para tipos assíncronos, pegue o `taskId` e envie `{"clientKey":"…","taskId":"…"}` para `https://api.yescaptcha.com/getTaskResult` a cada 5 segundos, até que `status` seja `ready`.
4. O Base64 da imagem não deve ter o prefixo `data:image/...;base64,` nem quebras de linha.
Formato de requisição e resposta: [Requisição e resposta](https://docs.yescaptcha.com/pt/api/overview.md).
## O exemplo não executa
- Mensagem de que não foi possível criar o navegador: use o navegador incluído no pacote de exemplo, desinstale outros navegadores que possam entrar em conflito ou compile o programa antes de executá-lo.
- Um código de erro é retornado: confira os parâmetros com a página [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md).
---
# Várias clientKeys: limite de gastos, IPs permitidos e expiração
> Uma conta YesCaptcha pode ter até 20 clientKeys, todas usando o mesmo saldo da conta. Cada uma pode ter seu próprio limite de gastos (por dia, semana ou mês, ou um total único, zerado no horário de Pequim), IPs permitidos e data de expiração, com efeito em poucos segundos.
Source: https://docs.yescaptcha.com/pt/account/client-keys/ · Last verified: 2026-10-29
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/account/client-keys/
Uma conta YesCaptcha pode ter até 20 `clientKey`s (incluindo a original), gerenciadas na página Chaves e segurança do Painel em [yescaptcha.com](https://yescaptcha.com/security). Toda `clientKey` pode criar tarefas e consultar o saldo, e todas usam o mesmo saldo da conta. Cada uma pode ter seu próprio limite de gastos, IPs permitidos e data de expiração, e as alterações entram em vigor em poucos segundos.
Usos típicos: separar ambiente de teste e de produção, ou projetos diferentes; repassar chaves a clientes ou parceiros seus, cada um com seu limite; e, se uma `clientKey` vazar, excluir apenas essa, sem afetar os outros programas.
## Chave principal e subchaves
| | Chave principal | Subchave |
| --- | --- | --- |
| O que é | A `clientKey` original, uma por conta | Qualquer chave criada além da principal; até 19 |
| Limite, IPs permitidos, expiração | Pode definir | Pode definir |
| Redefinir | Sim: a antiga deixa de funcionar na hora e o saldo passa para a nova | Não; exclua e crie outra |
| Excluir | Não | Sim: deixa de funcionar em poucos segundos e não pode ser restaurada |
- Todas têm o mesmo formato: os primeiros 40 caracteres são a chave secreta, seguidos do seu ID de usuário.
- Redefinir a chave principal não afeta as subchaves.
- Seja qual for a `clientKey` usada para criar tarefas ou consultar o saldo, a API e as respostas são as mesmas; a única diferença são as verificações adicionais de limite, IPs permitidos e expiração.
## Criar uma clientKey
1. Faça login em [yescaptcha.com](https://yescaptcha.com/) e abra a página Chaves e segurança ([yescaptcha.com/security](https://yescaptcha.com/security)).
2. Em “Todas as chaves”, clique em “Nova subchave”. Nome (até 40 caracteres), limite, IPs permitidos e expiração são opcionais e podem ser alterados depois.
3. Verifique sua identidade novamente quando solicitado. Criar, alterar e excluir exigem essa verificação.
4. Depois de criada, copie a `clientKey` completa e configure-a no seu programa. Você também pode vê-la novamente depois, clicando no ícone de olho na lista.
> **Nota:** Criar, alterar e excluir entram em vigor em poucos segundos. Uma chamada feita logo após criar a chave pode retornar `ERROR_KEY_DOES_NOT_EXIST`; aguarde alguns segundos e tente de novo. Nos segundos seguintes à exclusão de uma chave ou ao endurecimento de suas configurações, requisições já em andamento ainda podem ser processadas com as configurações antigas.
## Limite de gastos
O limite define quantos pontos uma `clientKey` pode gastar em um período (1,000 pontos = ¥1), de 1 a 10,000,000,000 pontos. Há quatro períodos, zerados no horário de Pequim (UTC+8):
| Período | Quando zera |
| --- | --- |
| Por dia | Todo dia às 00:00 |
| Por semana | Toda segunda-feira às 00:00 |
| Por mês | Todo dia 1 às 00:00 |
| Total único | Nunca zera. Depois de esgotado, esta `clientKey` não pode mais criar tarefas; aumente o limite para continuar usando |
- Conta os pontos efetivamente cobrados: os pontos devolvidos por falha de reconhecimento ou timeout também voltam ao limite.
- Se o que resta do limite no período atual não cobre a cobrança de pontos da tarefa, `createTask` retorna [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED), sem cobrar pontos e sem contar para a [pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md).
- A lista no Painel mostra quanto cada `clientKey` já usou no período atual e quando será zerada novamente.
- O limite não é um saldo separado: todas as `clientKey`s usam o mesmo saldo da conta, e quando o saldo da conta acaba você recebe `ERROR_ZERO_BALANCE`, como de costume.
Ao chamar [`getBalance`](https://docs.yescaptcha.com/pt/api/get-balance.md) com uma `clientKey` que tem limite, `balance` é o menor valor entre o saldo da conta e o que resta do limite no período atual, e há um campo extra `keyQuotaRemaining` (limite restante, em pontos). Uma `clientKey` sem limite não recebe esse campo, e a resposta é igual à de antes.
```json
{
"errorId": 0,
"balance": 20000,
"softBalance": 0,
"inviteBalance": 0,
"inviteBy": 0,
"keyQuotaRemaining": 20000
}
```
## IPs permitidos
Uma `clientKey` com IPs permitidos só funciona para requisições enviadas dos IPs da lista. Deixe em branco para não restringir.
- Informe o **IP público da máquina que chama a API do YesCaptcha** (o IP de saída), não o proxy dos parâmetros da tarefa. Se várias máquinas fazem chamadas, adicione o IP público de cada uma.
- Um endereço IPv4 ou IPv6, ou faixa CIDR, por linha, até 50 entradas. Um endereço isolado permite somente esse IP.
- Escreva as faixas com o endereço de rede: `203.0.113.0/24` é aceito, `203.0.113.5/24` não (os bits de host não são zero).
```text
203.0.113.10
198.51.100.0/24
2001:db8::/32
```
- Se o IP da requisição não estiver na lista, `createTask` e `getBalance` retornam [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED), sem cobrar pontos e sem contar para a pausa automática.
- Se o seu IP de saída muda (banda larga residencial, funções em nuvem, saída rotativa), não defina a lista ou permita a faixa inteira.
## Expiração
- Qualquer `clientKey`, inclusive a chave principal, pode ter uma data de expiração dentro de dez anos; depois você pode alterá-la ou removê-la a qualquer momento.
- Depois de expirada, `createTask` e `getBalance` com essa chave retornam [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_EXPIRED), sem cobrar pontos. Tarefas já criadas ainda podem ter o resultado obtido com `getTaskResult`.
- Se uma `clientKey` fica muito tempo sem uso, o sistema define uma data de expiração para proteger a conta e envia um e-mail antes do vencimento. Essa expiração não pode ser alterada: gere uma nova chave principal (o saldo passa para ela automaticamente) ou crie outra `clientKey`, e atualize o seu programa.
## Saldo, limite de tarefas simultâneas e pausa automática
- **Saldo**: todas as `clientKey`s usam o mesmo saldo da conta. Recarga, bônus de VIP, recompensa por indicação e participação do desenvolvedor pertencem à conta, seja qual for a `clientKey` usada.
- **Limite de tarefas simultâneas**: contado por conta; todas as `clientKey`s juntas compartilham o mesmo limite. Veja [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md).
- **Pausa automática**: contada por `clientKey`. Se uma `clientKey` for pausada por erros demais, as outras não são afetadas.
## Códigos de erro relacionados
| Código de erro | Quando é retornado |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | O que resta do limite no período atual não cobre esta tarefa (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | O IP da requisição não está nos IPs permitidos desta `clientKey` (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_EXPIRED) | A `clientKey` expirou (`createTask`, `getBalance`) |
Nenhum destes cobra pontos. Veja [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md) para saber o que fazer.
---
# Recarga e VIP
> Como recarregar o YesCaptcha (WeChat Pay, Alipay, PayPal, criptomoedas); 1,000 pontos = ¥1. A recarga acumulada eleva automaticamente seu nível de VIP 1 a VIP 10, e cada recarga seguinte recebe pontos de bônus proporcionais.
Source: https://docs.yescaptcha.com/pt/account/recharge/ · 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/account/recharge/
Recarregue na página de pagamento do Painel de [yescaptcha.com](https://yescaptcha.com/) ([yescaptcha.com/payment.html](https://yescaptcha.com/payment.html)). 1,000 pontos = ¥1, disponíveis imediatamente após a confirmação. Quando a recarga acumulada atinge determinado valor, você é promovido automaticamente a um nível VIP, e cada recarga seguinte recebe pontos extras de acordo com a proporção de bônus desse nível.
## Formas de pagamento
| Forma | Observações |
| --- | --- |
| WeChat Pay | Pagamento por QR code |
| Alipay | Pagamento por QR code ou redirecionamento |
| PayPal | Indicado para usuários fora da China |
| Criptomoedas | Via Cryptomus; suporta BTC, ETH, USDT e outras |
| Transferência bancária empresarial | Entre em contato com o suporte; o saldo é adicionado manualmente após confirmação do financeiro |
O histórico de recargas pode ser consultado na página de pagamento. Em caso de problemas com a recarga, [entre em contato com o suporte](https://docs.yescaptcha.com/pt/help/contact.md) e informe os dados do pedido.
## Níveis VIP
Quando a recarga acumulada atinge o valor mínimo da tabela abaixo, você é promovido automaticamente ao nível correspondente. A partir daí, cada recarga recebe pontos extras de acordo com a proporção de bônus.
| Nível | Recarga acumulada | Bônus em cada recarga |
| --- | --- | --- |
| VIP 1 | ¥10 | 2% |
| VIP 2 | ¥100 | 5% |
| VIP 3 | ¥500 | 8% |
| VIP 4 | ¥1.000 | 10% |
| VIP 5 | ¥2.000 | 15% |
| VIP 6 | ¥3.000 | 20% |
| VIP 7 | ¥6.000 | 25% |
| VIP 8 | ¥12.000 | 30% |
| VIP 9 | ¥24.000 | 35% |
| VIP 10 | ¥48.000 | 40% |
- **Acumulado**: não importa em quantas recargas o valor seja dividido; ao atingir o valor mínimo, você é promovido.
- **Calculado sobre o acumulado após a recarga**: por exemplo, se a primeira recarga for de ¥1,000 e o acumulado atingir o valor mínimo do VIP 4, essa recarga já recebe o bônus do VIP 4.
- Quem se cadastra pelo link de indicação de um amigo recebe imediatamente um nível VIP; veja [Recompensa por indicação](https://docs.yescaptcha.com/pt/account/referral.md).
- O nível atual e a proporção de bônus aparecem na página de pagamento do Painel.
---
# Recompensa por indicação
> Programa de indicação do YesCaptcha. Quem você indica recebe um nível VIP ao se cadastrar (seu nível menos 1, de VIP 1 a VIP 6), e você recebe 20% do valor que a pessoa gastar (10% para cada um quando também há participação do desenvolvedor), que pode virar saldo ou ser sacado a partir de ¥100 no Painel.
Source: https://docs.yescaptcha.com/pt/account/referral/ · 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/account/referral/
Indique amigos para o YesCaptcha: ao se cadastrarem, eles recebem um nível VIP e você ganha 20% do valor que eles gastarem. A recompensa pode ser transferida para o saldo da conta ou sacada no Painel a partir de ¥100.
## Como indicar
Faça login no Painel em [yescaptcha.com](https://yescaptcha.com/). No painel do programa de indicação você vê seu link de indicação, quantas pessoas indicou e o total de recompensas acumuladas. Envie o link aos amigos; basta que se cadastrem por ele.
## Regras
1. **VIP do amigo**: ao se cadastrar, o amigo recebe diretamente um nível VIP igual ao seu menos 1, no mínimo VIP 1 e no máximo VIP 6. Por exemplo, se você é VIP 6, seu amigo começa como VIP 5. Os percentuais de bônus de cada nível estão em [Recarga e VIP](https://docs.yescaptcha.com/pt/account/recharge.md).
2. **Sua recompensa**: a cada consumo do amigo (cobrança de pontos pelo reconhecimento), você recebe **20%** do valor gasto.
3. **Quando há participação do desenvolvedor**: se as tarefas do amigo também levam o ID de um desenvolvedor (veja [Participação do desenvolvedor](https://docs.yescaptcha.com/pt/account/developer.md)), quem indicou e o desenvolvedor **recebem 10% cada**.
4. Se o amigo reportar um resultado errado e receber reembolso de pontos em uma tarefa, a recompensa correspondente é descontada.
5. Consulte o saldo de recompensas com `inviteBalance` em [getBalance](https://docs.yescaptcha.com/pt/api/get-balance.md) (unidade: yuan).
## Usar a recompensa
- **Transferir para o saldo**: no Painel, transfira a recompensa para o saldo da conta, a 1 yuan = 1,000 pontos, para usar em reconhecimentos.
- **Sacar**: quando a recompensa chegar a **¥100**, envie um pedido de saque no Painel; o pagamento é feito após análise.
- O imposto de renda sobre o valor sacado deve ser declarado por você.
## Escreva sobre nós
Se você publicar recomendações, tutoriais, relatos de experiência, extensões ou bibliotecas sobre o YesCaptcha em fóruns, blogs ou redes sociais, envie o link ao suporte. Avaliaremos e podemos conceder pontos ou um nível VIP, conforme a qualidade do conteúdo.
Se as regras de recompensa mudarem, vale o que estiver nesta página e no [Registro de atualizações do serviço](https://docs.yescaptcha.com/pt/changelog.md).
---
# Participação do desenvolvedor
> Participação do desenvolvedor no YesCaptcha. Inclua seu softID nas requisições que seu software envia em nome dos usuários e receba 20% do valor que eles gastam (10% para cada parte quando também há um indicador); converta em saldo ou saque a partir de ¥100 no painel.
Source: https://docs.yescaptcha.com/pt/account/developer/ · 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/account/developer/
Se o seu software, script ou extensão usa o YesCaptcha, inclua o seu ID de desenvolvedor (`softID`) nas requisições que ele envia para outros usuários e você recebe uma parte do que eles gastam. Os usuários continuam usando a própria `clientKey` e os próprios pontos; a participação não custa nada a mais para eles.
## Como integrar
1. Chame [getSoftID](https://docs.yescaptcha.com/pt/api/get-soft-id.md) com a sua própria `clientKey` para obter o seu ID de desenvolvedor:
```json
{
"errorId": 0,
"softID": 3,
"balance": 0.004
}
```
2. Em cada requisição `createTask` que o seu software enviar, adicione o campo `softID` no nível superior (junto de `clientKey` e `task`; atenção às maiúsculas e minúsculas):
```json
{
"clientKey": "THE_USERS_CLIENT_KEY",
"task": {
"type": "NoCaptchaTaskProxyless",
"websiteURL": "https://www.google.com/recaptcha/api2/demo",
"websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
},
"softID": 3
}
```
`clientKey` é a chave do próprio usuário.
## Regras da participação
- Nas tarefas com o seu `softID`, **20%** do valor efetivamente gasto pelo usuário são creditados na sua participação do desenvolvedor.
- Se o usuário também foi indicado por outra pessoa (veja [Recompensa por indicação](https://docs.yescaptcha.com/pt/account/referral.md)), o desenvolvedor e quem indicou **recebem 10% cada**.
- Só as tarefas com cobrança de pontos concluída geram participação; tarefas com falha ou timeout, que têm reembolso de pontos, não geram. Se o usuário reportar um resultado incorreto e receber o reembolso de pontos, a participação dessa tarefa é descontada.
- Consulte o saldo da participação, em yuan (¥), pelo campo `balance` de [getSoftID](https://docs.yescaptcha.com/pt/api/get-soft-id.md) ou pelo campo `softBalance` de [getBalance](https://docs.yescaptcha.com/pt/api/get-balance.md).
## Como usar a participação
- **Converter em saldo**: transfira o valor para o saldo da conta no painel, na proporção de 1,000 pontos = ¥1.
- **Sacar**: quando a participação chegar a **¥100**, envie um pedido de saque no painel; o pagamento é feito após a análise.
- A declaração do imposto de renda sobre os valores sacados é responsabilidade sua.
---
# Perguntas frequentes
> Perguntas frequentes sobre o YesCaptcha. Se tarefas com falha são cobradas, por quanto tempo o token é válido, taxa de aprovação, reconhecimento humano ou por máquina, banimento de conta, uso de uma clientKey em vários lugares, qual endpoint usar, extensão vs API.
Source: https://docs.yescaptcha.com/pt/help/faq/ · 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/help/faq/
## O YesCaptcha cobra pontos quando falha ao resolver um captcha?
Não. Tarefas com falha (`ERROR_CAPTCHA_UNSOLVABLE`) e com tempo esgotado (`ERROR_TASK_TIMEOUT`) têm os pontos devolvidos automaticamente, e requisições que retornam um código de erro, como as de parâmetros inválidos, não são cobradas. Se você obteve o token mas o site de destino não o aceitou, a tarefa é cobrada como bem-sucedida, pois não temos como saber a decisão do site; nos tipos de reconhecimento de imagem, é possível reportar cliques errados para solicitar o reembolso de pontos. Veja [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
## Quanto custa cada reconhecimento?
Cada tipo de tarefa tem um preço fixo em pontos (1 ¥ = 1,000 pontos), e os preços variam conforme o tipo. Todos os preços estão em [Tipos de tarefa e preços](https://docs.yescaptcha.com/pt/tasks.md); a versão legível por máquina está em [/data/task-types.json](https://docs.yescaptcha.com/data/task-types.json).
## Por quanto tempo o token é válido?
Os tokens de reCAPTCHA, hCaptcha e Turnstile são de uso único. O token do reCAPTCHA é válido por cerca de 120 segundos; recomendamos enviá-lo em até 60 segundos após recebê-lo. O prazo de validade é definido pelo fornecedor do captcha.
## Por que às vezes o token obtido não é aprovado?
Quem decide se o token é aprovado é o site de destino. O site avalia pontuação, IP, ambiente do navegador e outros fatores, e o critério pode mudar a qualquer momento, por isso a taxa de aprovação varia de site para site. Você pode comparar outros tipos de tarefa para o mesmo captcha, usar um tipo com proxy próprio e enviar o token pelo mesmo proxy, ou usar o reconhecimento de imagem e clicar de verdade no navegador.
## Quanto tempo leva o reconhecimento?
As tarefas assíncronas costumam levar de alguns segundos a algumas dezenas de segundos, no máximo cerca de 110 segundos (180 a 220 segundos em alguns tipos); depois disso, expiram e os pontos são devolvidos automaticamente. O reconhecimento de imagem e o de texto em imagem são síncronos e retornam em uma única requisição.
## O reconhecimento é feito por humanos ou por máquina?
Por máquina, com modelos de aprendizado de máquina.
## Usar o YesCaptcha pode levar ao banimento da minha conta?
Só retornamos o resultado do reconhecimento e não temos acesso à sua conta no site de destino. Como o site avalia a atividade e se bane contas é decisão do próprio site; siga as regras dele. O YesCaptcha só pode ser usado para fins legais, e o uso ilegal é proibido.
## Uma clientKey pode ser usada em vários programas e navegadores ao mesmo tempo?
Sim. As requisições de uma mesma conta somam-se no [limite de tarefas simultâneas](https://docs.yescaptcha.com/pt/api/rate-limits.md) e compartilham o mesmo saldo.
## Devo usar o endpoint global ou o endpoint China?
Para servidores na China continental, use `cn.yescaptcha.com`; nas demais regiões, use `api.yescaptcha.com`. Consulte o resultado no mesmo endpoint em que a tarefa foi criada. Veja [Endpoints](https://docs.yescaptcha.com/pt/getting-started/endpoints.md).
## Qual é a diferença entre a extensão do navegador e a API?
A extensão também usa a mesma API para reconhecer captchas. Ela é de instalação gratuita, cobra pontos pelas chamadas de API que usa e é indicada para quem trabalha no navegador sem escrever código; a API é indicada para processamento em lote em programas. Veja [Extensão do navegador](https://docs.yescaptcha.com/pt/extension.md).
## Por que fui pausado com ERROR\_IP\_BLOCKED\_5MIN?
A mesma clientKey gerou requisições com erro demais em um minuto e foi pausada automaticamente por alguns minutos; ao fim do prazo, volta ao normal sozinha. O campo `blockReason` na resposta indica o código de erro que causou a pausa; corrija seu programa de acordo com ele. Veja [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md).
## Quais sites são compatíveis?
Oferecemos reconhecimento por tipo de captcha, não por site específico. Se é possível passar depende das configurações do site de destino, por isso recomendamos testar primeiro com um lote pequeno. Quando um site ainda não é compatível, a resposta é `ERROR_DOMAIN_NOT_ALLOWED`.
---
# Problemas de conexão e rede
> O que fazer quando não é possível acessar a API do YesCaptcha. Failed to establish a new connection, falha de DNS, interferência de software de proxy e erros de SSL (Certificate has expired, SSLEOFError).
Source: https://docs.yescaptcha.com/pt/help/troubleshooting/ · 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/help/troubleshooting/
Erros de conexão ao chamar a API (como `Failed to establish a new connection`, `getaddrinfo failed`, timeouts ou erros de SSL) geralmente vêm da rede da sua máquina, do DNS ou de software de proxy. Siga os passos abaixo na ordem.
## 1\. Teste o outro endpoint
O YesCaptcha tem dois endpoints: `https://api.yescaptcha.com` (global) e `https://cn.yescaptcha.com` (China). Use o endpoint China em servidores na China continental e o global nas demais regiões. Ao trocar de endpoint, consulte os resultados no mesmo endpoint.
```bash
curl -s https://api.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
curl -s https://cn.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
```
Se um dos dois retornar JSON, a sua rede está funcionando e o problema está na rota até o outro endpoint.
## 2\. Verifique o software de proxy
Não é necessário proxy para acessar o YesCaptcha. Se há um proxy ou VPN em execução:
- Desative-o e tente novamente;
- Se precisar mantê-lo ativo, use o modo por regras (PAC) em vez do modo global, ou adicione `api.yescaptcha.com` e `cn.yescaptcha.com` à lista de conexão direta;
- `SSLEOFError(8, 'EOF occurred in violation of protocol')` no Python com um proxy ativo também costuma ser causado pelo proxy; desative-o ou faça esses dois domínios conectarem diretamente.
## 3\. Verifique a rede e o DNS
```bash
ping api.yescaptcha.com
```
- Mensagem de host não encontrado: falha na resolução de DNS. Limpe o cache de DNS (Windows: `ipconfig /flushdns`; macOS: `sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder`) ou troque o DNS do computador por um DNS público (por exemplo `223.5.5.5`, `119.29.29.29`, `8.8.8.8`) e tente novamente.
- O ping falha, mas o endereço é resolvido: a rede pode estar bloqueando ICMP, o que não significa que a API esteja inacessível. Considere o resultado do curl do passo 1.
## 4\. Erros de certificado SSL
- `Certificate has expired` ou `certificate verify failed`: primeiro verifique se o **horário do sistema** está correto; depois atualize o sistema operacional, o `certifi` do Python, o Postman e outras ferramentas para a versão mais recente, para que tenham os certificados raiz atualizados.
- Use sempre `https://`. Não troque para `http://` nem desative a verificação de certificado para contornar o erro.
## 5\. Ainda não resolveu?
[Entre em contato com o suporte](https://docs.yescaptcha.com/pt/help/contact.md) informando: a mensagem de erro completa, o endpoint que você usa, a região do seu servidor e a saída do curl do passo 1.
---
# Fale conosco
> Entre em contato com o suporte do YesCaptcha por WeChat, QQ, WhatsApp, LINE, Telegram @yescaptcha_official ou e-mail yescaptcha@gmail.com, das 9:00 às 21:00 (UTC+8).
Source: https://docs.yescaptcha.com/pt/help/contact/ · 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/help/contact/
O suporte do YesCaptcha funciona das **9:00 às 21:00 (UTC+8, horário de Pequim)**. Se a resposta demorar, deixe uma mensagem e responderemos o mais rápido possível.
- E-mail: [yescaptcha@gmail.com](mailto:yescaptcha@gmail.com)
- Telegram: [@yescaptcha\_official](https://t.me/yescaptcha_official)
Escaneie o código para nos adicionar:
**WeChat**Escaneie no WeChat para nos adicionar; podemos incluir você no grupo de usuários
**QQ**Escaneie no QQ para nos adicionar
**WhatsApp**Escaneie com a câmera do WhatsApp
**LINE**Escaneie em "Adicionar amigos" no LINE
**[Telegram](https://t.me/yescaptcha_official)**@yescaptcha\_official
Ao entrar em contato, informe:
- O e-mail da sua conta ou o ID de usuário (**nunca** envie a `clientKey`);
- O `taskId`, o código de erro e o horário em que ocorreu;
- Qual tipo de tarefa e qual endpoint (`api.yescaptcha.com` ou `cn.yescaptcha.com`) você usou.
Muitas dúvidas já são respondidas em [Perguntas frequentes](https://docs.yescaptcha.com/pt/help/faq.md), [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md) e [Problemas de conexão e rede](https://docs.yescaptcha.com/pt/help/troubleshooting.md).
---
# Registro de alterações do serviço
> Mudanças do YesCaptcha que afetam os usuários, por data: tipos de tarefa lançados e desativados, regras de cobrança e de reembolso de pontos, limite de tarefas simultâneas e migração da documentação. Registrado a partir de outubro de 2026.
Source: https://docs.yescaptcha.com/pt/changelog/ · Last verified: 2026-10-19
> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/changelog/
Esta página registra, por data, as mudanças que afetam os usuários: tipos de tarefa lançados e desativados, regras de cobrança, regras de limite e assim por diante. As mais recentes aparecem primeiro.
## 2026-10-19
- **A página de desafio do Cloudflare não é mais marcada como “não recomendada”**: o serviço por trás de `CloudFlareTaskS2` e `CloudFlareTaskS3` foi reconstruído; uma tarefa normalmente leva de 6 a 35 segundos. Os dois tipos têm os mesmos parâmetros, resultados e eficácia, e os preços não mudam (25 e 20 pontos). O proxy deve ser `http://` (com usuário e senha opcionais) ou `socks5://` sem usuário e senha; proxies `https://` e endereços locais ou da rede interna são recusados na criação da tarefa (sem cobrança de pontos). O `userAgent` só é usado se for do Chrome para desktop no Linux; nas requisições seguintes, use o `user_agent` do resultado. Se você enviar `requiredCookies`, a tarefa só é bem-sucedida quando todos forem obtidos. Veja [página de desafio do Cloudflare](https://docs.yescaptcha.com/pt/tasks/cloudflare-challenge.md).
## 2026-10-16
- **Os tipos FunCaptcha que retornam token não são recomendados por enquanto**: o custo é alto e não há uma solução estável. `FunCaptchaTask` passa a custar 30 pontos por tarefa (antes, 15). `FunCaptchaTaskProxyless` continua sem conseguir resolver; as tarefas com falha têm reembolso de pontos automático. Para passar pelo FunCaptcha, use o [reconhecimento de imagem do FunCaptcha](https://docs.yescaptcha.com/pt/tasks/funcaptcha-classification.md) ou a extensão do navegador.
## 2026-10-15
- **Migração da documentação**: a documentação saiu do Confluence e foi para este site (docs.yescaptcha.com), em chinês e inglês, e o chinês é a referência. Há [llms.txt](https://docs.yescaptcha.com/llms.txt), [OpenAPI](https://docs.yescaptcha.com/openapi.json) e uma versão em Markdown de cada página, para leitura por IA e por programas.
- **O reembolso de pontos após reportar passa a ser liquidado em cerca de 24 horas**: nos tipos de reconhecimento de imagem, ao reportar um erro de reconhecimento, o reembolso de pontos deixa de ser imediato e é liquidado de uma só vez após cerca de 24 horas; se a taxa de falhas for claramente maior que a do mesmo período, o reembolso segue a taxa de falhas do período. Veja [Cobrança e reembolso de pontos](https://docs.yescaptcha.com/pt/getting-started/billing.md).
- **Limite de tarefas simultâneas**: passamos a contar as tarefas em processamento por conta e por tipo de tarefa. Acima do limite, a resposta é `ERROR_THREADS_MAXIMUM`, sem cobrança de pontos e sem contar para a pausa automática. Quando as cotas de cada tipo forem definidas, serão publicadas em [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md).
- **Mais tipos de tarefa públicos**: `HCaptchaTask`, `NoCaptchaTask`, `TurnstileTask` e `RecaptchaV2EnterpriseTask` (com proxy próprio), além de `FunCaptchaTaskProxylessM1`, `FunCaptchaTask` e `HCaptchaTaskProxylessM1`, passam a constar na documentação.
- **Tipos FunCaptcha que retornam token**: `FunCaptchaTaskProxylessM1` e `FunCaptchaTask` estão disponíveis; a rota de `FunCaptchaTaskProxyless` não consegue resolver desde cerca de 2026-09-10, e as tarefas com falha têm reembolso de pontos automático.
- **Desativados**: a série de impressões digitais personalizadas K1 do reCAPTCHA, `FunCaptchaTaskS1`, `CloudFlareTaskS1`, `TurnstileTaskS2`, `TurnstileTaskProxylessS2`, `bCaptcha2Classification` e `GeneralClassification` deixaram de ser atendidos.
## Antes de 2026-10-15
- O serviço de aluguel autônomo de **servidor dedicado** foi desativado.