Documentação da API
Três endpoints, exemplos de código completos em seis linguagens. Integre em menos de 60 segundos com o cluster de solucionadores de alto desempenho da Capzy.
Início rápido
POST /createTaskEnvie o tipo de captcha + os parâmetros do site. Receba um taskId de volta instantaneamente.
POST /getTaskResultConsulte a cada ~1s até o status ser ready. O token chega no objeto solution.
POST /getBalanceConfira os créditos restantes. Resoluções com falha são reembolsadas aqui automaticamente.
https://api.capzy.aiautenticação via clientKey no corpo da requisiçãoEndpoints
/createTaskCriar uma nova tarefa de resolução de captcha{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResultConsultar o resultado da tarefa{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalanceVerificar o saldo da conta{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/reportScoreOpcional: informe de volta o score verificado pelo Google para tarefas V3. Alimenta a visualização de qualidade V3 do seu painel. Um relatório por tarefa; os relatórios devem chegar em até 24 horas após a conclusão da resolução.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/reportCorrectCaptchaOpcional: informe que a resolução foi ACEITA pelo site de destino. Especialmente útil para tipos que retornam coordenadas (por exemplo, o slider da Shopee), em que retornamos uma posição e o seu próprio navegador realiza o arraste. Este relatório é nosso único sinal de precisão no mundo real. Um relatório por tarefa, em até 24 horas; nunca afeta o preço.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/reportIncorrectCaptchaOpcional: informe que a resolução foi REJEITADA pelo site de destino. Alimenta o mesmo acompanhamento de precisão no mundo real que /reportCorrectCaptcha. Um relatório por tarefa, em até 24 horas; nunca afeta o preço.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }Tipos de tarefa suportados
Carregando…Lista ao vivo dos tipos de tarefa habilitados no momento, agrupados por provedor de captcha. Preços e tempo médio de resolução são atualizados automaticamente pela telemetria do cluster.
Limites de taxa
Os limites são aplicados por conta, somando todas as chaves de API que você possui. Ultrapassar o limite retorna um código de erro sem consumir créditos.
Toda conta nova começa aqui
Abra um ticket de suporte informando o volume esperado (sem nível de preço separado, mesmo valor por resolução)
tarefas simultâneasQuantas tarefas você pode ter na fila de resolução ao mesmo tempo. Uma tarefa conta para o seu limite desde o createTask até terminar (sucesso, falha ou timeout).
limite de taxaQuantas chamadas createTask você pode fazer por segundo. Janela deslizante, aplicada por conta. Exceder a taxa retorna ERROR_RATE_LIMITED sem débito de créditos.
Códigos de erro
Todos os erros retornados por /createTask / /getTaskResult, com a correção. Resoluções com falha são reembolsadas automaticamente: os créditos voltam ao seu saldo imediatamente.
Autenticação
Problemas com sua chave de API ou seu IP.- #
ERROR_KEY_DOES_NOT_EXISTSua chave de API não foi reconhecida.
correçãoConfira o valor em Painel → Chaves de API. As chaves começam com `capzy_`. Chaves rotacionadas são invalidadas imediatamente.
- #
ERROR_IP_NOT_ALLOWEDO IP da sua requisição não está na lista de permissões da chave de API.
correçãoAdicione seu IP à lista de permissões da chave em Painel → Chaves de API ou remova a lista de permissões por completo se você não precisar fixar IPs.
- #
ERROR_IP_BLOCKEDSeu IP está temporariamente banido por enviar requisições inválidas demais.
correçãoBanimos IPs que enviam mais de 100 requisições inválidas em 10 minutos (de forma progressiva). Corrija o bug que causa as requisições inválidas e aguarde. Os banimentos expiram automaticamente em 1 minuto a 24 horas, dependendo do nível.
Validação
Parâmetros de tarefa inválidos ou tipo incorreto para a sitekey.- #
ERROR_INVALID_PARAMSO corpo da requisição estava malformado ou sem campos obrigatórios.
correçãoVerifique se `clientKey` está no nível superior e se `task` contém `type` mais o identificador obrigatório (websiteURL/websiteKey/captchaId/etc). Consulte a seção Tipos de tarefa para ver os parâmetros obrigatórios de cada tipo.
- #
ERROR_BAD_SITEKEYO `websiteKey` não está registrado em nenhum provedor de captcha que conseguimos identificar.
correçãoCertifique-se de copiar a sitekey completa da página de destino (procure `data-sitekey`, `sitekey:` ou o parâmetro em `grecaptcha.render` / `hcaptcha.render`).
- #
ERROR_TASK_NOT_SUPPORTEDO `type` de tarefa que você enviou não é um tipo de captcha que a Capzy suporta atualmente.
correçãoConsulte a seção Tipos de tarefa abaixo para ver a lista completa de tipos habilitados. Se você precisa de um captcha que não está na lista, abra um ticket e daremos prioridade a ele.
- #
ERROR_WRONG_TASK_TYPEO tipo de tarefa não corresponde ao provedor real da sitekey.
correçãoVerificamos previamente as sitekeys junto ao provedor real. A resposta de erro inclui um campo `recommended`: mude para esse tipo de tarefa. (Nenhum crédito é cobrado.)
- #
ERROR_PROXY_REQUIREDEste captcha é vinculado ao IP: seus tokens ficam atrelados ao IP que os resolveu.
correçãoMude para a variante `*Task` (em vez de `*TaskProxyLess`) e informe um `proxyAddress` correspondente ao IP que você usará para enviar o token. Afeta: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.
- #
ERROR_NO_PROXYOs campos de proxy são obrigatórios para este tipo de tarefa, mas não foram informados.
correçãoInclua `proxyType`, `proxyAddress`, `proxyPort` (e, opcionalmente, `proxyLogin`/`proxyPassword`/`userAgent`) no corpo da tarefa.
- #
ERROR_PROXY_CONNECT_REFUSEDO proxy informado recusou a conexão.
correçãoVerifique as credenciais do proxy, se o host está acessível e se o IP está ativo. Teste o mesmo proxy na sua própria máquina primeiro para isolar problemas do provedor.
Limites de taxa
Limites de simultaneidade / por segundo / de taxa de reembolso.- #
ERROR_MAX_TASKS_REACHEDVocê atingiu o limite de tarefas simultâneas do nível da sua conta.
correçãoAguarde a conclusão das tarefas em andamento antes de enviar mais. O nível Regular padrão é de 30 simultâneas; entre em contato com o suporte para fazer upgrade.
- #
ERROR_RATE_LIMITEDVocê está enviando /createTask mais rápido do que seu limite de taxa permite.
correçãoDiminua o ritmo e tente novamente. O nível Regular padrão é de 30 req/s em janela deslizante. Exceder a taxa não consome créditos.
- #
ERROR_NO_SLOT_AVAILABLEA capacidade do cluster está temporariamente saturada.
correçãoTente novamente após alguns segundos (é temporário). Se persistir por minutos, confira status.capzy.ai.
- #
ERROR_SYSTEM_MAINTENANCEA Capzy está em manutenção programada.
correçãoTente novamente após a janela de manutenção. Publicamos avisos antecipados na página de status.
Resultados da resolução
O que o solucionador retornou. Resoluções com falha são reembolsadas automaticamente.- #
ERROR_TIMEOUTA tarefa não foi concluída dentro do tempo limite do seu tipo.
correçãoReembolsado automaticamente, sem cobrança. A maioria dos timeouts é temporária. Se um captcha específico estourar o tempo com frequência, abra um ticket com o UUID da tarefa.
- #
ERROR_CAPTCHA_UNSOLVABLEO solucionador esgotou suas tentativas neste desafio.
correçãoReembolsado automaticamente, sem cobrança. Causas comuns: sitekey desatualizada, websiteURL não corresponde ao domínio onde o captcha está incorporado ou o captcha foi desativado pelo site de destino.
- #
ERROR_NULL_RESULTO solucionador terminou, mas não retornou nenhum token.
correçãoReembolsado automaticamente. Geralmente indica que o site de destino removeu o captcha durante a resolução. Tente novamente; se persistir, abra um ticket.
- #
ERROR_INTERNALErro inesperado no pipeline de resolução.
correçãoReembolsado automaticamente. Tente novamente (esses erros são raros). Se eles aparecerem em sequência, abra um ticket com o UUID da tarefa.
- #
ERROR_ZERO_BALANCEO saldo da conta é insuficiente para cobrir o custo da tarefa.
correçãoAdicione créditos em Painel → Faturamento. Resoluções com falha são reembolsadas automaticamente, então você só paga por tokens bem-sucedidos.
Relatório de score
Erros específicos de /reportScore (feedback de qualidade V3).- #
ERROR_TASK_NOT_FOUND/reportScore: o taskId não pertence à sua conta ou foi expurgado.
correçãoOs relatórios de score devem referenciar uma tarefa sua e ser enviados em até 24h após a conclusão da resolução.
- #
ERROR_TASK_NOT_READY/reportScore: a tarefa ainda está em processamento ou já falhou.
correçãoSomente tarefas `ready` podem receber score. Aguarde /getTaskResult retornar ready antes de enviar o relatório.
- #
ERROR_REPORT_TOO_LATE/reportScore: mais de 24h se passaram desde a conclusão da resolução.
correçãoEnvie os scores poucos minutos após sua chamada de siteverify. É quando os dados são mais úteis para nosso painel de qualidade V3.
Playground de código
Exemplos completos e funcionais nas principais linguagens. Copie, cole sua chave de API e execute.
import requests, time
API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"
# Create task
task = requests.post(f"{API}/createTask", json={
"clientKey": KEY,
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}).json()
task_id = task["taskId"]
# Poll for result
while True:
result = requests.post(f"{API}/getTaskResult", json={
"clientKey": KEY,
"taskId": task_id
}).json()
if result["status"] == "ready":
token = result["solution"]["token"]
print(f"Solved: {token[:50]}...")
break
elif result["status"] == "failed":
print(f"Failed: {result.get('errorDescription')}")
break
time.sleep(1)Integre em menos de 60 segundos.
$0.10 em créditos grátis ao criar sua conta. Não é necessário cartão de crédito.
Obtenha sua chave de API grátis →