Pular para o conteúdo

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

passo 1
POST /createTask

Envie o tipo de captcha + os parâmetros do site. Receba um taskId de volta instantaneamente.

passo 2
POST /getTaskResult

Consulte a cada ~1s até o status ser ready. O token chega no objeto solution.

passo 3
POST /getBalance

Confira os créditos restantes. Resoluções com falha são reembolsadas aqui automaticamente.

url basehttps://api.capzy.aiautenticação via clientKey no corpo da requisição

Endpoints

POST/createTaskCriar uma nova tarefa de resolução de captcha
requisição
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
resposta
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultConsultar o resultado da tarefa
requisição
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
resposta
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceVerificar o saldo da conta
requisição
{ "clientKey": "capzy_..." }
resposta
{ "errorId": 0, "balance": 9.50 }
POST/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.
requisição
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
resposta
{ "errorId": 0 }
POST/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.
requisição
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
resposta
{ "errorId": 0 }
POST/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.
requisição
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
resposta
{ "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.

Carregando tipos de tarefa…

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.

Padrão
30 simultâneas · 30 req/s

Toda conta nova começa aqui

Concorrência maior
300+ simultâneas · 100+ req/s

Abra um ticket de suporte informando o volume esperado (sem nível de preço separado, mesmo valor por resolução)

tarefas simultâneas

Quantas 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 taxa

Quantas 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_EXIST

    Sua 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_ALLOWED

    O 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_BLOCKED

    Seu 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_PARAMS

    O 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_SITEKEY

    O `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_SUPPORTED

    O `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_TYPE

    O 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_REQUIRED

    Este 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_PROXY

    Os 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_REFUSED

    O 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_REACHED

    Você 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_LIMITED

    Você 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_AVAILABLE

    A 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_MAINTENANCE

    A 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_TIMEOUT

    A 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_UNSOLVABLE

    O 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_RESULT

    O 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_INTERNAL

    Erro 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_BALANCE

    O 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.

    #
06

Playground de código

Exemplos completos e funcionais nas principais linguagens. Copie, cole sua chave de API e execute.

solve.py
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)
Prévia da saídaSucesso (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

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 →