How to bypass Capy Puzzle

Introduction

Capy Puzzle captcha is an interactive verification system that requires users to solve a visual puzzle, such as assembling pieces or moving an element to a specific position. Unlike simple text captchas, Capy generates unique tokens and requires exact context matching, making it highly resistant to standard automation and scraping methods.

For developers working on automation, testing, or web scraping, Capy Puzzle captcha presents a significant challenge. Its non-standard interaction format and visual complexity make it impossible to bypass using traditional OCR solutions.

In this guide, we'll walk through how to automatically bypass Capy Puzzle captcha using the 2Captcha API. We'll cover how to extract the necessary parameters from the page, configure the task, and correctly inject the received solution into the target website.

How to Find Capy Puzzle captcha Parameters on a Website

To successfully solve the captcha, you need one critical parameter: websiteKey (often also referred to as the sitekey).

1. Open the target page in your browser and launch the developer tools (F12).
2. Navigate to the Elements or Network tab.
3. Look for the script or iframe that loads the Capy captcha. It usually contains the websiteKey or sitekey parameter in its URL or attributes.
4. Copy the value of this key. It typically consists of a long string of letters and numbers.

API Parameters

The 2Captcha API supports two task types for Capy Puzzle: using our internal proxies (CapyPuzzleTaskProxyless) and using your own proxies (CapyPuzzleTask).

Required Parameters (for both types)

Optional Parameters

Proxy Parameters (for CapyPuzzleTask only)

If the website strictly checks IP addresses, use the CapyPuzzleTask type and pass your residential proxy details.

JSON Request Examples

Create Task Request (Proxyless)

{
    "clientKey": "YOUR_API_KEY",
    "task": {
        "type": "CapyPuzzleTaskProxyless",
        "websiteURL": "https://example.com/login",
        "websiteKey": "PUZLE_abcdef1234567890"
    }
}

Create Task Request (with Your Proxy)

{
    "clientKey": "YOUR_API_KEY",
    "task": {
        "type": "CapyPuzzleTask",
        "websiteURL": "https://example.com/login",
        "websiteKey": "PUZLE_abcdef1234567890",
        "proxyType": "http",
        "proxyAddress": "1.2.3.4",
        "proxyPort": 8080,
        "proxyLogin": "user",
        "proxyPassword": "password"
    }
}

Successful Response with Solution

Unlike many other captchas, Capy Puzzle returns a solution object containing both the answer and the challenge_key. You will need both values for the final request on the target site.

{
    "errorId": 0,
    "status": "ready",
    "solution": {
        "answer": "0xaxakx0xaxaax0xkxx3ox0x3ox3ox...gAAAAABk8bgzEFOg9i3Jm",
        "challenge_key": "e0348984-92ec-23af-1488-446e3a58946c"
    },
    "cost": "0.00299",
    "createTime": 1692863536,
    "endTime": 1692863556
}

Step-by-Step Implementation in Python

Step 1: Create the Task

import requests

API_KEY = "YOUR_API_KEY"
API_HOST = "api.2captcha.com"

def create_capy_task(website_url, websiteKey):
    payload = {
        "clientKey": API_KEY,
        "task": {
            "type": "CapyPuzzleTaskProxyless",
            "websiteURL": website_url,
            "websiteKey": websiteKey
        }
    }
    
    response = requests.post(f"https://api.2captcha.com/createTask", json=payload)
    return response.json()["taskId"]

Step 2: Get the Result

import time

def get_capy_result(task_id):
    while True:
        time.sleep(5)
        
        payload = {
            "clientKey": API_KEY,
            "taskId": task_id
        }
        
        response = requests.post(f"https://api.2captcha.com/getTaskResult", json=payload)
        result = response.json()
        
        if result.get("status") == "ready":
            return result["solution"]
        elif result.get("errorId") != 0:
            raise Exception(f"API error: {result.get('errorDescription')}")

Complete Code Examples

Python (via Official SDK)

Using the SDK significantly simplifies your code, as the library handles task status polling for you.

from twocaptcha import TwoCaptcha

solver = TwoCaptcha('YOUR_API_KEY')

try:
    result = solver.capy(
        site_key='PUZLE_abcdef1234567890',
        url='https://example.com/login'
    )
    
    print(f"Answer: {result['answer']}")
    print(f"Challenge Key: {result['challenge_key']}")
    
except Exception as e:
    print(f"Error solving: {e}")

Selenium Integration and Answer Injection

After receiving the answer and challenge_key, you need to pass them to the website. Capy typically expects this data in hidden form fields or through a JavaScript callback before form submission.

from selenium import webdriver
from selenium.webdriver.common.by import By
from twocaptcha import TwoCaptcha
import time

driver = webdriver.Chrome()
driver.get("https://example.com/login")
time.sleep(3)  # Wait for the captcha to load

# Solve the captcha
solver = TwoCaptcha('YOUR_API_KEY')
result = solver.capy(
    site_key='PUZLE_...',
    url=driver.current_url
)

