captcha-cli

A simple captcha generator

I. Introduction

This is a simple captcha generator that utilizing pillow and pydub to generate captcha.

This also include a simple CLI to help you manage captcha level and data.

II. Installation

1. Base installation

You can install this package using pip:

pip install captcha-cli

or with uv:

uv add captcha-cli

2. manage installation

You can install this package with DB driver using pip:

pip install 'captcha-cli[manage]'

or with uv:

uv add 'captcha-cli[manage]'

This package comes with DB library (sqlalchemy) and default driver (aiosqlite)

3. api installation

You can install this package with API support using pip:

pip install 'captcha-cli[api]'

or with uv:

uv add 'captcha-cli[api]'

This package comes with DB part (sqlalchemy and aiosqlite) and API part (fastapi)

4. Using Docker

You can pull latest Docker image to your machine and use it:

docker pull git.vaito.dev/vair.nooi/captcha:latest

Or using dev image:

docker pull git.vaito.dev/vair.nooi/captcha:dev-latest

Or any dev build image:

docker pull git.vaito.dev/vair.nooi/captcha:<image id>

III. Usage

1. CLI

a. Add captcha level

• Text captcha:

  captcha add text --level <int> --angle <int> <int> --lines <int> <int> --dots <int> <int> --amplitude <int> --wavelength <int>
  

  • -L / --level <int> act as the level id
  • -a / --angle <int> <int> the range of the rotation angle of each character
  • -l / --lines <int> <int> the range of the number of lines will be on the image
  • -d / --dots <int> <int> the range of the number of dots will be on the image
  • -A / --amplitude <int> the amplitude of distortion
  • -w / --wavelength <int> the wavelength of distortion
  • Note amplitude and wavelength will decide how the picture will be bent

• Audio captcha:

  captcha add audio --level <int> --white-noise <int> <int> --pitch-shift <int> <int>
  

  • -L / --level <int> act as the level id
  • -w / --white-noise <int> <int> the range of the volume of the background noise, both int are negative number
  • -p / --pitch-shift <int> <int> the range of the shift of each character pitch
  • Notes:
    • For white noise volumne, -35 is very quiet, 0 is super dupper loud
    • The pitch shift should be from 1 to 12
    • The pitch is kinda useless

b. Delete captcha level

captcha delete --type [audio | text] --level <string>

• -t / --type [audio | test] the type of the captcha
• -l / --level <string> the level id

c. List captcha levels

captcha list --type [audio | text]

• -t / --type [audio | test] the type of the captcha

d. Generate captcha

captcha generate --type [audio | text] --level <string> --text <string> --length <int> --preview

• -t / --type [audio | test] the type of the captcha
• -L / --level <string> the level id
• --text <string> the text to generate
• -k / --length <int> the length of random text
• -p / --preview preview the captcha
• Notes
  • To use given text to generate captcha, use --text option
  • To use random text to generate captcha, use --length option
  • --preview option use pillow Image.show() for text captcha and pydub play() for audio captcha
  • --preview is required if you don't install package with DB option

e. Get all generated captcha (require DB installation)

captcha all --type [audio | text | both]

• -t / --type [audio | text | both] captcha type filter

f. Start API server

captcha api --host <string> --port <int>

• -h / --host the host adress
• -p / --port the server port

2. API

Beside using CLI, you can also interact with app using API.

a. Start API

You can use this method

Or using Docker image:

docker run --name captcha -p 8000:8000 -v <path on your host>:/app/file git.vaito.dev/vair.nooi/captcha

b. Endpoints

• POST /captcha

  Create a new captcha

  • Query:

    • type: "text" / "audio" captcha type
    • noise_level: string captcha level
    • text: string | null (default: null) predefined captcha answer, if null, use random text
    • include_data: boolean (default: false) include base64 encoded captcha in the response

  • Return:

    • id: string captcha id, use for getting answer
    • type: "text" / "audio" captcha type, should match with the requested one
    • data: string | null base64 encoded captcha

• POST /solve

  Solve the captcha

  • Query:

    • id: string captcha id
    • answer: string captcha answer

  • Return:

    • status: "accepted" / "wrong" if the answer was true

• GET /captcha

  Get the captcha detail

  • Query:

    • id: string captcha id
    • with_answer: boolean (default false) captcha answer, return error if env variable ALLOW_GET_ANSWER is unset or set to false

  • Return:

    • id: string captcha id, use for getting answer
    • type: "text" / "audio" captcha type
    • answer: string captcha answer

  • Note: Field answer in reponse would be omitted if query with_answer is false

• GET /captcha/file

  Get the captcha data

  • Query:

    • id: string captcha id

  • Return:

    • A JPG file if the captcha type is text
    • or A WAV file if the captcha type is audio

IV. Env variables

Name	Default value	Data type	Note
APP_LEVEL	Base on your installation	simple/manage/api	simple if you install captcha-cli manage if you install captcha-cli[manage] api if you install captcha-cli[api]
DB_URL	sqlite+aiosqlite:///file/db.sqlite	string	Have to have the async dialect (driver) of the database (e.g. aiosqlite for sqlite) Should be accepted by sqlalchemy
ALLOW_GET_ANSWER	false	boolean	Set this to true to be able to get the captcha answer in API response
HOST	127.0.0.1	Any IP
PORT	8000	integer