POST /captcha/tasks. Quando você chama qualquer interface de captcha (série token ou série recognition) e passa async: true, a interface retornará imediatamente um task_id, o servidor assumirá e continuará a processar; você pode usar esse task_id para consultar o resultado final, mas a consulta não é uma condição para a continuação da execução da tarefa. É aplicável a cenários como rotação de múltiplos decodificadores (multi-solver rotation): após enviar a tarefa, você obtém imediatamente o task_id, pode agendar outros decodificadores e voltar mais tarde para ler o resultado.
📘 Documentação interativa completa (incluindo depuração online): API de Consulta de Tarefas de Captcha →
Processo de Solicitação
Para usar esta interface, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser mantido em reserva. Um Token de API é suficiente para chamar todos os serviços da plataforma, não é necessário solicitar um para cada serviço.Uso Básico
Passo 1: Criar Tarefa de Forma Assíncrona
No corpo da solicitação de qualquer interface de captcha, passeasync: true, a interface retornará imediatamente um task_id (HTTP 201), sem bloquear a espera:
Passo 2 (Opcional): Consultar Resultados com task_id
Se precisar verificar o progresso ativamente, você pode usar otask_id retornado na etapa anterior para consultar POST /captcha/tasks (recomenda-se a cada 3~5 segundos). Esta interface não acionará ou avançará o processamento da tarefa; ao ler resultados prontos, o comportamento de liquidação única existente será mantido:
status: processing:
status: ready e o campo de resultado correspondente — a estrutura do campo é idêntica ao modo síncrono:
- Série token (hcaptcha, recaptcha2, recaptcha3) retorna
token:
- Classificação recognition (recognition/recaptcha2, recognition/hcaptcha) retorna
solution; recognition/image2text retornatext.
/captcha/tasks é aplicável a todas as interfaces de captcha (séries token e recognition), basta usar o mesmo task_id para a consulta.
O servidor continuará a processar desde a criação, por um máximo de 120 segundos. Se na última consulta antes do prazo não houver resultado, retornará um HTTP 504 persistente. Esse estado é terminal, o cliente deve parar a consulta; consultas repetidas ao mesmo task_id retornarão consistentemente o mesmo resultado de falha:
ready e HTTP 504 incluirão campos de temporização.
started_at, hora de início do processamento da tarefa, timestamp Unix (segundos, ponto flutuante).finished_at, hora de produção do resultado da tarefa, timestamp Unix (segundos, ponto flutuante). Não será retornado enquanto estiver em processamento.elapsed, tempo de processamento da tarefa, em segundos (ponto flutuante, com 3 casas decimais). Não será retornado enquanto estiver em processamento.
Instruções de Cobrança
No modo assíncrono, a criação de tarefas e a leitura do estado “em processamento” não são cobradas; a cobrança ocorre uma vez quando o cliente lê o resultado com sucesso pela primeira vez (consistente com o comportamento existente e o preço do modo síncrono). O servidor avançará a tarefa autonomamente, mas não cobrará antecipadamente se o processamento em segundo plano for concluído antes. Tarefas que não forem bem-sucedidas dentro do prazo de 120 segundos serão encerradas com HTTP 504 e não serão cobradas.Tratamento de Erros
Ao chamar esta interface, se ocorrer um erro, retornará o código e a mensagem de erro correspondentes. Por exemplo:400 invalid_request: A solicitação está faltando o parâmetrotask_id.401 invalid_token: Não autorizado, Token de autorização inválido ou ausente.404 not_found:task_idnão existe ou não pertence à conta atual.504 timeout: A tarefa foi encerrada e não produziu resultados; por favor, pare de consultar essetask_id. Essa falha não resultará em cobrança.