Introdução e início rápido

1. Apresentando o SDK CapSolver Python

O SDK é fornecido como três pacotes independentes — cada um instalável por conta própria via pip install — além de um repositório de exemplos complementar. Juntos, eles permitem que você passe de “há um CAPTCHA na página” para “Eu tenho um token válido” em apenas algumas linhas de Python - esteja você escrevendo um script único, dirigindo um navegador real com o Playwright ou conectando a capacidade de resolução a um agente de IA autônomo.

É alimentado pelo serviço de resolução de IA da CapSolver. O SDK cuida de tudo do seu lado – detectando o CAPTCHA, montando os parâmetros, chamando o serviço e preenchendo o resultado novamente – enquanto o reconhecimento e a solução reais acontecem na nuvem. A ideia central se resume a uma única frase: seu código (ou seu modelo) decide o que fazer, e o CapSolver cuida de resolvê-lo.

1.1 Recursos principais

• ✅ Resolução de tokens com tecnologia de IA — CapSolver retorna um token que você envia ao site de destino.
• ✅ Dois modos de uso — API pura (modo Token, para chaves de site conhecidas, sem necessidade de navegador) e modo Navegador baseado em Playwright.
• ✅ Cobertura dos principais CAPTCHAs — reCAPTCHA v2/v3 (incluindo Enterprise) e Cloudflare Turnstile.
• ✅ API totalmente assíncrona — construída em async / await , uma opção natural para rastreadores e agentes modernos.
• ✅ Pacotes de três camadas — desde o mecanismo de baixo nível até ferramentas de agente e um serviço MCP; escolha o que você precisa (veja 1.2).
• ✅ CLIs agrupadas — capsolver , capsolver-agent e capsolver-mcp permitem executar diagnósticos sem escrever nenhum código.

1.2 CAPTCHAs e parâmetros suportados

O SDK atualmente resolve os seguintes tipos de CAPTCHA:

Os parâmetros principais exigidos por cada tipo são website_url + website_key . O reCAPTCHA v3 também pode receber page_action , min_score e uma dica enterprise , enquanto o Cloudflare pode receber cdata . Você pode inspecionar os tipos suportados pela sua compilação atual a qualquer momento:

cap = create_capsolver(api_key="YOUR_API_KEY")
print(cap.get_supported_captchas())

Observação: No modo Navegador, você não precisa fornecer esses parâmetros manualmente — get_captcha_info(page) lê o tipo e a chave do site diretamente da página ativa para você.

2. Capacidades principais (SDK)

2.1 Os Três Pacotes

O conjunto completo de recursos mais um repositório de exemplos. Esses não são três pares para escolher — os dois últimos são construídos sobre capsolver-core , simplesmente entregando a mesma capacidade de solução por meio de uma interface diferente. Escolha aquele que melhor corresponde à sua forma de trabalhar.

** capsolver-core — O SDK principal (mecanismo)**

O pacote de nível mais baixo e o mecanismo compartilhado do qual os outros dois dependem. Ele divide a solução de um CAPTCHA em quatro etapas – detectar → ler parâmetros → resolver → preencher – e oferece dois níveis de granularidade: quando a chave do site é conhecida, vá para API pura (modo Token, sem navegador); quando você tiver apenas a página, deixe o Playwright detectar automaticamente e preencher o resultado novamente. Totalmente assíncrono, com um registro de manipulador conectável.

• Melhor para: scripts, rastreadores e automação onde você controla o código e não precisa de um LLM.
• Pontos de entrada: create_capsolver() → solve() / solve_on_page() .
• Instalar: pip install capsolver-core (adicione [playwright] para o modo Navegador).

** capsolver-agent — Ferramentas do agente**

Envolve o núcleo como ferramentas que um LLM pode chamar: ele fornece esquemas de ferramentas independentes de estrutura, além de um executor assíncrono, bem como implementações prontas de LangChain BaseTool. Dentro de seu loop, o modelo chama “resolver” da mesma forma que chama “click” ou “type”, e o executor retransmite essa chamada para os métodos do núcleo e retorna um resultado estruturado.

• Melhor para: deixar o modelo decidir quando resolver — chamada de função OpenAI, SDK de agentes OpenAI, LangChain, uso de navegador ou qualquer loop de agente personalizado.
• Pontos de entrada: get_all_tools() + create_executor() ou get_langchain_tools() .
• Instalar: pip install capsolver-agent (adicionar [langchain] para LangChain).

** capsolver-mcp — Serviço MCP**

Expõe o mesmo conjunto de ferramentas que um serviço padrão por meio do Model Context Protocol. Qualquer cliente compatível com MCP descobre essas ferramentas automaticamente na conexão — não é necessário nenhum código de adaptador por cliente. Suporta três transportes: stdio, SSE e streamable-http.

• Melhor para: uso plug-and-play dentro de um cliente de IA — Claude Desktop, Claude Code, Cursor, Windsurf, Cline e muito mais, com quase nenhum código de integração.
• Pontos de entrada: o comando capsolver-mcp ou create_server() .
• Instalar: pip install capsolver-mcp (adicione [browser] para as ferramentas do navegador).

2.2 Casos de uso

Sempre que um CAPTCHA bloqueia a próxima etapa, este SDK ganha seu lugar. Alguns cenários típicos:

Web scraping/coleta de dados

Um rastreador atinge um reCAPTCHA ou Turnstile em uma página de listagem, página de pesquisa ou parede de login, e todo o pipeline de coleta para. Use o modo Token para obter um token e enviá-lo com sua solicitação ou use o modo Navegador para preenchê-lo diretamente na página – de qualquer forma, a extração continua. → Recomendado: capsolver-core (Modo token quando a chave do site é conhecida; solve_on_page para páginas dinâmicas).

