ProjectName

10Captcha API

10captcha is an AI-powered image and CAPTCHA recognition service. 10captcha's main purpose is solving your CAPTCHAs in a quick and cost effective way by using AI "Artificial Intelligence".

Introduction

We provide an API that allows you to automate the process and integrate your software with our service.

There are few simple steps to solve your captcha or recognize the image:

1. Send your image or captcha to our server.
2. Get the ID of your task.
3. Start a cycle that checks if your task is completed.
4. Get the result.

Captcha types

Type of captcha/method	Description
Normal Captcha	27,500+ image captchas including, Solve Media, Google captcha, reCAPTCHA v1, Facebook captcha, etc.
reCAPTCHA V2	Google reCaptcha V2
reCAPTCHA V3	Google reCaptcha V3

Solving Captchas

Our API is based on HTTP requests and supports both HTTP and HTTPS protocols.

API endpoints:

https://ocr.10captcha.com/in.php is used to submit a captcha
https://ocr.10captcha.com/res.php is used to get the captcha solution

NEW For image captcha, now you can use https://ocr.10captcha.com/solve.php instead of in.php to directly get the results.

The process of solving captchas with 10captcha is really easy and it's mostly the same for all types of captchas:

Get your API key from your API key. Each user is given a unique authentication token, we call it API key. It's a 32-characters string that looks like: 347bc2896fc1812d3de5ab56a0bf4ea7 This key will be used for all your requests to our server.
Submit a HTTP POST request to our API URL: https://ocr.10captcha.com/in.php with parameters corresponding to the type of your captcha. Server will return captcha ID or an error code if something went wrong.
Make a timeout: 20 seconds for reCAPTCHA, 5 seconds for other types of captchas.
Submit a HTTP GET request to our API URL: https://ocr.10captcha.com/res.php to get the result. If captcha is already solved server will return the answer in format corresponding to the type of your captcha. By default answers are returned as plain text like: OK|Your answer. But answer can also be returned as JSON {"status":1,"request":"TEXT"} if json parameter is used. If captcha is not solved yet server will return CAPCHA_NOT_READY result. Repeat your request in 5 seconds. If something went wrong server will return an error code.

Normal Captcha

Normal Captcha is an image that contains distorted but human-readable text. To solve the captcha user have to type the text from the image.

To solve the captcha with our service you have to submit the image with HTTP POST request to our API URL: https://ocr.10captcha.com/in.php Server accepts images in multipart or base64 format.

NEW For image captcha, now you can use https://ocr.10captcha.com/solve.php instead of in.php to directly get the results.

Multipart sample form

<form method="post" action="https://ocr.10captcha.com/in.php" enctype="multipart/form-data">
  <input type="hidden" name="method" value="post">
  Your key: <input type="text" name="key" value="YOUR_APIKEY">
  The CAPTCHA file: <input type="file" name="file">
  <input type="submit" value="Upload and get the ID">
</form>

YOUR_APIKEY is Your API key.

Base64 sample form

<form method="post" action="https://ocr.10captcha.com/in.php">
  <input type="hidden" name="method" value="base64">
  Your key: <input type="text" name="key" value="YOUR_APIKEY">
  The CAPTCHA file body in base64 format:
  <textarea name="body">BASE64_FILE</textarea>
  <input type="submit" value="Upload and get the ID">
</form>

YOUR_APIKEY is here your API key.

BASE64_FILE is base64-encoded image body.

You can provide additional parameters with your request to define what kind of captcha you're sending and to help OCR servers to solve your captcha correctly. You can find the full list of parameters in the table below.

If everything is fine server will return the ID of your captcha as plain text, like: OK|123456789 or as JSON {"status":1,"request":"123456789"} if json parameter was used.

If something went wrong server will return an error. See Error Handling chapter for the list of errors.

Make a 5 seconds timeout and submit a HTTP GET request to our API URL: https://ocr.10captcha.com/res.php providing the captcha ID. The list of parameters is in the table below.

If everything is fine and your captcha is solved server will return the answer as plain text, like: OK|TEXT or as JSON {"status":1,"request":"TEXT"} if json parameter was used.

