Slider Captcha Solver API

This project provides a robust API for solving slider captchas (puzzle piece matching) using computer vision techniques (Masked Normalized Cross-Correlation with Sobel Edge Detection).

GIF:

Smoother Video: https://i.gyazo.com/984473076a3777c3b38f239f04260403.mp4

Setup & Run

1. Ensure Go is installed.
2. Add authorized API keys to allowed_keys.txt (one per line).
3. Run the server:

   go run .

   The server starts on port 8080.

Authentication

All requests must include the x-api-key header. The key must exist in allowed_keys.txt.

API Reference

Solve Captcha

Endpoint: POST /solve

Headers:

• x-api-key: (Required) Your API key.

Body (multipart/form-data):

• background: (Required) The background image file (PNG, JPEG).
• piece: (Required) The puzzle piece image file (PNG, JPEG).

Response (application/json):

{
  "x": 184,,
  "y": 34,
  "confidence": 0.798903
}

• x: The X coordinate of the top-left corner of the matching position.
• y: The Y coordinate of the top-left corner of the matching position.
• confidence: A score between -1.0 and 1.0 indicating the quality of the match (higher is better).

Example Usage

curl -X POST http://localhost:8080/solve \
  -H "x-api-key: secret-key-123" \
  -F "background=@bg-1.png" \
  -F "piece=@slice-1.png"

Algorithm Details

The solver uses the following pipeline:

1. Cropping: Automatically removes transparent/background borders from the puzzle piece.
2. Masking: Extracts a shape mask from the puzzle piece to ignore empty corners during matching.
3. Blurring: Applies Gaussian Blur to reduce texture noise.
4. Edge Detection: Uses Sobel operator to extract structural outlines.
5. Matching: Performs Normalized Cross-Correlation (NCC) between the masked piece edges and the background edges to find the best fit.

Benchmark

See BENCHMARK_RESULTS.md for performance metrics and optimization suggestions.