# createTask – Tạo tác vụ

> POST /createTask tạo một tác vụ nhận dạng captcha. Các tham số yêu cầu (clientKey, task, softID), thứ tự kiểm tra, loại bất đồng bộ trả về taskId, loại đồng bộ trả về solution trực tiếp; số dư phải lớn hơn 10 điểm.

Source: https://docs.yescaptcha.com/vi/api/create-task/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/create-task/

`createTask` tạo một tác vụ nhận dạng; `task.type` cho biết cần giải loại captcha nào. Loại bất đồng bộ trả về `taskId`, sau đó dùng [getTaskResult](https://docs.yescaptcha.com/vi/api/get-task-result.md) để lấy kết quả; loại đồng bộ trả về kết quả trực tiếp.

> **Ghi chú:** Điểm bị trừ khi tác vụ được tạo thành công, và số dư phải lớn hơn 10 điểm mới tạo được tác vụ. Tác vụ nhận dạng thất bại hoặc hết thời gian chờ sẽ tự động được hoàn điểm.

- POST `https://api.yescaptcha.com/createTask` (Endpoint quốc tế)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint Trung Quốc)

## Tham số yêu cầu

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `clientKey` | string | Có | Khóa tài khoản, sao chép trong bảng điều khiển tại [yescaptcha.com](https://yescaptcha.com/) |
| `task` | object | Có | Đối tượng tác vụ, bắt buộc có `type`; các trường khác điền theo loại tác vụ, xem từng trang loại tác vụ |
| `softID` | integer | Không | ID nhà phát triển. Khi phần mềm bạn phát triển được người khác sử dụng, hãy kèm theo ID này để nhận chia sẻ doanh thu, xem [Chia sẻ doanh thu cho nhà phát triển](https://docs.yescaptcha.com/vi/account/developer.md) |

## Ví dụ yêu cầu

Nhận dạng một captcha hình ảnh (đồng bộ):

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "ImageToTextTaskOcrBase",
    "body": "BASE64_IMAGE"
  }
}
```

Lấy token reCAPTCHA v2 (bất đồng bộ):

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}
```

Các trường `task` của từng loại tác vụ có trong các trang thuộc [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md).

## Kết quả trả về

Loại bất đồng bộ:

```json
{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```

Hãy lưu lại `taskId`, sau 5 giây bắt đầu gọi `getTaskResult` để truy vấn.

Loại đồng bộ:

```json
{
  "errorId": 0,
  "status": "ready",
  "taskId": "2376919c-1863-11ec-a012-94e6f7355a0b",
  "solution": {
    "text": "LMResm"
  }
}
```

Thất bại:

```json
{
  "errorId": 1,
  "errorCode": "ERROR_TASK_NOT_SUPPORTED",
  "errorDescription": "任务类型不正确或不受支持"
}
```

## Thứ tự kiểm tra

Máy chủ kiểm tra yêu cầu theo thứ tự sau và trả về mã lỗi tương ứng ngay khi gặp vấn đề đầu tiên, không trừ điểm:

1.  Nội dung yêu cầu là JSON hợp lệ: `ERROR_REQUEST_FORMATS`
2.  Có `clientKey`: `ERROR_REQUIRED_FIELDS`
3.  `clientKey` tồn tại: `ERROR_KEY_DOES_NOT_EXIST`
4.  Không bị tự động tạm dừng: `ERROR_IP_BLOCKED_5MIN` (xem [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md))
5.  Số dư lớn hơn 10 điểm: `ERROR_ZERO_BALANCE`
6.  Có `task`: `ERROR_TASK_ABSENT`
7.  `task.type` tồn tại: `ERROR_TASK_NOT_SUPPORTED`
8.  Đủ các trường bắt buộc: `ERROR_REQUIRED_FIELDS` (`errorDescription` ghi rõ thiếu trường nào)
9.  Với tác vụ hình ảnh, ảnh hợp lệ: `ERROR_ZERO_CAPTCHA_FILESIZE`, `ERROR_IMAGE_TYPE_NOT_SUPPORTED`, v.v.

## Ví dụ hoàn chỉnh

Tạo tác vụ và gọi lại để lấy kết quả (loại bất đồng bộ):

**curl**

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}'

# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'
```

**Python**

solve.py

```python
import os
import time

import requests

API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]  # Read the clientKey from an environment variable

def call(method, payload):
    r = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30)
    data = r.json()
    if data.get("errorId"):
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data

def solve(task):
    task_id = call("createTask", {"task": task})["taskId"]
    for _ in range(36):  # Poll every 5 seconds, for up to about 3 minutes
        time.sleep(5)
        result = call("getTaskResult", {"taskId": task_id})
        if result.get("status") == "ready":
            return result["solution"]
    raise TimeoutError(task_id)

solution = solve({
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])
```

**Node.js**

solve.mjs

```js
const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable

async function call(method, payload) {
  const res = await fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
  });
  const data = await res.json();
  if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
  return data;
}

async function solve(task) {
  const { taskId } = await call('createTask', { task });
  for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
    await new Promise((r) => setTimeout(r, 5000));
    const result = await call('getTaskResult', { taskId });
    if (result.status === 'ready') return result.solution;
  }
  throw new Error(`timeout: ${taskId}`);
}

const solution = await solve({
  type: "NoCaptchaTaskProxyless",
  websiteURL: "https://www.google.com/recaptcha/api2/demo",
  websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```