CaptchaAI Quickstart: ваше первое решение CAPTCHA за 5 минут

Первый вызов API CaptchaAI занимает пять минут: ключ, задача, токен, форма.

Без теории и отступлений — сразу код на Python, Node.js, PHP и cURL, который можно скопировать, вставить и запустить без адаптации под ваш стек.

Как устроен быстрый старт: четыре шага

Любой тип CAPTCHA в CaptchaAI решается по одной схеме:

1. Отправить — POST-запрос на in.php
2. Получить ID задачи — сохранить request из ответа
3. Опросить — GET-запрос к res.php раз в 5 секунд
4. Применить токен — вставить в форму или в запрос

Шаг 0. Получите API-ключ CaptchaAI

1. Зарегистрируйтесь на captchaai.com
2. Откройте панель управления
3. Скопируйте API-ключ (32 символа)

Без активных потоков задачи не отправляются. На оценке сервиса — напишите в поддержку, обычно дают бесплатные потоки.

Шаг 1. Отправьте CAPTCHA на решение

Пример решает Cloudflare Turnstile. Со страницы нужны два значения:

• sitekey — публичный ключ виджета, из атрибута data-sitekey (начинается с 0x)
• pageurl — полный URL страницы с виджетом

Такая пара регулярно нужна QA-инженерам распределённых команд — например, при тестировании формы логина на staging в европейском дата-центре, до релиза.

cURL

curl -X POST "https://ocr.captchaai.com/in.php" \
  -d "key=YOUR_API_KEY" \
  -d "method=turnstile" \
  -d "sitekey=0x4AAAAAAAC3DHQFLr1GavNl" \
  -d "pageurl=https://staging.example.com/qa-login" \
  -d "json=1"

Python

import requests

response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "turnstile",
    "sitekey": "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl": "https://staging.example.com/qa-login",
    "json": 1,
})
print(response.json())

Node.js

const response = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    method: "turnstile",
    sitekey: "0x4AAAAAAAC3DHQFLr1GavNl",
    pageurl: "https://staging.example.com/qa-login",
    json: "1",
  }),
});
console.log(await response.json());

PHP

<?php
$response = file_get_contents("https://ocr.captchaai.com/in.php?" . http_build_query([
    "key"       => "YOUR_API_KEY",
    "method"    => "turnstile",
    "sitekey"   => "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl"   => "https://staging.example.com/qa-login",
    "json"      => 1,
]));
echo $response;

Шаг 2. Получите ID задачи и разберите ответ

Успешный ответ выглядит так:

{
  "status": 1,
  "request": "71823469"
}

request — ID задачи, понадобится дальше.

Если status равен 0, код ошибки — в том же поле request:

Шаг 3. Опросите res.php и дождитесь токена

Первый опрос делайте не раньше чем через 15 секунд после отправки, дальше — раз в 5 секунд, пока не придёт готовый результат.

Python

import time

time.sleep(15)

while True:
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY",
        "action": "get",
        "id": "71823469",
        "json": 1,
    }).json()

    if result.get("request") == "CAPCHA_NOT_READY":
        time.sleep(5)
        continue

    if result.get("status") == 1:
        token = result["request"]
        print(f"Solved! Token: {token[:60]}...")
        break

    raise RuntimeError(result)

Node.js

await new Promise((r) => setTimeout(r, 15000));

while (true) {
  const r = await fetch(
    `https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=71823469&json=1`,
  );
  const data = await r.json();
  if (data.request === "CAPCHA_NOT_READY") {
    await new Promise((r) => setTimeout(r, 5000));
    continue;
  }
  if (data.status === 1) {
    console.log("Solved:", data.request.slice(0, 60));
    break;
  }
  throw new Error(JSON.stringify(data));
}

Шаг 4. Примените токен на странице

Применение токена зависит от типа CAPTCHA:

• Turnstile / reCAPTCHA — запишите в поле cf-turnstile-response или g-recaptcha-response, либо вызовите js-колбэк страницы.
• Image OCR — вставьте распознанный текст в поле ответа.
• GeeTest — соберите несколько полей ответа по требованиям сайта.

Минимальный вариант для браузера:

document.querySelector('[name="cf-turnstile-response"]').value = token;
document.querySelector("form").submit();

Частые ошибки при первом запуске CaptchaAI API

Частые вопросы о быстром старте CaptchaAI

Сколько потоков нужно для первого теста?

Тарифы считаются по потокам, не по количеству решений: план BASIC ($15/мес, 5 потоков) уже покрывает quickstart, первые прогоны и небольшой staging-стенд без апгрейда.

Как долго живёт токен Turnstile?

Около 120 секунд с момента, когда вы получили его из res.php. Применяйте токен сразу — кешировать и переиспользовать его в следующем запросе нельзя, он одноразовый.

Что делать, если res.php долго возвращает CAPCHA_NOT_READY?

Пару десятков секунд — норма для обычной задачи. Если статус не меняется дольше 60 секунд подряд, задача, скорее всего, зависла: отмените её по таймауту на своей стороне и отправьте новую, не ждите бесконечно.

Эта схема подходит только для Turnstile?

Нет, схема из четырёх шагов одинакова для всех поддерживаемых типов CAPTCHA — меняется только значение method в запросе на шаге 1 и способ применения токена на шаге 4.

Нужен ли браузер для использования токена?

Нет, если целевой сайт принимает токен прямо в POST-запросе формы — тогда достаточно HTTP-клиента. Браузер нужен, только если токен вставляется через JavaScript на живой странице перед отправкой формы.

Что дальше после быстрого старта CaptchaAI

Дальше выбирайте гайд по конкретному типу CAPTCHA, с которым работает ваш проект — параметры запроса и способ применения токена немного различаются:

• Решение reCAPTCHA v2 через API
• Настройка Cloudflare Turnstile через API
• GeeTest v3: решение через API
• Распознавание image CAPTCHA через API

Ключ получаете на captchaai.com/api.php; путь от регистрации до первого решённого токена занимает пять минут — дальше это уже вопрос интеграции в ваш пайплайн.