Otherwise server will return CAPCHA_NOT_READY that means that your captcha is not solved yet. Just repeat your request in 5 seconds.

If something went wrong server will return an error. See Error Handling chapter for the list of errors.

List of POST request parameters for https://ocr.10captcha.com/in.php

POST parameter	Type	Required	Description
key	String	Yes	your API key
method	String	Yes	post - defines that you're sending an image with multipart form base64 - defines that you're sending a base64 encoded image
file	File	Yes*	Captcha image file. * - required if you submit image as a file (method=post)
body	String	Yes*	Base64-encoded captcha image * - required if you submit image as Base64-encoded string (method=base64)
module	String	No	NEW Choose from custom image modules for perfect results. List of available modules: common-1, common-2, common-3, collection-1, collection-2, collection-3, collection-4, collection-5, ...
phrase	Integer Default: 0	No	0 - captcha contains one word 1 - captcha contains two or more words
regsense	Integer Default: 0	No	0 - captcha is not case sensitive 1 - captcha is case sensitive
numeric	Integer Default: 0	No	0 - not specified 1 - captcha contains only numbers 2 - captcha contains only letters 3 - captcha contains only numbers OR only letters 4 - captcha contains both numbers AND letters
calc	Integer Default: 0	No	0 - not specified 1 - captcha requires calculation (e.g. type the result 4 + 8 = )
min_len	Integer Default: 0	No	0 - not specified 1..20 - minimal number of symbols in captcha
max_len	Integer Default: 0	No	0 - not specified 1..20 - maximal number of symbols in captcha
language	Integer Default: 0	No	0 - not specified 1 - Cyrillic captcha 2 - Latin captcha
lang	String	No	Language code. See the list of supported languages.
json	Integer Default: 0	No	0 - server will send the response as plain text 1 - tells the server to send the response as JSON

List of GET request parameters for https://ocr.10captcha.com/res.php

GET parameter	Type	Required	Description
key	String	Yes	your API key
action	String	Yes	get - get the answer for your captcha
id	Integer	Yes	ID of captcha returned by in.php.
json	Integer Default: 0	No	0 - server will send the response as plain text 1 - tells the server to send the response as JSON
header_acao	Integer Default: 0	No	0 - disabled 1 - enabled. If enabled res.php will include Access-Control-Allow-Origin:* header in the response.

Request URL example:

https://ocr.10captcha.com/res.php?key=347bc2896fc1812d3de5ab56a0bf4ea7&action=get&id=123456789

reCAPTCHA V2

reCAPTCHA V2 also known as "I'm not a robot" reCAPTCHA is a very popular type of captcha.

Solving reCAPTCHA V2 with our method is pretty simple:

Look at the element's code at the page where you found reCAPTCHA.
Find a link that begins with www.google.com/recaptcha/api2/anchor or find data-sitekey parameter.
Copy the value of k parameter of the link (or value of data-sitekey parameter).
Submit a HTTP GET or POST request to our API URL: https://ocr.10captcha.com/in.php with method set to userrecaptcha and the value found on previous step as value for googlekey and full page URL as value for pageurl. You can find the full list of parameters in the table below.

Request URL example:
```
https://ocr.10captcha.com/in.php?key=347bc2896fc1812d3de5ab56a0bf4ea7&method=userrecaptcha&googlekey=6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-&pageurl=https://mysite.com/page/with/recaptcha
```
If everything is fine server will return the ID of your captcha as plain text, like: OK|123456789 or as JSON {"status":1,"request":"123456789"} if json parameter was used. Otherwise server will return an error code.
Make a 15-20 seconds timeout then submit a HTTP GET request to our API URL: https://ocr.10captcha.com/res.php to get the result. The full list of parameters is in the table below.

If captcha is already solved server will return the answer token.
Locate the element with id g-recaptcha-response and make it visible. As an alternative you can use javascript:
```
document.getElementById("g-recaptcha-response").innerHTML="TOKEN_FROM_10captcha";
```
Paste the answer token to the g-recaptcha-response field and submit the form.
Congratulations, you've passed the recaptcha!

List of GET/POST request parameters for https://ocr.10captcha.com/in.php

