ray-slide-captcha

Slide puzzle captcha Python backend library.

简体中文 | English

Companion frontend: ray-captcha-react

Features

• Core service CaptchaService has zero framework dependencies — works with any Python project (Flask / Django / Starlette / FastAPI, etc.)
• FastAPI router shipped as an optional adapter, ready out of the box
• Background pre-generated asset pool, response < 10ms
• IP rate limiting + failure penalty + one-time token
• HMAC-SHA256 signed token, consumed once by the business layer
• Multi-source background image downloader with automatic retry on failure

Installation

# Core library (only depends on Pillow, works with any Python framework)
pip install ray-slide-captcha

# With FastAPI router adapter
pip install ray-slide-captcha[fastapi]

Quick Start

Any Python framework

from ray_slide_captcha import CaptchaService

service = CaptchaService(secret_key="your-secret-key-at-least-32-chars")
challenge = service.create_challenge(client_ip="1.2.3.4")
# Write your own routes to handle challenge / verify / consume_token

FastAPI

from fastapi import FastAPI
from ray_slide_captcha import CaptchaService
from ray_slide_captcha.fastapi import create_captcha_router

app = FastAPI()
service = CaptchaService(secret_key="your-secret-key-at-least-32-chars")
app.include_router(create_captcha_router(service), prefix="/api")

# Consume token in your business endpoint
@app.post("/login")
def login(token: str):
    if not service.consume_token(token):
        raise HTTPException(400, "Invalid captcha")
    # ...

Run the example server

pip install -e .[dev]
cd examples
python main.py
# Server runs at http://localhost:8000

CaptchaService Configuration

API Endpoints

GET /captcha/challenge

Fetch a new captcha challenge.

Response:

{
  "code": 200,
  "msg": "Captcha challenge generated",
  "data": {
    "id": "uuid",
    "bgUrl": "data:image/png;base64,...",
    "puzzleUrl": "data:image/png;base64,...",
    "expires_in": 120
  }
}

Note: All msg values are English by default. To localize, modify the ERR_MESSAGES dict in fastapi.py or pass a custom msg to ok() / fail().

POST /captcha/verify

Verify the drag position and return a one-time token.

Request body:

{
  "id": "uuid",
  "x_position": 150,
  "drag_duration_ms": 800
}

Response:

{
  "code": 200,
  "msg": "Verification successful",
  "data": {
    "success": true,
    "token": "eyJjbGllbnRJZCI6IC...",
    "expires_in": 300
  }
}

CaptchaService.consume_token(token)

Called by the business layer to consume a token once (invalidated after consumption).

from ray_slide_captcha import CaptchaService

service = CaptchaService(secret_key="...")

if not service.consume_token(token):
    raise Exception("Invalid or expired captcha")

Anti-Abuse Mechanisms

License

MIT