O **SDK Python oficial da CaptchaSonic** transforma cada CAPTCHA suportado em uma única chamada de função. Ele traz um cliente síncrono (`CaptchaSonic`) e um assíncrono (`AsyncCaptchaSonic`), se comunica com a nossa infraestrutura via **gRPC por padrão** (com transporte HTTP opcional) e inclui type hints completos, novas tentativas automáticas para erros transitórios e polling integrado para desafios do tipo token.

---

## Instalação

```bash
pip install captchasonic
```

O transporte gRPC é instalado por padrão. Para usar também o transporte opcional HTTP/JSON, instale o extra:

```bash
pip install "captchasonic[http]"
```

> [!TIP]
> O SDK oferece suporte ao **Python 3.10, 3.11, 3.12 e 3.13** e é publicado sob a licença MIT.

---

## Autenticação

Você precisa de uma API key da CaptchaSonic. Crie uma conta e obtenha a sua chave no [dashboard](/app), depois adicione saldo em [Adicionar fundos](/docs/guides/add-funds).

Passe a chave como primeiro argumento posicional para o cliente:

<Snippet sdk="python" region="authConstruct" />

> [!WARNING]
> Trate a sua API key como uma senha. Mantenha-a fora do controle de versão — carregue-a de uma variável de ambiente ou de um gerenciador de segredos, em vez de deixá-la fixa no código.

<Snippet sdk="python" region="authEnvVar" />

---

## Início rápido

A maioria dos CAPTCHAs do tipo token (reCAPTCHA, Turnstile, hCaptcha) é resolvida com uma única chamada. O cliente faz o polling por você e retorna o token assim que a tarefa estiver pronta.

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveRecaptchaV2Token_quickstart" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveRecaptchaV2Token" />

  </LangTabs.Tab>
</LangTabs>

> Retorna o token do reCAPTCHA — envie-o como `g-recaptcha-response` da página.