Automação de conta e fluxo de trabalho

Fluxos de várias etapas, como inscrição, login, redefinição de senha e checkout, geralmente geram um CAPTCHA em uma etapa específica, congelando todo o script. Coloque a solução exatamente nessa etapa – depois que o token é preenchido, o script continua enviando o formulário, aguarda o redirecionamento e executa as etapas restantes até a conclusão. → Recomendado: capsolver-core Modo navegador; especialmente suave quando seu roteiro já dirige o Playwright.

Agentes de IA (navegação autônoma)

Dê a um agente uma tarefa como “faça login e receba os pedidos”, e ele atingirá um CAPTCHA em algum lugar ao longo do caminho sem aviso prévio. Em vez de fazer com que o modelo clique em si mesmo - a segmentação com pixels perfeitos e os caminhos do cursor semelhantes aos humanos são difíceis de falsificar mecanismos de risco anteriores, e os loops de novas tentativas de imagem inundam a janela de contexto - registre uma ação de “solução” para ele: quando atinge um CAPTCHA, ele chama a ação, recebe um token de volta e continua na mesma sessão do navegador sem interromper o fluxo. → Recomendado: capsolver-agent (deixe o modelo chamá-lo sozinho) ou capsolver-mcp (use-o diretamente dentro de um cliente de IA).

Testes automatizados/ferramentas internas

Testes ponta a ponta e ferramentas de operações internas precisam limpar as etapas do CAPTCHA em seus próprios sites ou em sites de terceiros de maneira confiável, sem intervenção manual que atrase as coisas. → Recomendado: escolha por ambiente — capsolver-core (em código) ou capsolver-mcp (em um cliente).

Resumindo: em qualquer lugar que você precise limpar um CAPTCHA programaticamente em Python, este SDK está ao alcance.

3. Instalação e configuração da chave API

Antes de começar, tenha uma coisa em mente: a solução real acontece no serviço de nuvem do CapSolver – o SDK apenas a chama do seu lado. Portanto, o primeiro passo não é instalar um pacote; é ter uma conta e uma chave de API. A configuração consiste em três etapas, na ordem: registrar-se e obter uma chave → instalar o SDK → conectar a chave.

3.1 Registre-se e obtenha sua chave API

1. Registre uma conta no site CapSolver.
2. Abra o painel e copie sua chave API.
3. Adicione fundos à sua conta – cada solução bem-sucedida consome saldo e a resolução falhará quando o saldo chegar a zero.

3.2 Instale o SDK

Os três pacotes estão atualmente hospedados como código aberto no GitHub e ainda não foram publicados no PyPI, então instale-os via git. capsolver-core é o mecanismo, e tanto capsolver-agent quanto capsolver-mcp dependem dele - então core é sempre necessário. Adicione a camada superior que você pretende usar:

# Engine (required; both other packages depend on it)
pip install git+https://github.com/capsolver-ai/capsolver-core.git
 
# Optional: MCP service — exposes the tools to MCP clients
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git
 
# Optional: Agent tools — LLM-callable tool definitions + LangChain tools
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

Para o modo Navegador (detectando CAPTCHAs em uma página real e preenchendo o token novamente), adicione o extra [playwright] e instale o Chromium:

pip install "capsolver-core[playwright] @ git+https://github.com/capsolver-ai/capsolver-core.git"
playwright install chromium

Nota: detect e solve_on_page requerem o navegador extra; O modo token não precisa de nenhum navegador.

Os três repositórios são:

Você também pode clonar um repositório localmente antes de instalar – útil para ler o código-fonte ou fazer seu próprio desenvolvimento:

git clone https://github.com/capsolver-ai/capsolver-core.git
cd capsolver-core
pip install .            # or: pip install -e .  for an editable install

3.3 Conecte sua chave de API

Por fim, entregue a chave da etapa 3.1 ao SDK. Por padrão, todos os pacotes o leem da variável de ambiente CAPSOLVER_API_KEY:

# bash / zsh
export CAPSOLVER_API_KEY="your-capsolver-api-key"
 
# PowerShell
$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
 
# cmd
set CAPSOLVER_API_KEY=your-capsolver-api-key

Alternativamente, ignore a variável de ambiente e passe api_key="..." diretamente para create_capsolver() .

4. Sua primeira solução

Com o ambiente pronto, vamos rodar de ponta a ponta com o menor código possível. O caminho a seguir depende se você já conhece a chave do site: se souber, use o modo Token; se tudo o que você tem é um URL de página, use o modo Navegador.

4.1 Modo Token (você já conhece a chave do site)

Quando você conhece o tipo de CAPTCHA, o URL da página e a chave do site, nenhum navegador é necessário – entregue os parâmetros e receba um token de volta.

import asyncio
from capsolver_core import create_capsolver, CaptchaType, CaptchaInfo
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    info = CaptchaInfo(
        type=CaptchaType.RECAPTCHA_V2,
        website_url="https://example.com",
        website_key="6Lc...",
    )
    solution = await cap.solve(info)
    print(solution.token)  # submit as g-recaptcha-response
 
asyncio.run(main())

4.2 Modo Navegador (uma chamada, direto na página ao vivo)

Se tudo o que você tem é uma página – e você prefere não procurar a chave do site sozinho – deixe o SDK detectar automaticamente cada CAPTCHA na página, resolvê-los um por um e preencher os tokens de volta no DOM. Uma chamada faz tudo.

import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright
 
async def main():
    cap = create_capsolver(api_key="YOUR_API_KEY")
 
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto("https://example.com/login")
 
        results = await cap.solve_on_page(page)
        for r in results:
            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
 
asyncio.run(main())