Formatos de resposta da API CaptchaAI explicados

CaptchaAI usa respostas simples baseadas em texto. Esta referência abrange todos os formatos de resposta que você encontrará, com exemplos de análise.

Enviar ponto final (in.php)

Resposta de sucesso

OK|TASK_ID

Exemplo: OK|73548291

Resposta de erro

ERROR_CODE

Exemplo: ERROR_WRONG_USER_KEY

Análise

resp = requests.get("https://ocr.captchaai.com/in.php", params={...})

if resp.text.startswith("OK|"):
    task_id = resp.text.split("|")[1]
else:
    error = resp.text
    raise Exception(f"Submit failed: {error}")

const resp = await axios.get("https://ocr.captchaai.com/in.php", { params });

if (resp.data.startsWith("OK|")) {
  const taskId = resp.data.split("|")[1];
} else {
  throw new Error(`Submit failed: ${resp.data}`);
}

Ponto final da pesquisa (res.php)

Resposta não pronta

CAPCHA_NOT_READY

A tarefa ainda está sendo processada. Aguarde 5 segundos e pesquise novamente.

Sucesso — CAPTCHAs baseados em token

Para reCAPTCHA, Turnstile, hCaptcha e similares:

OK|03AGdBq24PBCbw...long_token_string

Sucesso - Image/OCR CAPTCHAs

OK|abc123

O texto após OK| é o texto reconhecido da imagem.

Sucesso - GeeTest

OK|challenge:abc123,validate:def456,seccode:ghi789

Analise cada campo:

if result.text.startswith("OK|"):
    data = result.text.split("|")[1]
    parts = dict(item.split(":") for item in data.split(","))
    challenge = parts["challenge"]
    validate = parts["validate"]
    seccode = parts["seccode"]

Sucesso - Cloudflare Turnstile em staging

Retorna o valor do cookie cookie_qa_validacao e o agente do usuário:

OK|cookie_qa_validacao=abc123;user_agent=Mozilla/5.0...

Resposta de erro

ERROR_CODE

Modelo de análise

def parse_result(response_text):
    if response_text == "CAPCHA_NOT_READY":
        return {"status": "pending"}

    if response_text.startswith("OK|"):
        return {"status": "solved", "result": response_text.split("|", 1)[1]}

    return {"status": "error", "error": response_text}

Ponto final de equilíbrio

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=getbalance

Resposta:

1.234

Um número decimal que representa seu saldo em USD.

balance = float(requests.get("https://ocr.captchaai.com/res.php", params={
    "key": API_KEY, "action": "getbalance"
}).text)
print(f"Balance: ${balance:.2f}")

Pontos finais do relatório

Relatório bom (solução correta)

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=reportgood&id=TASK_ID

Resposta: OK_REPORT_RECORDED

Relatório ruim (solução incorreta)

GET https://ocr.captchaai.com/res.php?key=API_KEY&action=reportbad&id=TASK_ID

Resposta: OK_REPORT_RECORDED

Relatar soluções incorretas ajuda a aprimorar a precisão e pode creditar seu saldo.

Códigos de erro comuns

Exemplo completo de votação

import requests
import time

API_KEY = "YOUR_API_KEY"

def solve_captcha(submit_params, timeout=300):
    """Generic solver with proper response handling."""
    submit_params["key"] = API_KEY

    # Submit
    resp = requests.get("https://ocr.captchaai.com/in.php", params=submit_params)
    if not resp.text.startswith("OK|"):
        raise Exception(f"Submit error: {resp.text}")

    task_id = resp.text.split("|")[1]

    # Poll
    deadline = time.time() + timeout
    while time.time() < deadline:
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY,
            "action": "get",
            "id": task_id
        })

        parsed = parse_result(result.text)

        if parsed["status"] == "pending":
            continue
        elif parsed["status"] == "solved":
            return parsed["result"]
        else:
            raise Exception(f"Solve error: {parsed['error']}")

    raise TimeoutError(f"Task {task_id} timed out after {timeout}s")

Perguntas frequentes

Por que a resposta usa delimitadores de barra vertical (|) em vez de JSON?

O formato do CaptchaAI é otimizado para simplicidade. As respostas delimitadas por barra vertical são menores e com menor latência de analisar do que JSON. Para dados estruturados (resultados do GeeTest), os dados após OK| contêm pares de valores-chave.

Como lidar com erros de rede?

Envolva chamadas de API em try/except e tente novamente em ConnectionError ou Timeout. Os problemas de rede são separados dos erros de API; a própria API mantém 99,9%+ de tempo de atividade.

Qual é o comprimento máximo do token?

Os tokens reCAPTCHA podem ter até aproximadamente 500 caracteres. Sempre use split("|", 1) (divisão máxima de 1) para evitar a divisão do próprio token.

Guias Relacionados

• Configuração e autenticação da chave API
• Retorno de chamada vs pesquisa
• Referência de códigos de erro CaptchaAI