Skip to content
moxon home

Captcha Generation

The /captcha endpoint generates a CAPTCHA image. It offers two modes: image, which returns the answer alongside the picture, and challenge, which keeps the answer server-side so it can be verified later.

gethttps://api.moxon.dev/v5/captcha

Prefer proof of work

A visual captcha no longer stops a determined bot: vision models read them well, often better than people do. For anti-bot protection, prefer /pow, which cannot be shortcut by a model — the only way through is to spend the computation.

Try itget/v5/captcha
curl -X GET \  "https://api.moxon.dev/v5/captcha"

Send the request to see the response here.

Parameters

  • mode"image" | "challenge"optional

    image (default) or challenge

  • textstringoptional

    The captcha text. If omitted, a random string is generated. Rejected in challenge mode

  • lengthnumberoptional

    Length of the auto-generated text, 1 to 20. Default: 6

  • widthnumberoptional

    Image width in pixels, 100 to 800. Default: 60 × the text length

  • heightnumberoptional

    Image height in pixels, 50 to 400. Default: 120

  • noise"low" | "medium" | "high"optional

    Noise level: low, medium (default) or high

  • bgstringoptional

    Background color in hexadecimal (e.g. ffffff)

  • colorstringoptional

    Text color in hexadecimal (e.g. 000000)

Available Modes

ModeResponse
imagePNG image, with the answer in the X-Captcha-Text header
challengePNG image, with a signed token in the X-Captcha-Token header — the answer is never sent

Both modes return a PNG image (Content-Type: image/png), usable in an <img> tag.

In challenge mode the answer never leaves the server: it exists only inside the token's signature, so intercepting the response does not reveal it. The rendering is also hardened against automated reading — glyphs overlap so they cannot be segmented, ride a sine baseline, mix font families, and are crossed by strokes drawn in the text's own colors, which no filter can subtract. The default image mode is unchanged. Send the token and the user's answer to /v5/captcha to check it.

Good to know

Both headers are exposed to browser JavaScript through CORS, so a web page can read them from the response.

The auto-generated string avoids ambiguous characters (e.g. 0/O, 1/l).

Code Examples

Example

See an example with auto-generated text

Error Handling

If parameters are missing or invalid, the API will return an error:

  • 400Mode must be one of: image, challengeThe mode value is not valid
  • 400A custom text cannot be used in challenge modetext was provided together with mode=challenge
  • 400length must be a numberThe length parameter is not a number
  • 400length must be between 1 and 20The length is out of range
  • 400width must be a numberThe width parameter is not a number
  • 400width must be between 100 and 800The width is out of range
  • 400height must be a numberThe height parameter is not a number
  • 400height must be between 50 and 400The height is out of range
  • 400Noise must be one of: low, medium, highInvalid noise value
  • 400Invalid color (use hex like ff6600)A bg or color parameter is malformed

Related Endpoints

  • post/v5/captcha - Verify a challenge answer
  • get/v5/pow - Proof of work, the recommended alternative
Edit this page on GitHubReport an issue

Last updated on September 8, 2026