Os métodos de token fazem polling por até 120 segundos por padrão antes de expirar (veja [Configuração](#configuration)).

---

## Tipos de CAPTCHA suportados

O SDK divide os métodos em duas famílias:

- **Métodos de token** (`*_token`, `solve_turnstile`, `solve_cloudflare`) — você fornece `website_url` / `website_key`, o SDK faz o polling na nossa infraestrutura e retorna um `result["token"]` pronto para envio.
- **Métodos de imagem / interativos** — você fornece as imagens do desafio, e o SDK retorna um `result["typed_solution"]` descrevendo o que clicar, arrastar ou digitar.

Todos os argumentos de imagem aceitam o tipo flexível `ImageInput` — um caminho de arquivo (`str`), um `pathlib.Path`, `bytes` brutos ou um objeto de arquivo binário aberto.

<Snippet sdk="python" region="imageInputTypes" />

### reCAPTCHA v2 (token)

<MethodRef name="solve_recaptcha_v2_token" lang="python" />

<Snippet sdk="python" region="solveRecaptchaV2Token" />

> Retorna `result["token"]` — envie-o como `g-recaptcha-response` da página.

### reCAPTCHA v3 (token)

<Snippet sdk="python" region="solveRecaptchaV3Token" />

> Retorna `result["token"]` — envie-o como `g-recaptcha-response` da página.

### reCAPTCHA v2 (grade de imagens)

Quando você já tem os blocos do desafio, resolva a grade diretamente e receba os índices a clicar.

<Snippet sdk="python" region="solveRecaptchaV2" />

> Retorna `result["typed_solution"]["grid"]["objects"]` — a lista de índices dos blocos a clicar.

### Cloudflare Turnstile

<MethodRef name="solve_turnstile" lang="python" />

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveTurnstile" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveTurnstile" />

  </LangTabs.Tab>
</LangTabs>

> Retorna o token do Turnstile — envie-o como `cf-turnstile-response` do formulário.

<TaskTypeRef captcha="cloudflare-turnstile" />

### Desafio Cloudflare

O desafio completo do Cloudflare **exige** um proxy.

<Snippet sdk="python" region="solveCloudflare" />

> Retorna `result["token"]` — o token de liberação para a requisição protegida.

### CAPTCHA popular (desafios de imagem estilo hCaptcha)

`solve_popular_captcha` trata as variantes interativas com imagens; `solve_popular_captcha_token` retorna um token diretamente.

<Snippet sdk="python" region="solvePopularCaptcha" />

> A variante de imagem retorna `result["typed_solution"]["grid"]["objects"]` (índices dos blocos a clicar); a variante de token retorna `result["token"]`.

### GeeTest

<Snippet sdk="python" region="solveGeetest" />

> Retorna `result["typed_solution"]` — a ação a executar, cuja forma depende de `geetest_type`.

### AWS WAF

<Snippet sdk="python" region="solveAwsWaf" />

> Retorna `result["typed_solution"]["grid"]["objects"]` — a lista de índices dos blocos a clicar.

### Imagem para texto (OCR)

<Snippet sdk="python" region="solveOcr" />

> Retorna `result["typed_solution"]["text"]["texts"][0]` — o texto reconhecido a ser digitado.

### Quebra-cabeça deslizante

Envie o fundo e a peça do quebra-cabeça; você recebe de volta o deslocamento horizontal em pixels para deslizar.

<Snippet sdk="python" region="solveSlideImage" />

> Retorna `result["typed_solution"]["slide"]["x"]` — o deslocamento horizontal em pixels para arrastar a peça.

### TikTok

<Snippet sdk="python" region="solveTikTok" />

> Retorna `result["typed_solution"]` — a ação a executar, cuja forma depende de `type`.

### Binance

<Snippet sdk="python" region="solveBinance" />

> Retorna `result["typed_solution"]` — a ação a executar, cuja forma depende de `type`.

---

## Uso assíncrono

Para cargas de trabalho com alta concorrência (handlers FastAPI, spiders Scrapy, pipelines asyncio), use `AsyncCaptchaSonic`. Ele espelha exatamente a API síncrona, mas todos os métodos de resolução são aguardáveis (awaitable). Use-o como gerenciador de contexto assíncrono para que o canal subjacente seja limpo automaticamente.

<Snippet sdk="python" region="asyncUsage" />

O cliente síncrono também suporta o protocolo de gerenciador de contexto:

<Snippet sdk="python" region="syncContextManager" />

---

## Suporte a proxy

Os métodos de token aceitam um argumento opcional `proxy` (obrigatório para `solve_cloudflare`). Use uma URL de proxy padrão:

<Snippet sdk="python" region="proxyUsage" />

> [!TIP]
> Fornecer um proxy permite que o nosso solver espelhe a localização geográfica e a reputação de IP da sua requisição, o que melhora as taxas de sucesso em sites com regras anti-bot rigorosas.

---

## Configuração

Todas as opções são passadas ao construtor do cliente e valem tanto para o cliente síncrono quanto para o assíncrono.

<Snippet sdk="python" region="clientConfiguration" />

| Opção | Padrão | Descrição |
| :--- | :--- | :--- |
| `transport` | `"grpc"` | Protocolo de transporte. `"grpc"` envia imagens sem overhead de base64; `"http"` (requer o extra `[http]`) envia REST/JSON com imagens codificadas em base64. |
| `url` | `api.captchasonic.com:443` | Substitui o endpoint da API (ex.: para instalações próprias ou staging). |
| `timeout` | `30.0` | Timeout de rede por chamada, em segundos. |
| `polling_interval` | `2.0` | Segundos entre consultas enquanto aguarda uma tarefa de token. |
| `polling_timeout` | `120.0` | Tempo máximo, em segundos, para aguardar uma tarefa de token antes de lançar erro. |
| `secure` | `True` | Usa TLS no canal gRPC. |

Erros transitórios de gRPC são repetidos automaticamente (até 3 tentativas) com backoff exponencial, então você só precisa tratar erros de negócio reais.

---

## Tratamento de erros

Todos os erros do SDK herdam de `SonicError`, então você pode capturar tudo com uma única cláusula `except` ou tratar uma subclasse específica. Cada erro também carrega um `error_id` numérico.

<Snippet sdk="python" region="errorHandling" />

<ErrorIdTable />

---

## Funções auxiliares da conta

<Snippet sdk="python" region="accountHelpers" />

Use `health_check()` como uma sonda de prontidão leve em serviços e `get_balance()` para validar jobs antes de começar a gastar créditos.

---

## Solução de problemas

> [!TIP]
> **`ModuleNotFoundError` ao usar o transporte HTTP.** O cliente HTTP depende do `httpx`, que é um extra opcional. Instale com `pip install "captchasonic[http]"` e defina `transport="http"`.

- **Uma tarefa de token gera erro após ~120 segundos.** Esse é o `polling_timeout`. Aumente-o para alvos lentos, ex.: `CaptchaSonic(key, polling_timeout=240.0)`.
- **`solve_cloudflare` falha imediatamente.** O argumento `proxy` é obrigatório para o desafio Cloudflare — forneça uma URL de proxy funcional.
- **Erros de conexão gRPC atrás de proxy corporativo/firewall.** O gRPC precisa de HTTP/2 na porta 443. Se a sua rede bloquear isso, mude para `transport="http"`.
- **Métodos de imagem retornam índices, não um token.** Os métodos interativos (`solve_recaptcha_v2`, `solve_popular_captcha`, `solve_aws_waf`, `solve_geetest`, etc.) retornam `result["typed_solution"]` descrevendo a ação a executar; apenas `*_token`, `solve_turnstile` e `solve_cloudflare` retornam `result["token"]`.

---

## Recursos

- [Pacote no PyPI](https://pypi.org/project/captchasonic/)
- [Referência da API REST](/docs/api)