Parameter	Type	Required	Description
key	String	Yes	your API key
method	String	Yes	userrecaptcha - defines that you're sending a reCAPTCHA V2 with new method
googlekey	String	Yes	Value of k or data-sitekey parameter you found on page
pageurl	String	Yes	Full URL of the page where you see the reCAPTCHA
domain	String Default: google.com	No	Domain used to load the captcha: google.com or recaptcha.net
invisible	Integer Default: 0	No	1 - means that reCAPTCHA is invisible. 0 - normal reCAPTCHA.
data-s	String	No	Value of data-s parameter you found on page. Currently applicable for Google Search and other Google services.
cookies	String	No	Your cookies that will be passed to our OCR server. Format: KEY:Value, separator: semicolon.
userAgent	String	No	Your userAgent that will be passed to our OCR server and used to solve the captcha.
header_acao	Integer Default: 0	No	0 - disabled 1 - enabled. If enabled in.php will include Access-Control-Allow-Origin:* header in the response.
json	Integer Default: 0	No	0 - server will send the response as plain text 1 - tells the server to send the response as JSON
proxy	String	No	Format: login:password@123.123.123.123:3128 You can find more info about proxies here.
proxytype	String	No	Type of your proxy: HTTP, HTTPS, SOCKS4, SOCKS5.

List of GET request parameters for https://ocr.10captcha.com/res.php

GET parameter	Type	Required	Description
key	String	Yes	your API key
action	String	Yes	get - get the answer for your captcha
id	Integer	Yes	ID of captcha returned by in.php.
json	Integer Default: 0	No	0 - server will send the response as plain text 1 - tells the server to send the response as JSON

reCAPTCHA Callback

Sometimes there's no submit button and a callback function is used instead. The function is called when reCAPTCHA is solved.

Callback function is usually defined in data-callback parameter of reCAPTCHA, for example:

data-callback="myCallbackFunction"

Or sometimes it's defined as callback parameter of grecaptcha.render function, for example:

grecaptcha.render('example', {
    'sitekey' : 'someSitekey',
    'callback' : myCallbackFunction,
    'theme' : 'dark'
});

Also there's another way to find the callback function - open javascript console of your browser and explore reCAPTCHA configuration object:

___grecaptcha_cfg.clients[0].aa.l.callback

Note that aa.l may change and there can be multiple clients so you have to check clients[1], clients[2] too.

Finally all you have to do is to call that function:

myCallbackFunction();

Or even this way:

___grecaptcha_cfg.clients[0].aa.l.callback();

Sometimes it is required to provide an argument and in most cases you should put the token there. For example:

myCallbackFunction('TOKEN');

Invisible reCAPTCHA V2

reCAPTCHA V2 also has an invisible version. We added parameter invisible=1 that should be used for invisible reCAPTCHA.

Invisible reCAPTCHA is located on a DIV layer positioned -10,000px from top that makes it invisible for user.

If you are not sure — there are few ways to determine that reCAPTCHA is in invisible mode:

You don't see "I'm not a robot" checkbox on the page but getting recaptcha challenge making some actions there
reCAPTCHA's iframe link contains parameter size=invisible
reCAPTCHA's configuration object contains parameter size that is set to invisible, for example ___grecaptcha_cfg.clients[0].aa.l.size is equal to invisible

How to bypass invisible reCAPTCHA in browser?

Method 1: using javascript:

Change the value of g-recaptcha-response element to the token you received from our server:
```
document.getElementById("g-recaptcha-response").innerHTML="TOKEN_FROM_10captcha";
```

Execute the action that needs to be performed on the page after solving reCAPTCHA. Usually there's a form that should be submitted:

document.getElementById("recaptcha-demo-form").submit(); //by id
document.getElementsByName("myFormName")[0].submit(); //by element name
document.getElementsByClassName("example").submit(); //by class name

Or call the callback function:

myCallbackFunction();

Voila! You've done that with just 2 strings of code.

Method 2: changing HTML:

