Перейти к содержимому

Документация API

Три эндпоинта и полные примеры кода на шести языках. Интеграция менее чем за 60 секунд с высокопроизводительным кластером решателей Capzy.

Быстрый старт

шаг 1
POST /createTask

Отправьте тип капчи и параметры сайта. taskId вернётся мгновенно.

шаг 2
POST /getTaskResult

Опрашивайте примерно раз в секунду, пока статус не станет ready. Токен придёт в объекте solution.

шаг 3
POST /getBalance

Проверьте остаток кредитов. За неудачные решения средства возвращаются сюда автоматически.

базовый urlhttps://api.capzy.aiаутентификация через clientKey в теле запроса

Эндпоинты

POST/createTaskСоздать новую задачу решения капчи
запрос
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
ответ
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultОпросить результат задачи
запрос
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
ответ
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceПроверить баланс аккаунта
запрос
{ "clientKey": "capzy_..." }
ответ
{ "errorId": 0, "balance": 9.50 }
POST/reportScoreНеобязательно: сообщите нам подтверждённую оценку Google для задач V3. На её основе работает раздел качества V3 в вашей панели. Один отчёт на задачу; отчёты должны поступить в течение 24 часов после завершения решения.
запрос
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
ответ
{ "errorId": 0 }
POST/reportCorrectCaptchaНеобязательно: сообщите, что решение было ПРИНЯТО целевым сайтом. Особенно полезно для типов с возвратом координат (например, слайдер Shopee), где мы возвращаем позицию, а перетаскивание выполняет ваш браузер. Этот отчёт: наш единственный сигнал о реальной точности. Один отчёт на задачу, в течение 24 часов; на цены не влияет.
запрос
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
ответ
{ "errorId": 0 }
POST/reportIncorrectCaptchaНеобязательно: сообщите, что решение было ОТКЛОНЕНО целевым сайтом. Данные идут в тот же учёт реальной точности, что и /reportCorrectCaptcha. Один отчёт на задачу, в течение 24 часов; на цены не влияет.
запрос
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
ответ
{ "errorId": 0 }

Поддерживаемые типы задач

Загрузка…

Актуальный список включённых сейчас типов задач, сгруппированных по провайдерам капч. Цены и среднее время решения обновляются автоматически по телеметрии кластера.

Загрузка типов задач…

Лимиты запросов

Лимиты действуют на аккаунт и суммируются по всем вашим API-ключам. При превышении лимита возвращается код ошибки, кредиты не расходуются.

По умолчанию
30 одновременно · 30 запросов/с

С этого уровня начинается каждый новый аккаунт

Повышенная параллельность
300+ одновременно · 100+ запросов/с

Создайте тикет в поддержку с ожидаемым объёмом (отдельного ценового уровня нет, цена за решение та же)

одновременные задачи

Сколько задач может одновременно находиться в очереди на решение. Задача учитывается в лимите с момента createTask до завершения (успех, ошибка или тайм-аут).

лимит запросов

Сколько вызовов createTask можно делать в секунду. Скользящее окно, лимит на аккаунт. При превышении возвращается ERROR_RATE_LIMITED, кредиты не списываются.

Коды ошибок

Все ошибки, которые возвращают /createTask / /getTaskResult, и способы их исправить. За неудачные решения средства возвращаются автоматически: кредиты сразу возвращаются на баланс.

Аутентификация

Проблемы с API-ключом или IP.
  • ERROR_KEY_DOES_NOT_EXIST

    Ваш API-ключ не распознан.

    решениеПроверьте значение в разделе «Панель управления → API-ключи». Ключи начинаются с `capzy_`. Сменённые ключи сразу становятся недействительными.

    #
  • ERROR_IP_NOT_ALLOWED

    IP вашего запроса не входит в список разрешённых для этого API-ключа.

    решениеДобавьте свой IP в список разрешённых для ключа в разделе «Панель управления → API-ключи» или полностью удалите список, если привязка к IP не нужна.

    #
  • ERROR_IP_BLOCKED

    Ваш IP временно заблокирован из-за слишком большого числа некорректных запросов.

    решениеМы блокируем IP, отправляющие 100+ некорректных запросов за 10 минут (с нарастанием). Исправьте ошибку, из-за которой отправляются некорректные запросы, и подождите. Блокировка снимается автоматически через срок от 1 минуты до 24 часов в зависимости от уровня.

    #

Валидация

