Skyvern Integrando CapSolver: Um Guia sobre Gerenciamento de CAPTCHA em Automação de Navegadores de IA

TL;DR

• Skyvern é responsável por abrir páginas da web, preencher formulários e avançar em fluxos de trabalho empresariais, enquanto o CapSolver lida com a devolução do Token CAPTCHA.

• Instale diretamente o SDK oficial capsolver e chame capsolver.solve() para evitar implementar logicamente createTask e a verificação por conta própria.

• Assim que o Token for obtido, retorne-o para a página atual do navegador, em seguida, deixe o Skyvern submeter o formulário e verificar os resultados.

Introdução

Skyvern é uma plataforma de automação de navegadores de inteligência artificial construída com Playwright, modelos de visão e Grandes Modelos de Linguagem (LLMs). O Skyvern consegue entender texto, formulários e elementos interativos em uma página da web, completando tarefas como navegação em páginas, cliques em botões, entrada de conteúdo, upload de arquivos, extração de informações e fluxos de trabalho de etapas múltiplas com base em instruções em linguagem natural. Essa abordagem reduz os custos de manutenção de scripts causados por mudanças na estrutura da página, sendo ideal para cenários como logins, submissões de formulários, operações de back-office e coleta de dados.

Quando um fluxo de automação encontra um desafio CAPTCHA, você pode chamar o SDK Python oficial do CapSolver fornecendo parâmetros como a URL da página atual, a Chave do Site e o tipo de CAPTCHA. Após o CapSolver concluir a tarefa, ele retorna um token de verificação correspondente. O programa, em seguida, usa o Playwright para escrever esse token nos campos de resposta da página atual, callbacks JavaScript ou solicitações de negócios. Assim que a verificação for bem-sucedida, o Skyvern pode continuar executando a tarefa original autorizada pelo usuário, como submeter o formulário, entrar na próxima página ou verificar os resultados finais.

1. Instalando Dependências

O Skyvern atualmente requer Python 3.11, 3.12 ou 3.13. Instale o Skyvern, o SDK do CapSolver e o Chromium:

pip install "skyvern[local]"
pip install --upgrade capsolver
python -m playwright install chromium

2. Código do CapSolver

# pip install --upgrade capsolver
# export CAPSOLVER_API_KEY='...'

import capsolver

# capsolver.api_key = "..."
solution = capsolver.solve({
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})

print(solution)

Ao sucesso, o resultado retornado principalmente usa:

token = solution["gRecaptchaResponse"]

O papel dos parâmetros:

websiteURL e websiteKey devem ser consistentes com a configuração real da página atual.

3. Exemplo de Integração com Skyvern

Abaixo está um exemplo mínimo de integração. O Skyvern primeiro abre a página e preenche o formulário, em seguida recupera o Token via SDK oficial, e finalmente retorna o Token para a página para submissão.

import asyncio
import capsolver
from skyvern import Skyvern


TARGET_URL = "https://www.google.com/recaptcha/api2/demo"
WEBSITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"


async def inject_token(page, token: str):
    await page.evaluate(
        """
        (token) => {
            const textarea = document.getElementById('g-recaptcha-response');
            if (textarea) {
                textarea.value = token;
            }
        }
        """,
        token,
    )


async def main():
    skyvern = Skyvern.local()
    browser = await skyvern.launch_local_browser(headless=False)
    page = await browser.get_working_page()

    try:
        await page.goto(TARGET_URL)
        solution = await asyncio.to_thread(
            capsolver.solve,
            {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": TARGET_URL,
                "websiteKey": WEBSITE_KEY,
            },
        )

        token = solution["gRecaptchaResponse"]
        await inject_token(page, token)

        await page.act("Submit")
        await page.validate("Verification successful... Great!")
    finally:
        await browser.close()

4. Como Retornar o Token para a Página

O CapSolver é responsável apenas por retornar o Token; ele não submete automaticamente o formulário de negócios do site-alvo. Diferentes sites tratam Tokens de formas variadas, com métodos comuns incluindo:

1. Escrever no campo oculto g-recaptcha-response;

