Core API

Core API

CaptchaConfig

All generators accept a CaptchaConfig in their constructor. Newer visual generators may also accept a per-call config.

Field	Default	Purpose
width	720	Output width
height	240	Output height
output_format	"PNG"	PNG, JPEG, WEBP or GIF where supported
quality	92	JPEG/WEBP quality
background_color	light blue	Canvas background
foreground_color	dark blue	Text and outline color
accent_colors	five colors	Challenge palette
fonts	()	Font file paths
font_size	None	Optional fixed font size
line_width	3	Shape and outline width
padding	24	Safe canvas padding
language	"en"	Integration language hint
prompt	None	Override the generated prompt
accessibility_text	None	Screen-reader description
high_contrast	False	High-contrast preference
include_answer_in_metadata	False	Debug only; never enable for clients
random_seed	None	Reproducible generation
pre_render_hook	None	Transform image before resize/save
post_render_hook	None	Final watermark or image transform

ChallengeResult

Most visual generators return:

@dataclass(frozen=True)
class ChallengeResult:
    answer: object
    path: str
    prompt: str
    metadata: dict[str, object]
    accessibility_text: str
    mime_type: str

Legacy-style generators return strings or tuples. Their exact return values are documented on the category pages.

Registry

from CaptchaGenerator import SUPPORTED_CAPTCHAS

generator_type = SUPPORTED_CAPTCHAS["MazeCaptcha"]
generator = generator_type()

Errors

Invalid parameters raise InvalidArgumentError. Optional dependency and generation failures derive from CaptchaError.