Self-developed CAPTCHA

Self-developed CAPTCHA (character image / arithmetic), rendered locally with Pillow and no third-party dependency; each answer is validated only once.

/api/captcha_self/

Service Description

The self-hosted CAPTCHA depends on no third-party service: the platform draws character images or arithmetic questions locally with Pillow, making it suitable when data must not leave your infrastructure or when you want a zero-cost in-house CAPTCHA.

Integration takes two steps: call the generate endpoint to get a captcha_id and a base64 image (with an expiry), then call the verify endpoint with the user's answer. Answers are one-time — they become invalid immediately after verification, whether it succeeds or fails, so a failed attempt requires a new CAPTCHA. The server stores only an HMAC-SHA256 digest of the answer, never the plaintext.

This channel is public and requires no project signature. The server applies per-IP rate limits (60 generates/min, 120 verifies/min) and disables caching on responses so images are not reused by browsers or proxies.

This service also provides Slider CAPTCHA and Chinese Character Picker channels: the former aligns a puzzle piece with the gap, the latter asks you to click 2-4 characters in order. Neither sends answer coordinates — they are kept server-side for verification.

Choosing a channel: character/arithmetic is the lightest option for form anti-bot; slider offers a drag experience; the Chinese character picker is the most intuitive for Chinese-speaking users.

Response Format

Every endpoint returns the same JSON envelope; the payload is always inside data:

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}

code: business status code. 10000 means success; anything else is an error — see the Error Codes page for the full list.
msg: a human-readable message you can show to end users, but never use it for program logic.
data: the payload; usually null on error. Each endpoint's Response section lists its data fields.

Judge success by code, not by the HTTP status code. View all error codes

Under Maintenance This service is currently in "Under Maintenance" status, the API may be temporarily unavailable. The docs and debug below are for reference only.

Self-developed CAPTCHA

SpiderServices/Captcha self-developed generation engine (drawn with Pillow) Available · No Signature

Two-step integration: call generate first to obtain a captcha_id and image (base64), then POST the user answer to verify. The answer is single-use: it expires immediately after validation, correct or not, so the frontend must fetch a new image afterwards.

GET /api/captcha_self/generate Total calls: 0

Generate CAPTCHA

Generate one CAPTCHA and return its captcha_id, base64 image and validity period.

Verification Code Type kind

Optional: char = character image (digits + uppercase letters); arithmetic = addition / subtraction

Character Count length

Optional: only applies when kind=char; valid range 4-6 (default 4)

Request method GET with parameters in the query string; public Endpoint, no project signature required.
captcha_id must be sent back to verify together with the answer; image can be used directly as an <img src>.
The response includes Cache-Control: no-store, so CAPTCHA images are not cached or reused by browsers or proxies.
Each IP can generate at most 60 CAPTCHAs per minute; exceeding this returns 20040.

Response Common envelope

Field	Type	Description
captcha_id	string	Captcha ID, pass it back when verifying
kind	string	Kind: char/arithmetic
image	string	base64 image (data URI)
expire_in	int	TTL (seconds)

Example response

