Shopee Captcha

Overview

Shopee Captcha is a captcha system used by Shopee to protect users and systems from abnormal behavior such as bots, spam, or automated login.

Achicaptcha supports automatic Shopee captcha solving for various platforms (browser, emulator, phone). See the guide below to integrate the API.

🛍️

For Shopee text captcha, please refer to Text Captcha. If you encounter any issues, please contact admin (opens in a new tab) for support.

1. Create Task

Request

POST https://api.achicaptcha.com/createTask

Parameters

Parameter	Data Type	Required?	Description
`clientKey`	string	yes	API key
`task.type`	string	yes	ShopeeCaptchaTask
`task.image`	string	yes	Base64 mask image\|Base64 background image
`task.subType`	int	yes	Captcha type: 0: Slider captcha

Request Example

POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ShopeeCaptchaTask",
    "image": "/9j/4AAQSkZJRgABAQEASABIAAD...|/9j/4DSJFHKSDJDS...",
    "subType": 0
  }
}

Response

On success, the server will return errorId = 0 and taskId

{
  "errorId": 0,
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

2. Get Result

Request

POST https://api.achicaptcha.com/getTaskResult

Parameters

Parameter	Data Type	Required?	Description
`clientKey`	string	yes	API key, contact admin
`taskId`	string	yes	TaskId from step (1)

Request Example

POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "Your API_KEY",
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

Response

{
  "errorId": 0,
  "status": "ready",
  "solution": "x1,y1,x2,y2"
}

Response Meaning

errorId = 0 and status = ready: Successfully solved, read result in solution
errorId = 1 and status = processing: Captcha is being solved, wait 1-2 seconds and try again
errorId other than 0 and 1: System error, error code and description provided
solution: For slider captcha: returns the x-axis coordinate to drag

Integration Examples

import requests
import time
 
def solve_shopee_captcha(mask_image, bg_image, sub_type, api_key='YOUR_API_KEY'):
    # Step 1: Create task
    create_task_url = 'https://api.achicaptcha.com/createTask'
    create_task_payload = {
        'clientKey': api_key,
        'task': {
            'type': 'ShopeeCaptchaTask',
            'image': mask_image + '|' + bg_image,
            'subType': sub_type
        }
    }
    
    response = requests.post(create_task_url, json=create_task_payload)
    result = response.json()
    
    if result['errorId'] != 0:
        raise Exception(result['errorDescription'])
    
    task_id = result['taskId']
    
    # Step 2: Get result
    get_result_url = 'https://api.achicaptcha.com/getTaskResult'
    
    while True:
        time.sleep(2)  # Wait 2 seconds
        
        get_result_payload = {
            'clientKey': api_key,
            'taskId': task_id
        }
        
        response = requests.post(get_result_url, json=get_result_payload)
        result = response.json()
        
        if result['errorId'] == 0 and result['status'] == 'ready':
            return result['solution']
        
        if result['errorId'] != 0 and result['errorId'] != 1:
            raise Exception(result['errorDescription'])
        
        # If status == 'processing', continue loop
 
# Usage
mask_image = '/9j/4AAQSkZJRgABAQEASABIAAD...'  # Base64 mask image
bg_image = '/9j/4DSJFHKSDJDS...'  # Base64 background image
sub_type = 0  # 0: Slider captcha
solution = solve_shopee_captcha(mask_image, bg_image, sub_type, 'YOUR_API_KEY')
print('Shopee captcha solution:', solution)

Common Error Codes

Error Codes When Creating Task

Error Code	Description	Notes
0	success	Task created successfully
2	missing required fields	Missing required fields, check parameters (image, subType)
3	task not supported	Task type not supported
4	task creation failed	Task creation failed, try again later
5	client key does not exist	API key does not exist, check your API key
6	insufficient account balance	Insufficient account balance, add more credits

Error Codes When Getting Result

Error Code	Description	Notes
0	success	Success, read result in `solution` field
1	processing	Processing, wait 1-2 seconds and send request again
5	client key does not exist	API key does not exist, check your API key
7	task failed, please create a new task	Task failed, please create a new task
8	task ID does not exist	Task ID does not exist or has expired

Best Practices

To achieve the best results when using Achicaptcha API for Shopee Captcha, follow these principles:

1. Prepare Base64 Images

Convert mask and background images to Base64 format
Ensure image quality is clear to increase accuracy
Connect two images with the | (pipe) character

2. Polling Interval

Wait at least 1-2 seconds between result checks
Don't spam the API with too many consecutive requests
Have a timeout to avoid infinite loops (recommended 120 seconds)

3. Error Handling

Check errorId to detect errors
errorId = 0 and status = ready: Success
errorId = 1: Processing, continue polling
errorId other than 0 and 1: System error, needs handling

4. Retry Logic

Implement retry for temporary errors
Use exponential backoff when retrying
Limit maximum retry attempts

5. API Key Security

Don't hardcode API key in code
Use environment variables
Don't expose API key on client-side

Useful Links:

Tiktok Captcha Faucet Captcha