# Create a reCAPTCHA job

> Send a reCAPTCHA v2 image grid and get a job id. Fetch the answer with a second request.

`POST https://api.solvecha.com/v1/recognition/recaptcha`


Creates a job for a reCAPTCHA image challenge. For `3x3` and `4x4` grids send one picture of the whole grid. For `1x1` (the single tiles that appear after a click) send 1 to 9 tile pictures. The answer is not in this response: [fetch it](https://solvecha.com/docs/api/get-job-result.md) with the job id.

## Authorization

Send your API key as `Authorization: Bearer YOUR_API_KEY`. Other ways are the `key` field of the body and the `key` query parameter. See [Authentication](https://solvecha.com/docs/authentication.md).

## Request body

JSON, or url-encoded form data. The body is limited to 4.5 MB.

| Name | Type | Required | Description |
|---|---|---|---|
| `key` | string | No | Your API key, if you do not send it in the `Authorization` header or the query string. |
| `task` | string | Yes | The instruction text that the user reads, for example `Select all images with buses`. Send the full sentence. Up to 2,048 characters. |
| `grid` | string | Yes | The grid size of the challenge. One of `3x3`, `4x4`, `1x1`. |
| `image_data` | array of strings | Yes | Base64 pictures without a `data:` prefix. One picture of the whole grid for `3x3` and `4x4`. One to nine tile pictures for `1x1`. In a form body use `image_data[0]`, `image_data[1]` and so on. |

## Example request


**cURL**

```bash
curl -X POST "https://api.solvecha.com/v1/recognition/recaptcha" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task": "Select all images with buses",
  "grid": "3x3",
  "image_data": ["BASE64_IMAGE"]
}'
```

**Python**

```python
import requests

response = requests.post(
    "https://api.solvecha.com/v1/recognition/recaptcha",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Select all images with buses",
        "grid": "3x3",
        "image_data": ["BASE64_IMAGE"]
    },
)
print(response.status_code, response.json())
```

**Node.js**

```js
const response = await fetch("https://api.solvecha.com/v1/recognition/recaptcha", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "task": "Select all images with buses",
    "grid": "3x3",
    "image_data": ["BASE64_IMAGE"]
  }),
});
console.log(response.status, await response.json());
```

**Go**

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "task": "Select all images with buses",
  "grid": "3x3",
  "image_data": ["BASE64_IMAGE"]
}`)
	req, err := http.NewRequest("POST", "https://api.solvecha.com/v1/recognition/recaptcha", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}
```


## Response

### 200 OK

The job was created. `data` is the job id.

```json
{"data": "1234567"}
```

### Errors

An error has the HTTP status of its code and this body:

```json
{"error": 15, "code": 15, "message": "Invalid key", "type": null}
```

| Code | HTTP status | When |
|---|---|---|
| `10` Invalid request | 400 | The body is not JSON or url-encoded form data (multipart is not supported), it is larger than 4.5 MB, or a field or the number of images is wrong. |
| `11` Rate limit reached | 429 | Your key is above the create requests per minute of its plan. |
| `15` Invalid key | 401 | The key is missing, malformed or unknown. |
| `16` Out of credit | 403 | No active plan, expired plan, or the daily quota is used up. |
| `9` Unknown error | 500 | Server error. Retry after a few seconds. |

All codes are on the [Errors](https://solvecha.com/docs/errors.md) page.

## Notes

See [reCAPTCHA image grids](https://solvecha.com/docs/captcha-types/recaptcha.md) for how to read the answer, and [Send feedback](https://solvecha.com/docs/api/send-feedback.md) to tell us whether Google accepted it.