{"captcha_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "kind": "char", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "expire_in": 300}

POST /api/captcha_self/verify Total calls: 0

Validate CAPTCHA

Submit the user answer for validation; the CAPTCHA is consumed on use (invalidated immediately after validation).

CAPTCHA ID captcha_id *

Required: the captcha_id (UUID) returned by the generate Endpoint

User Answer answer *

Required: the answer entered by the user (case-insensitive for characters; enter the computed result for arithmetic)

The request body is an application/x-www-form-urlencoded form; this is an open endpoint and needs no project signature.
Validation passed: code=10000 with data.passed=true;
Not passed (wrong answer / expired / already used / not found): code=20003 with data.passed=false; see msg for the cause;
A non-UUID captcha_id returns code=20002; a missing parameter returns code=20001.
The answer is single-use: repeated submissions of the same CAPTCHA can succeed only once, so call generate again after a failure.
Each IP can verify at most 120 times per minute; exceeding this returns 20040. Answers are compared in constant time and only a digest is stored.

Response Common envelope

Field	Type	Description
passed	bool	Whether the check passed

Example response

{"passed": true}

Slider CAPTCHA

Pillow local composition (background + puzzle piece) Available · No Signature

Drag the puzzle piece into the gap; the horizontal coordinate is not sent, and the server compares digests within a ±8px tolerance while validating the drag track (points / duration / monotonic time / matching endpoint).

GET /api/captcha_self/slider/generate Total calls: 0

Generate slider

Generate a background and puzzle piece; returns slider_id, vertical position and canvas size.

Try dragging

GET request, public endpoint, no project signature required.
background is JPEG and piece is PNG (both data URIs); the gap's horizontal coordinate is not in the response and must be matched by the user dragging the piece.
Each IP can generate at most 30 sliders per minute; exceeding this returns 20040. Responses are not cacheable.

Response Common envelope

Field	Type	Description
slider_id	string	Slider ID, returned on verification
background	string	Background image (JPEG data URI)
piece	string	Puzzle piece (PNG data URI with transparency)
piece_y	int	Vertical position of the puzzle piece (px)
piece_size	int	Puzzle piece edge length (px)
width	int	Canvas width (px, 320)
height	int	Canvas height (px, 160)
expire_in	int	TTL (seconds)

Example response

{"slider_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "background": "data:image/jpeg;base64,/9j/4AAQ…", "piece": "data:image/png;base64,iVBORw0KGgo…", "piece_y": 42, "piece_size": 52, "width": 320, "height": 160, "expire_in": 180}

POST /api/captcha_self/slider/verify Total calls: 0

Verify slider

Submit the puzzle piece position and drag track for one-time verification.

Slider ID slider_id *

Required: the slider_id (UUID) returned by generate.

Horizontal position x *

Required: the canvas x coordinate of the puzzle piece's left edge (decimals allowed).

Drag track track *

Required: JSON array with elements {"x": canvas coordinate, "t": relative milliseconds}; at least 5 points, total duration 200ms-60s, and the last point must match x.

The request body is an application/x-www-form-urlencoded form; this is a public Endpoint with no project signature required.
A position error within ±8px counts as aligned; the gap's horizontal coordinate is never sent and only a digest is stored.
Tracks with too few points, too short a duration, decreasing timestamps, or an endpoint that does not match x are rejected.
One-time: regardless of success or failure, each slider_id can be verified only once.
Each IP can verify at most 60 times per minute; 10 consecutive failures trigger a 10-minute cooldown. Both cases return 20040.

Response Common envelope

Field	Type	Description
passed	bool	Whether the check passed

Example response

{"passed": true}

Chinese Character Picker

Pillow + bundled Chinese font (8 candidate characters, click 2-4) Available · No Signature

Click the target characters in the order shown; target coordinates are not sent, and the server validates click order, hit positions and total duration.

GET /api/captcha_self/click/generate Total calls: 1

Generate character challenge

Generate an image with 8 candidate characters; returns the challenge ID, image and target characters in order.

Try clicking

GET request, public endpoint, no project signature required.
chars are the target characters (2-4) to click in order; their coordinates are not in the response and are stored server-side only for hit testing.
Each IP can generate at most 30 sliders per minute; exceeding this returns 20040. Responses are not cacheable.

Response Common envelope

Field	Type	Description
challenge_id	string	Challenge ID, returned on verification
image	string	CAPTCHA image (PNG data URI)
chars	array	Target characters to click in order
count	int	Number of target characters (2-4)
width	int	Canvas width (px, 360)
height	int	Canvas height (px, 200)
expire_in	int	TTL (seconds)

Example response

{"challenge_id": "9f1c1f14-6b0a-4a3e-9c31-2c9b6f0d1a55", "image": "data:image/png;base64,iVBORw0KGgo…", "chars": ["山", "河", "云"], "count": 3, "width": 360, "height": 200, "expire_in": 180}

POST /api/captcha_self/click/verify Total calls: 0

Verify character challenge

Submit ordered click points; validates order, hit positions and total duration.

Challenge ID challenge_id *

Required: the challenge_id (UUID) returned by generate.

Click points points *

Required: JSON array with elements {"x": canvas x, "y": canvas y, "t": relative milliseconds}; the number of points must equal count and total duration must be at least 300ms.

The request body is an application/x-www-form-urlencoded form; this is a public Endpoint with no project signature required.
Click order must match chars; each point must land within 26px of its target character.
Mismatched point count, wrong order, missed targets, or a total duration under 300ms are all rejected.
One-time: regardless of success or failure, each challenge_id can be verified only once.
Each IP can verify at most 60 times per minute; 10 consecutive failures trigger a 10-minute cooldown. Both cases return 20040.

Response Common envelope

Field	Type	Description
passed	bool	Whether the check passed

Example response

{"passed": true}

Endpoint catalog 6

Self-developed CAPTCHA

GET Generate CAPTCHA /api/captcha_self/generate POST Validate CAPTCHA /api/captcha_self/verify

Slider CAPTCHA

GET Generate slider /api/captcha_self/slider/generate POST Verify slider /api/captcha_self/slider/verify

Chinese Character Picker

GET Generate character challenge /api/captcha_self/click/generate POST Verify character challenge /api/captcha_self/click/verify

Auth Settings

Stored locally only