# Inject the received data into hidden fields (adapt selectors to your specific website)
driver.execute_script(f"""
    let answerInput = document.querySelector('input[name="capy_answer"]');
    if (!answerInput) {{
        answerInput = document.createElement('input');
        answerInput.type = 'hidden';
        answerInput.name = 'capy_answer';
        document.querySelector('form').appendChild(answerInput);
    }}
    answerInput.value = '{result["answer"]}';
    
    let challengeInput = document.querySelector('input[name="capy_challenge_key"]');
    if (challengeInput) {{
        challengeInput.value = '{result["challenge_key"]}';
    }}
""")

# Submit the form
driver.find_element(By.CSS_SELECTOR, "button[type='submit']").click()

Best Practices

1. Extract the websiteKey Accurately

The captcha key is embedded in the script URL or iframe attributes. If you copy it incorrectly or truncate extra characters, the task won't be solved.

2. Use Residential Proxies for Strict Websites

Capy analyzes network traffic. If you solve the captcha via Proxyless but the final POST request with the answer comes from your datacenter IP, the website may reject the token. In such cases, use the CapyPuzzleTask type and pass the proxy directly to the API.

3. Pass Both Parameters from the Solution

Many developers mistakenly send only the answer. However, Capy often requires validation of the answer and challenge_key pair. Make sure you pass both values in the final request to the target website.

4. Synchronize the User-Agent

If you're using Selenium or Playwright, pass the browser's User-Agent in the userAgent parameter when creating the task. This helps the Capy system link the solving session with the form submission session.

Solution Accuracy Reports

If a captcha solution turns out to be incorrect or you want to confirm a correct answer, use the 2Captcha reporting system. This helps improve recognition quality and trains our workers.

When to Send Reports

Send reportIncorrect if:

• The website rejected the received answer and challenge_key
• The captcha didn't load or threw an internal error after token injection
• The worker missed a step in the interactive puzzle

Send reportCorrect if:

• The solution passed validation on the website and the form was successfully submitted
• You want to confirm the high quality of the worker's performance

Report Parameters

Example of Sending a Report

import requests

API_KEY = "YOUR_API_KEY"
API_HOST = "api.2captcha.com"

def report_incorrect(task_id):
    """Report an incorrect Capy Puzzle captcha solution"""
    response = requests.post(
        f"https://api.2captcha.com/reportIncorrect",
        json={
            "clientKey": API_KEY,
            "taskId": task_id
        }
    )
    return response.json().get("errorId") == 0

def report_correct(task_id):
    """Report a correct Capy Puzzle captcha solution"""
    response = requests.post(
        f"https://api.2captcha.com/reportCorrect",
        json={
            "clientKey": API_KEY,
            "taskId": task_id
        }
    )
    return response.json().get("errorId") == 0

Important Points for Reporting

1. Save the taskId — make sure to save the task ID in your script's state so you can send a report after verifying the answer on the target website.
2. Send reports promptly — reports are only accepted within a certain time frame after the task is solved.
3. Don't abuse reports — send reportIncorrect only if you're confident the issue is on the service side, not due to your IP address or an expired session on the website.

Troubleshooting Common Issues

Website Rejects the Answer (Invalid Token)

Solutions:

• Make sure you're passing both the answer and the challenge_key.
• Check if the captcha session has expired (usually 1-2 minutes). Inject the answer immediately after receiving it.
• Switch to CapyPuzzleTask with a residential proxy so the IP address during solving matches the IP during form submission.

ERROR_CAPTCHA_UNSOLVABLE Error

Solutions:

• Verify the websiteKey you copied is correct.
• Make sure the page URL is specified fully and correctly.
• Check if the captcha domain is blocked in your network.

Captcha Doesn't Appear on the Page

Solutions:

• Capy may not load if the website detects you're using automation (Selenium/Puppeteer) without masking. Use Undetected Chromedriver or stealth plugins.

Useful Links

• Capy Puzzle API Documentation: https://2captcha.com/api-docs/capy-puzzle-captcha
• Capy Solver Page: https://2captcha.com/p/capy-puzzle-captcha
• Code Examples on GitHub: https://github.com/2captcha
• Support Center: https://2captcha.com/support/tickets/new
• How to Submit Reports: https://2captcha.com/h/how-to-submit-reports

Conclusion

Bypassing Capy Puzzle captcha through 2Captcha requires careful attention to extracting parameters from the page and correctly passing the received solution.

Key Takeaways:

1. Accurately extract the websiteKey from the page.
2. Remember that the solution consists of two parts: answer and challenge_key. Both need to be passed to the website.
3. For websites with strict IP checking, use the CapyPuzzleTask type with your proxies.
4. Inject tokens as quickly as possible before the session expires.
5. Use reportIncorrect and reportCorrect to maintain high solution quality.

Following these recommendations, you'll be able to reliably automate interactions with websites protected by the Capy Puzzle system.