Captcha OCR API (1.0.0)

1. Sign up on the website. New accounts get 500 free credits.
2. Create an API key on the dashboard (API keys → New key). The key is shown once.
3. Send a captcha:

curl -s https://captchaocr.allvoraz.com/v1/solve \
  -H "Authorization: Bearer $CAPTCHA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"image\": \"$(base64 < captcha.png | tr -d '\n')\", \"numeric\": true, \"length\": 6}"
# {"text":"482915","confidence":0.99,"reliable":true,"engine":"ocr","raw":"482915",
#  "expression":null,"error":null,"id":184467,"charged":true}

Official SDKs: Python, TypeScript/JavaScript, Go, Java, Kotlin, C#, PHP, Ruby, Rust, Swift and Dart. Every operation below shows each language's call.

Both take the same body and options, cost the same, and return the same answer object.

Submit, then fetch. POST /v1/submit reserves a credit, stores the task, and returns its id with HTTP 202 before solving. The captcha is solved in the background, usually within 0.1 s. GET /v1/result/{id} returns:

?wait=N (0-30) holds the request until the task finishes or N seconds pass, so one request usually returns the answer without a polling loop. Results are kept 48 hours; another key's task ids return 404. A key may have up to 256 unfinished tasks (429 beyond that).

curl -s https://captchaocr.allvoraz.com/v1/submit -H "Authorization: Bearer $CAPTCHA_API_KEY" \
  -H 'Content-Type: application/json' -d '{"image": "<base64>", "numeric": true, "length": 6}'
# {"id": 184467, "status": "processing"}
curl -s "https://captchaocr.allvoraz.com/v1/result/184467?wait=10" -H "Authorization: Bearer $CAPTCHA_API_KEY"
# {"id": 184467, "status": "ready", "result": {"text": "482915", "reliable": true, ...}, "error": null}

Send your API key with every request, either as Authorization: Bearer <key> or as X-API-Key: <key>. Keys are created and revoked on the dashboard. A revoked key stops working within 30 seconds. Keep keys on your server: anyone holding a key can spend its credits.

• 1 credit = 1 reliable answer. A captcha costs a credit only when the response has reliable: true. Undecodable images (error) and low-confidence reads are returned free.
• Credits are prepaid in packs (₹100, ₹1,000, ₹5,000) by card, UPI (Google Pay, PhonePe, Paytm) or netbanking. They work out to ₹25, ₹22 and ₹20 per 1,000 solves.
• Every response carries an X-Credits-Remaining header. GET /v1/balance returns the balance.
• A request needs enough credits for all of its images up front (402 insufficient_credits otherwise). The uncharged ones are returned before the response is sent; for /v1/submit, when the task finishes.

Describe the captcha, not the answer you want. Each option you set removes wrong readings the model could otherwise make.

• numeric alone also turns look-alike letters into digits (O → 0, l → 1, S → 5).
• uppercase or lowercase alone folds the other case into it, and turns look-alike digits into letters (0 → O).
• length is enforced by the decoder: it returns the most likely reading of exactly that many characters. Set it whenever the site's captchas have a fixed length.
• math returns the computed answer in text and the expression it computed in expression.

if result.error:          the image couldn't be decoded (not charged): re-download it
elif result.reliable:     submit result.text (charged)
else:                     refresh the captcha and solve the new one (not charged)

confidence is the probability of the least certain character. reliable combines it with engine-specific checks: the length matched, a math answer is non-negative, a Hindi number word was read exactly.

GET /v1/balance returns {"credits": N, "alert_threshold": T} (alert_threshold is null without an alert). Every solve response also carries the balance in the X-Credits-Remaining header.

Each account can have one low-balance alert. When a solve leaves your credits below its threshold, we POST your JSON payload to your url, so your team hears about it before captchas start failing with 402.

curl -s -X PUT https://captchaocr.allvoraz.com/v1/alert -H "Authorization: Bearer $CAPTCHA_API_KEY" \
  -H 'Content-Type: application/json' -d '{
    "threshold": 500,
    "url": "https://hooks.example.org/captcha-credits",
    "payload": {"text": "Captcha credits low: {{credits}} left (alert at {{threshold}})"},
    "headers": {"Authorization": "Bearer my-hook-secret"}
  }'

How it behaves:

• It fires once per drop below the threshold, then armed becomes false. Buying credits that bring the balance back to the threshold or above re-arms it.
• We POST with Content-Type: application/json and X-CaptchaOCR-Event: low_balance, and treat any 2xx as delivered. Otherwise we retry after 10 s and 60 s. Redirects are not followed.
• PUT /v1/alert replaces your alert and arms it. GET /v1/alert shows it with the last delivery (last_fired_at, last_status, last_error). DELETE /v1/alert removes it.
• POST /v1/alert/test sends it right now with your current balance and returns {"delivered": true, "status": 200, "error": null}, without changing armed.

If a site rejects an answer that was reliable, call POST /v1/report with the answer's id (from /v1/solve, or the task id from /v1/submit) within 48 hours, and the credit is returned. Refunds per day are capped at 10% of that day's charged solves (plus 5).

POST /v1/solve_batch takes up to 256 images, solves them in parallel, and returns results in request order. The top-level options apply to every image. An item can override any of them:

{
  "numeric": true,
  "images": [
    {"image": "<base64>"},
    {"image": "<base64>", "length": 5},
    {"image": "<base64>", "math": true}
  ]
}

A plain base64 string works as shorthand for {"image": "<base64>"}. A bad image fails only its own slot.

Besides /v1, the API offers task-style endpoints for normal (image) captchas, the createTask / getTaskResult shape many captcha integrations already use. Point such a client at this API's host and send your key as clientKey.

Low-confidence reads come back as ERROR_CAPTCHA_UNSOLVABLE and are not charged.

• About 25 ms per text captcha and 6 ms per math captcha, plus network time.
• Up to 32 concurrent requests per key, 256 unfinished submitted tasks per key, 256 images per batch, 5 MB per image.
• Reuse one SDK client (HTTP keep-alive) rather than creating one per call.

The API and every SDK share one semantic version. Adding fields is a minor release, and clients must ignore unknown response fields. Removing or renaming a field is a major release.

Read captchas. Each reliable answer costs 1 credit.

Balance and refunds.

Task API: createTask / getTaskResult / getBalance / reportIncorrect (ImageToTextTask).

Operational endpoints.