Неверные параметры задачи или неподходящий тип для sitekey.
  • ERROR_INVALID_PARAMS

    Тело запроса имеет неверный формат или в нём нет обязательных полей.

    решениеУбедитесь, что `clientKey` находится на верхнем уровне, а `task` содержит `type` и обязательный идентификатор (websiteURL/websiteKey/captchaId и т. д.). Обязательные параметры для каждого типа см. в разделе «Типы задач».

    #
  • ERROR_BAD_SITEKEY

    `websiteKey` не зарегистрирован ни у одного известного нам провайдера капчи.

    решениеУбедитесь, что вы копируете sitekey целиком с целевой страницы (ищите `data-sitekey`, `sitekey:` или параметр в `grecaptcha.render` / `hcaptcha.render`).

    #
  • ERROR_TASK_NOT_SUPPORTED

    Отправленный `type` задачи не относится к типам капч, которые Capzy сейчас поддерживает.

    решениеПолный список включённых типов см. в разделе «Типы задач» ниже. Если нужной капчи нет в списке, создайте тикет, и мы рассмотрим её в приоритетном порядке.

    #
  • ERROR_WRONG_TASK_TYPE

    Тип задачи не соответствует фактическому провайдеру sitekey.

    решениеМы заранее проверяем sitekey по их реальному провайдеру. Ответ с ошибкой содержит поле `recommended`: переключитесь на этот тип задачи. (Кредиты не списываются.)

    #
  • ERROR_PROXY_REQUIRED

    Эта капча привязана к IP: её токены связаны с IP, с которого она была решена.

    решениеИспользуйте вариант `*Task` (вместо `*TaskProxyLess`) и передайте `proxyAddress`, совпадающий с IP, с которого вы будете отправлять токен. Касается: Cloudflare Challenge, CaptchaFox, AWS WAF, DataDome, PerimeterX, Kasada, Akamai, Imperva.

    #
  • ERROR_NO_PROXY

    Для этого типа задачи нужны поля прокси, но они отсутствуют.

    решениеУкажите в теле задачи `proxyType`, `proxyAddress`, `proxyPort` (и при необходимости `proxyLogin`/`proxyPassword`/`userAgent`).

    #
  • ERROR_PROXY_CONNECT_REFUSED

    Указанный вами прокси отклонил подключение.

    решениеПроверьте учётные данные прокси, доступность хоста и то, что IP работает. Сначала попробуйте тот же прокси со своей машины, чтобы исключить проблемы провайдера.

    #

Лимиты запросов

Лимиты одновременных задач, запросов в секунду и доли возвратов.
  • ERROR_MAX_TASKS_REACHED

    Вы достигли лимита одновременных задач для уровня вашего аккаунта.

    решениеДождитесь завершения текущих задач, прежде чем отправлять новые. Для уровня Regular по умолчанию: 30 одновременных задач; для повышения обратитесь в поддержку.

    #
  • ERROR_RATE_LIMITED

    Вы отправляете /createTask чаще, чем позволяет ваш лимит запросов.

    решениеСнизьте частоту и повторите попытку. Для уровня Regular по умолчанию: 30 запросов/с в скользящем окне. Превышение лимита не расходует кредиты.

    #
  • ERROR_NO_SLOT_AVAILABLE

    Мощности кластера временно исчерпаны.

    решениеПовторите попытку через несколько секунд (это временно). Если проблема сохраняется несколько минут, проверьте status.capzy.ai.

    #
  • ERROR_SYSTEM_MAINTENANCE

    В Capzy идут плановые технические работы.

    решениеПовторите попытку после окончания технических работ. Мы заранее публикуем уведомления на странице статуса.

    #

Результаты решения

Что вернул решатель. За неудачные решения средства возвращаются автоматически.
  • ERROR_TIMEOUT

    Задача не завершилась в пределах тайм-аута для этого типа.

    решениеСредства возвращены автоматически, ничего не списано. Большинство тайм-аутов временные. Если определённая капча постоянно завершается по тайм-ауту, создайте тикет с UUID задачи.

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    Решатель исчерпал лимит повторных попыток для этой проверки.

    решениеСредства возвращены автоматически, ничего не списано. Частые причины: устаревший sitekey, websiteURL не совпадает с доменом встраивания, капча отключена на целевом сайте.

    #
  • ERROR_NULL_RESULT

    Решатель завершил работу, но не вернул токен.

    решениеСредства возвращены автоматически. Обычно это означает, что целевой сайт убрал капчу во время решения. Повторите попытку; если проблема сохраняется, создайте тикет.

    #
  • ERROR_INTERNAL

    Непредвиденная ошибка в конвейере решения.

    решениеСредства возвращены автоматически. Повторите попытку (такое бывает редко). Если ошибки идут подряд, создайте тикет с UUID задачи.

    #
  • ERROR_ZERO_BALANCE

    Баланса аккаунта недостаточно для оплаты задачи.

    решениеПополните баланс в разделе «Панель управления → Оплата». За неудачные решения средства возвращаются автоматически, поэтому вы платите только за успешные токены.

    #

Отчёты об оценке

Ошибки, характерные для /reportScore (обратная связь о качестве V3).
  • ERROR_TASK_NOT_FOUND

    /reportScore: taskId не принадлежит вашему аккаунту или был удалён.

    решениеОтчёт об оценке должен ссылаться на вашу задачу и отправляться в течение 24 ч после завершения решения.

    #
  • ERROR_TASK_NOT_READY

    /reportScore: задача ещё обрабатывается или уже завершилась ошибкой.

    решениеОценивать можно только задачи со статусом `ready`. Дождитесь, пока /getTaskResult вернёт ready, прежде чем отправлять отчёт.

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore: с момента завершения решения прошло более 24 ч.

    решениеОтправляйте оценки в течение нескольких минут после вызова siteverify. Именно тогда данные наиболее полезны для нашей панели качества V3.

    #
06

Песочница кода

Полные рабочие примеры на всех основных языках. Скопируйте, вставьте свой API-ключ и запустите.

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)
Пример выводаУспех (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

Интеграция менее чем за 60 секунд.

$0.10 бесплатных кредитов при регистрации. Банковская карта не нужна.

Получить бесплатный API-ключ →