Requisições e respostas

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

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.
• 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:

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Falha:

{
  "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
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.

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
• getTaskResult: obter resultado
• Limite de tarefas simultâneas e pausa automática: erros em excesso causam uma pausa de alguns minutos