Cut the div containing reCAPTCHA from page body and the whole reCAPTCHA block.
Put the following code instead of the block you've just cut:
```
<input type="submit">
<textarea name="g-recaptcha-response">%g-recaptcha-response%</textarea>
```
Where %g-recaptcha-response% - is an answer token you've got from our service.
You will see "Submit query" button. Press the button to submit the form with g-recaptcha-response and all other form data to the website.

List of GET/POST request parameters for https://ocr.10captcha.com/in.php

Parameter	Type	Required	Description
key	String	Yes	your API key
method	String	Yes	userrecaptcha - defines that you're sending a reCAPTCHA V2 with new method
googlekey	String	Yes	Value of k or data-sitekey parameter you found on page
pageurl	String	Yes	Full URL of the page where you see the reCAPTCHA
domain	String Default: google.com	No	Domain used to load the captcha: google.com or recaptcha.net
invisible	Integer Default: 0	No	1 - means that reCAPTCHA is invisible. 0 - normal reCAPTCHA.
data-s	String	No	Value of data-s parameter you found on page.
cookies	String	No	Your cookies in format KEY:Value;KEY2:Value2;
userAgent	String	No	Your userAgent that will be passed to our OCR server.
header_acao	Integer Default: 0	No	0 - disabled 1 - enabled. If enabled in.php will include Access-Control-Allow-Origin:* header.
json	Integer Default: 0	No	0 - server will send the response as plain text 1 - tells the server to send the response as JSON
proxy	String	No	Format: login:password@123.123.123.123:3128
proxytype	String	No	Type of your proxy: HTTP, HTTPS, SOCKS4, SOCKS5.

List of GET request parameters for https://ocr.10captcha.com/res.php

GET parameter	Type	Required	Description
key	String	Yes	your API key
action	String	Yes	get - get the answer for your captcha
id	Integer	Yes	ID of captcha returned by in.php.
json	Integer Default: 0	No	0 - server will send the response as plain text 1 - tells the server to send the response as JSON

Request URL example:

https://ocr.10captcha.com/res.php?key=347bc2896fc1812d3de5ab56a0bf4ea7&action=get&id=123456789

reCAPTCHA V3

reCAPTCHA V3 is the newest type of captcha from Google. It has no challenge so there is no need for user interaction. Instead it uses a "humanity" rating - score.

reCAPTCHA V3 technically is quite similar to reCAPTCHA V2: customer receives a token from the API that is used to bypass the captcha on the target website.

Find the value of data-sitekey parameter in the source code of the page.

Submit a HTTP GET request to our API URL with method set to userrecaptcha, version set to v3, and provide the action and min_score parameters.

Request URL example:

https://ocr.10captcha.com/in.php?key=347bc2896fc1812d3de5ab56a0bf4ea7&method=userrecaptcha&version=v3&action=verify&min_score=0.3&googlekey=6LfZil0UAAAAAAdm1Dpzsw9q0F11-bmervx9g5fE&pageurl=https://mysite.com/page/

If everything is fine server will return the ID of your captcha: OK|2122988149

Wait 15-20 seconds and poll for the result:

https://ocr.10captcha.com/res.php?key=347bc2896fc1812d3de5ab56a0bf4ea7&action=get&id=2122988149

Use the token returned to bypass reCAPTCHA V3 on the target page.

List of GET/POST request parameters for https://ocr.10captcha.com/in.php

Parameter	Type	Required	Description
key	String	Yes	your API key
method	String	Yes	userrecaptcha - defines that you're sending a reCAPTCHA
version	String	Yes	v3 - defines that you're sending reCAPTCHA V3
googlekey	String	Yes	Value of data-sitekey parameter you found on page
pageurl	String	Yes	Full URL of the page where you bypass the captcha
action	String	No	Value of action parameter you found on page
min_score	Float Default: 0.3	No	The minimum score needed for the captcha resolution. Currently it can be 0.3, 0.7 or 0.9
json	Integer Default: 0	No	0 - server will send the response as plain text 1 - tells the server to send the response as JSON
soft_id	Integer	No	ID of the software developer.

List of GET request parameters for https://ocr.10captcha.com/res.php

