Документация API
Три эндпоинта и полные примеры кода на шести языках. Интеграция менее чем за 60 секунд с высокопроизводительным кластером решателей Capzy.
Быстрый старт
POST /createTaskОтправьте тип капчи и параметры сайта. taskId вернётся мгновенно.
POST /getTaskResultОпрашивайте примерно раз в секунду, пока статус не станет ready. Токен придёт в объекте solution.
POST /getBalanceПроверьте остаток кредитов. За неудачные решения средства возвращаются сюда автоматически.
https://api.capzy.aiаутентификация через clientKey в теле запросаЭндпоинты
/createTaskСоздать новую задачу решения капчи{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResultОпросить результат задачи{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalanceПроверить баланс аккаунта{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/reportScoreНеобязательно: сообщите нам подтверждённую оценку Google для задач V3. На её основе работает раздел качества V3 в вашей панели. Один отчёт на задачу; отчёты должны поступить в течение 24 часов после завершения решения.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/reportCorrectCaptchaНеобязательно: сообщите, что решение было ПРИНЯТО целевым сайтом. Особенно полезно для типов с возвратом координат (например, слайдер Shopee), где мы возвращаем позицию, а перетаскивание выполняет ваш браузер. Этот отчёт: наш единственный сигнал о реальной точности. Один отчёт на задачу, в течение 24 часов; на цены не влияет.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/reportIncorrectCaptchaНеобязательно: сообщите, что решение было ОТКЛОНЕНО целевым сайтом. Данные идут в тот же учёт реальной точности, что и /reportCorrectCaptcha. Один отчёт на задачу, в течение 24 часов; на цены не влияет.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }Поддерживаемые типы задач
Загрузка…Актуальный список включённых сейчас типов задач, сгруппированных по провайдерам капч. Цены и среднее время решения обновляются автоматически по телеметрии кластера.
Лимиты запросов
Лимиты действуют на аккаунт и суммируются по всем вашим API-ключам. При превышении лимита возвращается код ошибки, кредиты не расходуются.
С этого уровня начинается каждый новый аккаунт
Создайте тикет в поддержку с ожидаемым объёмом (отдельного ценового уровня нет, цена за решение та же)
одновременные задачиСколько задач может одновременно находиться в очереди на решение. Задача учитывается в лимите с момента createTask до завершения (успех, ошибка или тайм-аут).
лимит запросовСколько вызовов createTask можно делать в секунду. Скользящее окно, лимит на аккаунт. При превышении возвращается ERROR_RATE_LIMITED, кредиты не списываются.
Коды ошибок
Все ошибки, которые возвращают /createTask / /getTaskResult, и способы их исправить. За неудачные решения средства возвращаются автоматически: кредиты сразу возвращаются на баланс.
Аутентификация
Проблемы с API-ключом или IP.- #
ERROR_KEY_DOES_NOT_EXISTВаш API-ключ не распознан.
решениеПроверьте значение в разделе «Панель управления → API-ключи». Ключи начинаются с `capzy_`. Сменённые ключи сразу становятся недействительными.
- #
ERROR_IP_NOT_ALLOWEDIP вашего запроса не входит в список разрешённых для этого 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.
Песочница кода
Полные рабочие примеры на всех основных языках. Скопируйте, вставьте свой API-ключ и запустите.
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)Интеграция менее чем за 60 секунд.
$0.10 бесплатных кредитов при регистрации. Банковская карта не нужна.
Получить бесплатный API-ключ →