Решатель Popular Captcha

Решайте задачи с взаимодействием с объектами через типы задач PopularCaptchaImage или PopularClassification. Поле questionType определяет способ обработки задачи.

Поддерживаемые режимы

Создание задачи — Сетка-классификация

{
    "apiKey": "YOUR_API_KEY",
    "task": {
        "type": "PopularCaptchaImage",
        "questionType": "objectClassify",
        "question": "Select all objects with a bridge",
        "queries": ["BASE64_IMG_1", "BASE64_IMG_2"]
    }
}

Ответ

{
    "code": 200,
    "msg": "",
    "answers": [true, false, true, true, false, true],
    "questionType": "objectClassify",
    "meta": { "pass_report": true, "fail_report": true }
}

Создание задачи — Клик по объекту

{
    "apiKey": "YOUR_API_KEY",
    "task": {
        "type": "PopularCaptchaImage",
        "questionType": "objectClick",
        "question": "Click on the center of the car",
        "queries": ["BASE64_MAIN_IMAGE"]
    }
}

Создание задачи — Drag по объекту

{
    "apiKey": "YOUR_API_KEY",
    "task": {
        "type": "PopularCaptchaImage",
        "questionType": "objectDrag",
        "question": "Drag the puzzle piece to the gap",
        "queries": ["BASE64_BACKGROUND"],
        "examples": ["BASE64_PUZZLE_PIECE"]
    }
}

Параметры задачи

Решение видео-капч (Dynamic Canvas)

Некоторые задачи (например, варианты hCaptcha) содержат динамическую анимацию на холсте (canvas) вместо статических изображений. Они решаются с использованием специализированного варианта типа задачи PopularCaptchaImage, требующего захвата/записи холста на стороне клиента (путем объединения нескольких кадров видео в одно изображение или отправки исходного видео).

Чтобы избежать записи и обработки видео при каждом вызове, настоятельно рекомендуется реализовать механизм кэширования на стороне клиента, сопоставляющий целевой вопрос с разрешенной конфигурацией холста.

Стратегия Кэширования (на стороне клиента)

1. Нормализация Омографов (Homoglyph Normalization): Очищайте текст question от Unicode-омографов (кириллических/греческих символов, похожих на английские буквы) перед запросом или сохранением в кэш. Это гарантирует, что ключи кэша будут соответствовать алгоритму нормализации на бэкенде.
2. TTL (Время Жизни): 24 часа.
3. Емкость: Максимум 800 записей с вытеснением LRU (Least Recently Used).
4. Ключ Кэша: "nc_video_cache", сопоставляющий нормализованный текст вопроса с canvasParams.

Процесс Решения (Алгоритм)

Сценарий А: Промах Кэша (Двухфазный Процесс)

sequenceDiagram
    participant Client as Клиент
    participant Server as Сервер
    Note over Client: Шаг 1: Обнаружение задачи
    Client->>Server: POST /createTask (Исходный стандартный запрос)
    Server-->>Client: 400 Bad Request (questionVariant: "canvasvideo")
    Note over Client: Шаг 2: Получение canvasParams и запись в кэш
    Note over Client: Шаг 3: Запись видео с холста (например, 2 сек) и слияние кадров
    Client->>Server: POST /createTask (Обогащенный запрос фазы 2)
    Server-->>Client: 200 OK (Координаты ответов)

1. Первоначальный захват: Отправьте стандартный однокадровый запрос в solver API (/createTask).
2. Сигнал Бэкенда: Если бэкенд обнаруживает, что этот целевой вопрос требует видео-капчу, он возвращает статус 400 и questionVariant: "canvasvideo" вместе с требуемыми canvasParams.
3. Сохранение в Кэш: Сохраните полученные canvasParams локально.
4. Запись и Объединение Холста:
   • Если canvasParams.video имеет значение true, запишите видео с холста в течение указанного времени.
   • Извлеките и объедините/объедините кадры в соответствии с canvasParams.format.
5. Повторная отправка (Фаза 2): Сформируйте обогащенный запрос, содержащий canvasVideo: true, объединенный кадр в queries и массив base64 записанного видео. Повторно отправьте запрос на бэкенд, чтобы получить успешный ответ 200.

Сценарий Б: Попадание в Кэш (Однофазный Процесс)

