docs/acceptance.md

Acceptance

This page documents acceptance targets for each supported captcha type, including the test URLs, site keys, and observed outcomes during local validation runs.

Summary

Captcha type	Target	Status
reCAPTCHA v3	https://antcpt.com/score_detector/	✅ Token returned
Cloudflare Turnstile	https://react-turnstile.vercel.app/basic	✅ Dummy token returned
reCAPTCHA v2	https://www.google.com/recaptcha/api2/demo	⚠️ Requires audio challenge (see notes)
hCaptcha	https://accounts.hcaptcha.com/demo	⚠️ Challenge-dependent
Image-to-Text	Local base64 image	✅ Text returned via vision model
Classification	Local base64 grid	✅ Object indices returned via vision model

---

reCAPTCHA v3 — Primary acceptance target

URL: https://antcpt.com/score_detector/
Site key: 6LcR_okUAAAAAPYrPe-HK_0RULO1aZM15ENyM-Mf

Acceptance checklist

1. Install dependencies and Playwright Chromium.
2. Start the service: python main.py
3. Confirm GET /api/v1/health returns all 19 supported types.
4. Create a RecaptchaV3TaskProxyless task.
5. Poll POST /getTaskResult until status=ready.
6. Confirm a non-empty solution.gRecaptchaResponse.

Curl example

TASK=$(curl -s -X POST http://localhost:8000/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "your-key",
    "task": {
      "type": "RecaptchaV3TaskProxyless",
      "websiteURL": "https://antcpt.com/score_detector/",
      "websiteKey": "6LcR_okUAAAAAPYrPe-HK_0RULO1aZM15ENyM-Mf",
      "pageAction": "homepage"
    }
  }' | python -c "import sys,json; print(json.load(sys.stdin)['taskId'])")

curl -s -X POST http://localhost:8000/getTaskResult \
  -H "Content-Type: application/json" \
  -d '{"clientKey":"your-key","taskId":"'"$TASK"'"}'

Verified outcome

• Service startup: ✅
• Health endpoint: ✅ (19 types registered)
• Task creation: ✅
• Token returned: ✅ (non-empty gRecaptchaResponse, length ~1060 chars)

---

Cloudflare Turnstile

URL: https://react-turnstile.vercel.app/basic
Site key: 1x00000000000000000000AA (Cloudflare official test key — always passes)

Curl example

curl -s -X POST http://localhost:8000/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "your-key",
    "task": {
      "type": "TurnstileTaskProxyless",
      "websiteURL": "https://react-turnstile.vercel.app/basic",
      "websiteKey": "1x00000000000000000000AA"
    }
  }'

Verified outcome

• Token returned: ✅ XXXX.DUMMY.TOKEN.XXXX (expected for Cloudflare test sitekeys)

---

reCAPTCHA v2

URL: https://www.google.com/recaptcha/api2/demo
Site key: 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-

Behavior with headless Chromium

Headless browsers are detected by Google's risk analysis engine. The checkbox click succeeds, but a visual image challenge is presented rather than issuing a token immediately.

Implemented mitigation: The solver falls back to the audio challenge path — clicking the audio button in the challenge dialog, downloading the MP3, transcribing via the configured model, and submitting the transcript.

!!! note "Audio challenge transcription" The audio challenge requires a language model capable of processing audio or base64-encoded audio data. Accuracy depends on the model endpoint configured via CAPTCHA_MODEL.

Curl example

curl -s -X POST http://localhost:8000/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "your-key",
    "task": {
      "type": "NoCaptchaTaskProxyless",
      "websiteURL": "https://www.google.com/recaptcha/api2/demo",
      "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
    }
  }'

Status

⚠️ Functionally implemented with audio challenge fallback. Success rate depends on model audio capability and Google's current challenge difficulty.

---

hCaptcha

URL: https://accounts.hcaptcha.com/demo
Site key: 10000000-ffff-ffff-ffff-000000000001 (hCaptcha official test key)

Behavior

The hCaptcha test key (10000000-ffff-ffff-ffff-000000000001) is designed to always pass — but headless browsers detected as bots still receive an image challenge. The solver clicks the checkbox iframe and polls for a token for up to 30 seconds.

Status

⚠️ Checkbox click succeeds. Token issuance depends on hCaptcha's bot detection score. For test environments, using the HCaptchaClassification task type (direct image classification) is the recommended integration path.

---

Image-to-Text

Any base64-encoded image can be sent to ImageToTextTask. The vision model returns a structured description suitable for click/slide/drag_match captcha automation.

Status

✅ Works with any OpenAI-compatible vision model endpoint. Accuracy depends on model capability.

---

What these results mean

• ✅ reCAPTCHA v3 and Turnstile are fully functional and pass in every local test run.
• ⚠️ reCAPTCHA v2 and hCaptcha browser-based solving is limited by headless browser detection. These captcha types are primarily intended to be integrated with HCaptchaClassification / ReCaptchaV2Classification task types for image grid solving, or via audio challenge transcription.
• The service is designed as a backend solver for flow2api — in practice, real-world integrations extract the image challenge frames and send them to the classification endpoint, rather than relying on full browser automation to pass the widget.