GET parameter	Type	Required	Description
key	String	Yes	your API key
action	String	Yes	get - get the answer for your captcha
id	Integer	Yes	ID of captcha returned by in.php
json	Integer Default: 0	No	0 - server will send the response as plain text 1 - tells the server to send the response as JSON

Language support

For Normal Captcha you can specify the language using the lang parameter. Below is the list of supported language codes:

Language	Code	Language	Code
Arabic	ar	Korean	ko
Bulgarian	bg	Latvian	lv
Chinese (Simplified)	zh	Lithuanian	lt
Croatian	hr	Norwegian	no
Czech	cs	Polish	pl
Danish	da	Portuguese	pt
Dutch	nl	Romanian	ro
English	en	Russian	ru
Estonian	et	Slovak	sk
Finnish	fi	Slovenian	sl
French	fr	Spanish	es
German	de	Swedish	sv
Greek	el	Thai	th
Hebrew	he	Turkish	tr
Hungarian	hu	Ukrainian	uk
Indonesian	id	Vietnamese	vi
Italian	it
Japanese	ja

Using proxies

Please note that we disable this option by default to get better results, please contact support if you know you want to open it for your account.

Proxies can be used to solve most types of javascript-based captchas:

reCAPTCHA V2
reCAPTCHA V3

Proxy allows to solve the captcha from the same IP address as you load the page. Using proxies is not obligatory in most cases. But for some kind of protection you should use it. For example: Cloudflare and Datadome protection pages require IP matching.

We support the following proxy types: SOCKS4, SOCKS5, HTTP, HTTPS with authentication by IP address or login and password.

If your proxy uses login/password authentication you have to include your credentials in proxy parameter.

POST parameters for proxies

POST parameter	Type	Required	Description
proxy	String	No	Format for IP authentication: `IP_address:PORT` Example: `proxy=123.123.123.123:3128` Format for login/password authentication: `login:password@IP_address:PORT` Example: `proxy=proxyuser:strongPassword@123.123.123.123:3128`
proxytype	String	No	Type of your proxy: HTTP, HTTPS, SOCKS4, SOCKS5. Example: `proxytype=SOCKS4`

Cookies

Our API provides extended Cookies support for reCAPTCHA V2.

You can provide your cookies using the format below as the value of json_cookies parameter. We will set the cookies on our OCR server's browser.

After the captcha was solved successfully, we will return all the cookies set for domains: google.com and the domain of your target website from pageurl parameter value.

You should use json=1 parameter in your request to res.php endpoint to get the cookies.

Cookies format:

{
    "json_cookies": [
        {
            "name": "my-cookie-name-1",
            "value": "my-cookie-val-1",
            "domain": "example.com",
            "hostOnly": true,
            "path": "/",
            "secure": true,
            "httpOnly": false,
            "session": false,
            "expirationDate": 1665434653,
            "sameSite": "strict"
        },
        {
            "name": "my-cookie-name-2",
            "value": "my-cookie-val-2",
            "domain": ".google.com",
            "hostOnly": false,
            "path": "/",
            "secure": true,
            "httpOnly": false,
            "session": false,
            "expirationDate": 1668015805,
            "sameSite": "no_restriction"
        }
    ]
}

The following properties are required for each cookie:

domain (String) - the domain for cookie
name (String) - the cookie name
value (String) - the cookie value
secure (Boolean) - should we set secure attribute?

Error Handling

It's very important to use proper error handling in your code to avoid suspension of your account and service interruption.

Normally if something is wrong with your request server will return an error. Below you can find tables with lists of errors with descriptions:

errors returned by https://ocr.10captcha.com/in.php
errors returned by https://ocr.10captcha.com/res.php

Errors can be returned as plain text or as JSON if you provided json=1 parameter.

In very rare cases server can return HTML page with error text like 500 or 502 - please keep it in mind and handle such cases correctly. If you received anything that doesn't look like the answer or error code - make a 5 seconds timeout and then retry your request.

List of in.php errors