sequenceDiagram
    participant Client as Клиент
    participant Server as Сервер
    Note over Client: Шаг 1: Запрос к кэшу (поиск по нормализованному вопросу)
    Note over Client: Шаг 2: Мгновенная запись холста и слияние кадров
    Client->>Server: POST /createTask (Обогащенный запрос сразу)
    Server-->>Client: 200 OK (Координаты ответов)
    Note over Client: Резервный вариант: если сервер отклонил, инвалидировать кэш и запустить фазу 1

1. Проверка Кэша перед отправкой: Выполните запрос к локальному кэшу, используя нормализованный текст вопроса.
2. Мгновенная подготовка холста: Если найдена валидная запись в кэше, сразу же начните запись холста и объединение кадров на основе параметров из кэша.
3. Однофазная отправка: Отправьте полностью сформированный запрос (объединенный кадр + данные видео) непосредственно при первом обращении.
4. Резервный сброс: Если сервер отклонил запрос (например, параметры кэша устарели или изменились на сервере), удалите сохраненную конфигурацию из кэша и выполните стандартный двухфазный процесс.

Структура Данных (Запросы и Ответы)

1. Исходный Запрос (Фаза 1 - Промах Кэша)

Отправляется при первой попытке решить капчу, когда еще неизвестно, требуется ли видео-обработка.

{
  "apiKey": "YOUR_API_KEY",
  "task": {
    "type": "PopularCaptchaImage",
    "queries": ["data:image/jpeg;base64,..."],
    "examples": ["data:image/jpeg;base64,..."],
    "question": "Please click on the living room",
    "screenshot": false,
    "questionType": "objectClick",
    "websiteURL": "example.com",
    "websiteKEY": "sitekey-value"
  }
}

2. Ответ (Указывает на необходимость Видео-Капчи)

Возвращается сервером, если обнаружен холст с видео.

{
  "code": 400,
  "msg": "canvasvideo",
  "questionVariant": "canvasvideo",
  "questionType": "objectClick",
  "canvasParams": {
    "duration": 2,
    "video": true,
    "format": ["frameMerge"],
    "frames": [0.1, 0.5, 1.0],
    "framecount": null
  }
}

3. Обогащенный Запрос (Повторная отправка Фазы 2 / Попадание в Кэш)

Содержит объединенное изображение (в queries) и записанное видео холста.

{
  "apiKey": "YOUR_API_KEY",
  "task": {
    "type": "PopularCaptchaImage",
    "queries": ["data:image/jpeg;base64,..."], // Результат объединения кадров
    "examples": ["data:image/jpeg;base64,..."],
    "question": "please click on the living room", // Нормализованный вопрос
    "screenshot": false,
    "questionType": "objectClick",
    "websiteURL": "example.com",
    "websiteKEY": "sitekey-value",
    "choices": [],
    "canvasVideo": true,
    "format": "frameMerge", // или "framecount"
    "video": ["data:video/mp4;base64,..."] // Base64 записанного видео
  }
}

4. Ответ (Успешное Решение)

{
  "code": 200,
  "status": "ready",
  "questionType": "objectClick",
  "answers": [
    [
      { "x": 109, "y": 179 },
      { "x": 163, "y": 260 }
    ]
  ],
  "meta": {
    "data": "...",
    "fail_report": true,
    "pass_report": true
  }
}

Коды Ошибок

Примеры Кода

# Шаг 1: Создание задачи
RESPONSE=$(curl -s -X POST "https://api.captchasonic.com/createTask" \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "YOUR_API_KEY",
  "task": {
    "type": "PopularCaptchaImage",
    "questionType": "objectClassify",
    "question": "Select all objects with a bridge",
    "queries": [
      "BASE64_IMG_1",
      "BASE64_IMG_2"
    ]
  }
}')

echo "Create Task Response: $RESPONSE"
TASK_ID=$(echo $RESPONSE | grep -o '"taskId":"[^"]*"' | cut -d'"' -f4)

# Шаг 2: Ожидание результата
while true; do
  RESULT=$(curl -s -X POST "https://api.captchasonic.com/getTaskResult" \
    -H "Content-Type: application/json" \
    -d "{\"apiKey\": \"YOUR_API_KEY\", \"taskId\": \"$TASK_ID\"}")
  echo "Result: $RESULT"
  echo "$RESULT" | grep -q '"status":"processing"' || break
  sleep 2
done

API Playground

{
  "apiKey": "YOUR_API_KEY",
  "task": {
    "type": "PopularCaptchaImage",
    "questionType": "objectClassify",
    "question": "Select all objects with a bridge",
    "queries": [
      "BASE64_IMG_1",
      "BASE64_IMG_2"
    ]
  }
}