API 01 · Requires worker

CAPTCHA Image Recognition

Recognises text in PNG, JPEG or WebP images you own or are authorised to test. Images are converted to grayscale and optionally resized and binarised (Otsu or fixed threshold) in Rust and recognised with Tesseract through Rust bindings. Up to 5 images per request. This endpoint does not bypass third-party CAPTCHA services and makes no compatibility claims.

POST https://dev.itsozy.lol/api/v1/ocr/captcha

Requires worker. Tesseract's native libraries cannot run inside Vercel functions, so recognition runs on the optional isolated worker. Without OZY_WORKER_URL this endpoint returns 503 worker_unavailable.

Authentication

Send Authorization: Bearer ozy_… with an API key that includes the ocr permission (or *). Signed-in dashboard sessions work in the playground. Each call costs 10 units.

Parameters

Name	Type		Description
`authorized_testing`	boolean	required	Must be true: confirms the images are yours or from an authorised test environment
`images`	string[]	required	1-5 base64 images (PNG/JPEG/WebP, max 1 MiB each). Or send multipart files with an `options` JSON part
`options.threshold`	number \| "otsu"	optional	Binarise at 0-255 or with Otsu's method
`options.scale`	number	optional	Resize factor 0.25-4 (default 1)
`options.psm`	integer	optional	Tesseract page segmentation mode: 3, 6, 7 (default), 8, 11 or 13
`options.whitelist`	string	optional	Restrict recognised characters

Example request

curl -X POST https://dev.itsozy.lol/api/v1/ocr/captcha \
  -H "Authorization: Bearer $OZY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"authorized_testing": true, "images": ["iVBORw0KGgo..."], "options": {"threshold": "otsu", "scale": 2, "psm": 7}}'

Example response (illustrative)

{
  "engine": "tesseract",
  "formats": [
    "png"
  ],
  "results": [
    {
      "confidence": 87.4,
      "height": 120,
      "text": "X7K2P",
      "width": 400
    }
  ]
}

Errors

Errors use one envelope: {"error": {"code": "…", "message": "…"}}.

Status	Code	Meaning
503	`worker_unavailable`	The optional self-hosted worker is not configured on this deployment
502	`worker_failed`	The worker could not complete the job
400	`invalid_input`	A parameter is missing or invalid
401	`unauthorized`	No valid API key or session
403	`permission_denied`	The key does not include this API's permission
429	`quota_exceeded`	Free-tier quota reached (20 units/min, 100 units/day)
503	`database_unavailable`	Persistent storage is temporarily unavailable

Rate limits

20 units per minute and 100 units per day per account; outbound fetches to the same host are spaced at least one second apart. Exceeding a limit returns 429.

Try it in the playground