Error code	Description	Action
ERROR_WRONG_USER_KEY	You've provided key parameter value in incorrect format, it should contain 32 symbols.	Stop sending requests. Check your API key.
ERROR_KEY_DOES_NOT_EXIST	The key you've provided does not exist.	Stop sending requests. Check your API key.
ERROR_ZERO_BALANCE	You don't have free threads.	Send less captchas at a time or upgrade your plan.
ERROR_PAGEURL	pageurl parameter is missing in your request.	Stop sending requests and change your code to provide valid pageurl parameter.
ERROR_ZERO_CAPTCHA_FILESIZE	Image size is less than 100 bytes.	Check the image file.
ERROR_TOO_BIG_CAPTCHA_FILESIZE	Image size is more than 100 kB.	Check the image file.
ERROR_WRONG_FILE_EXTENSION	Image file has unsupported extension. Accepted extensions: jpg, jpeg, gif, png.	Check the image file.
ERROR_IMAGE_TYPE_NOT_SUPPORTED	Server can't recognize image file type.	Check the image file.
ERROR_UPLOAD	Server can't get file data from your POST-request. That happens if your POST-request is malformed or base64 data is not a valid base64 image.	You got to fix your code that makes POST request.
IP_BANNED	Your IP address is banned due to many frequent attempts to access the server using wrong authorization keys.	Ban will be automatically lifted after 5 minutes.
ERROR_BAD_TOKEN_OR_PAGEURL	You can get this error code when sending reCAPTCHA V2. That happens if your request contains invalid pair of googlekey and pageurl.	Explore code of the page carefully to find valid pageurl and sitekey values.
ERROR_GOOGLEKEY	You can get this error code when sending reCAPTCHA V2. That means that sitekey value provided in your request is incorrect: it's blank or malformed.	Check your code that gets the sitekey and makes requests to our API.
ERROR_WRONG_GOOGLEKEY	googlekey parameter is missing in your request.	Check your code that gets the sitekey and makes requests to our API.
ERROR_CAPTCHAIMAGE_BLOCKED	You've sent an image that is marked in our database as unrecognizable.	Try to override website's limitations.
ERROR_BAD_PARAMETERS	The error code is returned if some required parameters are missing in your request or the values have incorrect format.	Check that your request contains all the required parameters and the values are in proper format.
ERROR_BAD_PROXY	You can get this error code when sending a captcha via proxy server which is marked as BAD by our API.	Use a different proxy server in your requests.
ERROR_SERVER_ERROR	Something went wrong with our server.	Try again after 10 seconds.
ERROR_INTERNAL_SERVER_ERROR	Something went wrong with our captcha processing servers.	Try again after 10 seconds.

List of res.php errors

Error code	Description	Action
CAPCHA_NOT_READY	Your captcha is not solved yet.	Make 5 seconds timeout and repeat your request.
ERROR_CAPTCHA_UNSOLVABLE	We are unable to solve your captcha - it may not be supported.	Check if supported & you can retry to send your captcha.
ERROR_WRONG_USER_KEY	You've provided key parameter value in incorrect format, it should contain 32 symbols.	Stop sending requests. Check your API key.
ERROR_KEY_DOES_NOT_EXIST	The key you've provided does not exist.	Stop sending requests. Check your API key.
ERROR_WRONG_ID_FORMAT	You've provided captcha ID in wrong format. The ID can contain numbers only.	Check the ID of captcha or your code that gets the ID.
ERROR_WRONG_CAPTCHA_ID	You've provided incorrect captcha ID.	Check the ID of captcha or your code that gets the ID.
ERROR_EMPTY_ACTION	Action parameter is missing or no value is provided for action parameter.	Check your request parameters and add the necessary value, e.g. get or getbalance.
ERROR_PROXY_CONNECTION_FAILED	We were unable to load a captcha through your proxy server.	Use a different proxy server in your requests.
ERROR_INTERNAL_SERVER_ERROR	Something went wrong with our captcha processing servers.	Try again after 10 seconds.

User Register

Sign In

10Captcha API

Introduction

Captcha types

Solving Captchas

Normal Captcha

reCAPTCHA V2

reCAPTCHA Callback

Invisible reCAPTCHA V2

reCAPTCHA V3

Language support

Using proxies

POST parameters for proxies

Cookies

Cookies format:

Error Handling

List of in.php errors

List of res.php errors