2. Chamar um callback JavaScript configurado na página;

3. Submeter o Token como parâmetro de interface de negócios.

A função inject_token() no exemplo tenta tanto o campo oculto quanto um callback de teste. Na utilização real, esse trecho deve ser ajustado de acordo com a implementação do frontend do seu próprio site.

5. Problemas Comuns

Token retornado, mas a página ainda falha

Verifique os seguintes parâmetros:

• A websiteURL é o endereço da página atual?

• A websiteKey é da página atual?

• A página foi recarregada após obter o Token?

• O Token foi entregue ao callback ou interface de negócios correto?

6. Usando a API do CapSolver para Resolver ImageToText

Além do reCAPTCHA, o Skyvern também pode trabalhar com o CapSolver para lidar com CAPTCHAs padrão de imagem para texto. Tomando como exemplo o Demo CAPTCHA do BotDetect: o ID do elemento da imagem CAPTCHA é demoCaptcha_CaptchaImage, o ID da caixa de entrada do resultado é captchaCode e o ID do botão de validação é validateCaptchaButton.

A tarefa ImageToTextTask requer a conversão da imagem CAPTCHA para Base64 e a submissão via parâmetro body. Se o src da imagem for um URL de dados, por exemplo:

data:image/png;base64,iVBORw0KGgoAAA...

Ao passá-lo para o CapSolver, mantenha apenas o conteúdo Base64 após a vírgula, excluindo o prefixo data:image/...;base64,. Ao contrário das tarefas do tipo Token, a ImageToTextTask retorna diretamente o resultado da reconhecimento sem exigir a verificação adicional de getTaskResult.

Abaixo está o exemplo completo de integração com o Skyvern:

import asyncio

import capsolver
from skyvern import Skyvern


TARGET_URL = "https://captcha.com/demos/features/captcha-demo.aspx"


async def main():
    skyvern = Skyvern.local()
    browser = await skyvern.launch_local_browser(headless=False)
    page = await browser.get_working_page()

    try:
        await page.goto(TARGET_URL)
        await page.locator("#demoCaptcha_CaptchaImage").wait_for()

        # Leia a URL de dados da imagem CAPTCHA.
        image_src = await page.locator(
            "#demoCaptcha_CaptchaImage"
        ).get_attribute("src")

        if not image_src or "," not in image_src:
            raise RuntimeError("Uma imagem CAPTCHA em Base64 válida não foi encontrada")

        # Remova o prefixo da URL de dados e mantenha apenas os dados em Base64.
        base64_image = image_src.split(",", 1)[1]

        solution = await asyncio.to_thread(
            capsolver.solve,
            {
                "type": "ImageToTextTask",
                "websiteURL": TARGET_URL,
                "module": "common",
                "body": base64_image,
            },
        )

        captcha_text = solution["text"]
        print("Resultado da reconhecimento:", captcha_text)

        await page.locator("#captchaCode").fill(captcha_text)
        await page.locator("#validateCaptchaButton").click()
        await page.wait_for_timeout(5000)
    finally:
        await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

O processo de execução do código pode ser resumido como:

O Skyvern abre a página CAPTCHA
  -> Localiza #demoCaptcha_CaptchaImage
  -> Extrai e limpa os dados da imagem em Base64
  -> Chama capsolver.solve(ImageToTextTask)
  -> Lê solution["text"]
  -> Preenche em #captchaCode
  -> Clica em #validateCaptchaButton

Escolhendo o Modelo de Reconhecimento Correto

module é um parâmetro opcional; common pode ser usado por padrão. Se a CAPTCHA contiver apenas números, você pode usar number; para alguns estilos especiais, também pode selecionar o modelo correspondente independente de acordo com a documentação do CapSolver para melhorar a precisão do reconhecimento.

Por exemplo, ao reconhecer apenas CAPTCHAs numéricas, você pode alterar os parâmetros da tarefa para:

solution = capsolver.solve({
    "type": "ImageToTextTask",
    "module": "number",
    "images": [base64_image],
})

answers = solution["answers"]

