141 行
4.0 KiB
Markdown
141 行
4.0 KiB
Markdown
---
|
|
name: captcha-third-party-services
|
|
description: Unified captcha workflow for 2Captcha, YesCaptcha, and Anti-Captcha. Use when users need official API-based task submission (`createTask`), polling (`getTaskResult`), balance checks (`getBalance`), provider fallback, or debugging captcha token pipelines for reCAPTCHA/hCaptcha/Turnstile/FunCaptcha and similar challenge types.
|
|
---
|
|
|
|
# Captcha Third Party Services
|
|
|
|
## Overview
|
|
|
|
Use official APIs to create captcha tasks, poll completion, and return solve tokens with consistent behavior across providers.
|
|
|
|
Read `references/official-docs-and-analysis.md` when you need provider-specific details, method URLs, and compatibility notes.
|
|
|
|
## Inputs To Collect
|
|
|
|
- Provider: `2captcha`, `yescaptcha`, or `anti-captcha`
|
|
- Captcha task type (for example `RecaptchaV2TaskProxyless`, `TurnstileTaskProxyless`, `HCaptchaTaskProxyless`)
|
|
- Target metadata: `websiteURL`, `websiteKey` and task-specific fields
|
|
- API key (runtime secret, not hardcoded into committed files)
|
|
|
|
## API Key Handling
|
|
|
|
Prefer environment variables:
|
|
|
|
- `CAPTCHA_2CAPTCHA_KEY`
|
|
- `CAPTCHA_YESCAPTCHA_KEY`
|
|
- `CAPTCHA_ANTI_CAPTCHA_KEY`
|
|
|
|
Only use direct `--api-key` arguments for one-off tests.
|
|
|
|
## Unified Workflow
|
|
|
|
1. Check balance before creating tasks.
|
|
2. Build a `task` payload that matches provider-supported task schema.
|
|
3. Submit `createTask`.
|
|
4. Poll `getTaskResult` every 3-5 seconds until `status=ready` or timeout.
|
|
5. Return `solution` token and timing/cost metadata.
|
|
|
|
## Provider Selection Strategy
|
|
|
|
- Start with preferred provider from user.
|
|
- If provider returns permanent task validation errors, fix payload first.
|
|
- If provider returns transient capacity/timeouts, fail over to next provider.
|
|
- Keep task type and site parameters identical during failover to isolate provider variance.
|
|
|
|
Recommended fallback order:
|
|
|
|
1. `yescaptcha`
|
|
2. `2captcha`
|
|
3. `anti-captcha`
|
|
|
|
Adjust order using account balance, measured solve latency, and recent success rate.
|
|
|
|
## Use The Bundled CLI
|
|
|
|
Use `scripts/captcha_api_cli.py` for deterministic API calls.
|
|
|
|
### Balance
|
|
|
|
```bash
|
|
python3 scripts/captcha_api_cli.py balance --provider 2captcha
|
|
python3 scripts/captcha_api_cli.py balance --provider yescaptcha
|
|
python3 scripts/captcha_api_cli.py balance --provider anti-captcha
|
|
```
|
|
|
|
### Create Task
|
|
|
|
```bash
|
|
python3 scripts/captcha_api_cli.py create-task \
|
|
--provider 2captcha \
|
|
--task-json '{"type":"RecaptchaV2TaskProxyless","websiteURL":"https://example.com","websiteKey":"SITE_KEY"}'
|
|
```
|
|
|
|
### Poll Task Result
|
|
|
|
```bash
|
|
python3 scripts/captcha_api_cli.py get-task-result \
|
|
--provider 2captcha \
|
|
--task-id 123456789
|
|
```
|
|
|
|
### End-To-End Solve (Create + Poll)
|
|
|
|
```bash
|
|
python3 scripts/captcha_api_cli.py solve \
|
|
--provider yescaptcha \
|
|
--task-json '{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"SITE_KEY"}' \
|
|
--poll-interval 3 \
|
|
--timeout 180
|
|
```
|
|
|
|
## Raw Curl Patterns
|
|
|
|
Use these when a user explicitly asks for direct HTTP examples.
|
|
|
|
### createTask
|
|
|
|
```bash
|
|
curl -sS https://api.<provider-domain>/createTask \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"clientKey":"<API_KEY>",
|
|
"task":{
|
|
"type":"RecaptchaV2TaskProxyless",
|
|
"websiteURL":"https://example.com",
|
|
"websiteKey":"SITE_KEY"
|
|
}
|
|
}'
|
|
```
|
|
|
|
### getTaskResult
|
|
|
|
```bash
|
|
curl -sS https://api.<provider-domain>/getTaskResult \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{
|
|
"clientKey":"<API_KEY>",
|
|
"taskId":123456789
|
|
}'
|
|
```
|
|
|
|
### getBalance
|
|
|
|
```bash
|
|
curl -sS https://api.<provider-domain>/getBalance \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"clientKey":"<API_KEY>"}'
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
- `errorId != 0`: treat as API-level failure and inspect `errorCode`/`errorDescription`.
|
|
- Stuck in `processing`: extend timeout or switch provider.
|
|
- Invalid key/site params: validate task type and required fields from official docs.
|
|
- Low balance: call `getBalance` and select another provider if needed.
|
|
|
|
## Compliance
|
|
|
|
- Use these services only for authorized security testing and legitimate automation.
|
|
- Respect target website Terms of Service and applicable laws.
|