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

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: 1

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: 0

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