O modelo number suporta a submissão de múltiplas imagens de uma vez, e images pode conter até 9 strings em Base64. Para outros nomes de modelo e tipos de imagem aplicáveis, consulte a Documentação Oficial da CapSolver ImageToTextTask.

7. Resumo

A escolha da solução técnica correta para automação de navegadores de inteligência artificial depende da complexidade da tarefa, da frequência das mudanças nas páginas e do mecanismo de verificação do site-alvo. Ferramentas tradicionais como Selenium e Playwright são adequadas para fluxos de automação com estruturas estáveis e caminhos de operação claros. O Skyvern constrói sobre isso, introduzindo modelos de visão e LLMs, tornando-o mais adequado para tarefas web onde as estruturas das páginas mudam frequentemente, exigem compreensão semântica ou envolvam operações de etapas múltiplas. Como o Skyvern controla o navegador com base no Playwright, ele pode completar navegação em páginas, preenchimento de formulários, cliques em botões e extração de dados por meio de linguagem natural. Quando o processo enfrenta um desafio CAPTCHA, os desenvolvedores podem combinar o SDK oficial do CapSolver para obter um Token de verificação e, em seguida, preencher o resultado de volta na página atual, permitindo que o Skyvern continue com operações subsequentes como submissão de formulários, transições de páginas e verificação de resultados. Combinando o Skyvern e o CapSolver, os desenvolvedores podem construir fluxos de automação de navegadores mais flexíveis, mantíveis e escaláveis, reduzindo os custos de manutenção de seletores tradicionais enquanto melhora a eficiência e a estabilidade da execução de tarefas complexas em sites. Definir claramente o escopo da autorização, proteger as chaves da API e verificar e registrar os resultados da automação são pré-requisitos importantes para a operação estável de projetos relacionados.

Referências

• GitHub do Skyvern

• Documentação Oficial do CapSolver reCAPTCHA

• Documentação Oficial da CapSolver ImageToTextTask

Resgate seu Código de Bônus do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código de bônus CAP26 ao recarregar sua conta do CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Perguntas Frequentes (FAQ)

Q1: Como lidar com CAPTCHAs dentro de iframes?
A1: Mude para o contexto do iframe primeiro usando page.frame_locator('iframe_selector') antes de injetar o token. Certifique-se de que a websiteURL enviada ao CapSolver seja a URL da página principal, não a URL do iframe.

Q2: E se o site usar um callback JavaScript personalizado?
A2: Identifique o nome da função de callback (ex.: onCaptchaResolved) e execute-a via Playwright: await page.evaluate("onCaptchaResolved(token)", token).

Q3: Como melhorar as taxas de reconhecimento do ImageToText?
A3: Use parâmetros module específicos (como number para CAPTCHAs numéricos) e certifique-se de que a imagem em Base64 extraída esteja clara e de alta resolução.

Q4: Como lidar com a segurança da chave da API?
A4: Nunca codifique sua chave da API. Use variáveis de ambiente (ex.: os.getenv("CAPSOLVER_API_KEY")) para carregá-la de forma segura.

Q5: Devo implementar um mecanismo de repetição?
A5: Sim, use bibliotecas como tenacity para implementar repetições com backoff exponencial para capsolver.solve() para lidar com problemas temporários de rede ou serviço.

Q6: O que acontece com a expiração do Token?
A6: Tokens CAPTCHA expiram rapidamente (ex.: 2 minutos). Injete e submeta o token imediatamente após recebê-lo do CapSolver.

Q7: O Skyvern pode rotear automaticamente diferentes tipos de CAPTCHA?
A7: Sim, você pode usar as capacidades de visão do Skyvern para identificar o tipo de CAPTCHA primeiro, em seguida, construir dinamicamente o payload apropriado do CapSolver (ex.: alternar entre ReCaptchaV2TaskProxyLess e ImageToTextTask).

Q8: Como a visão do Skyvern ajuda de outra forma?
A8: Ela permite localização dinâmica de elementos (encontrar CAPTCHAs sem IDs fixos), validação visual após a submissão (verificar mensagens de sucesso) e detecção visual de erros para tentativas mais inteligentes.