# createTask 创建任务

> POST /createTask 创建一个验证码识别任务：请求参数（clientKey、task、softID）、校验顺序、异步返回 taskId、同步直接返回 solution，余额须大于 10 点。

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

`createTask` 创建一个识别任务，在 `task.type` 里指定识别哪一种验证码。异步类型返回 `taskId`，之后用 [`getTaskResult`](https://docs.yescaptcha.com/zh/api/get-task-result/) 取结果；同步类型直接返回结果。任务创建成功时扣点，余额必须大于 10 点。

- POST `https://api.yescaptcha.com/createTask` (国际节点)
- POST `https://cn.yescaptcha.com/createTask` (国内节点)

## 请求参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `clientKey` | string | 是 | 账户密钥，在 [yescaptcha.com](https://yescaptcha.com/) 后台复制 |
| `task` | object | 是 | 任务对象，必须有 `type`；其他字段按任务类型填，见各任务类型页 |
| `softID` | integer | 否 | 开发者 ID。你开发的软件给别人用时带上它，可以得到分成，见 [开发者分成](https://docs.yescaptcha.com/zh/account/developer/) |

## 请求示例

识别一张图片验证码（同步）：

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

获取 reCAPTCHA v2 的 token（异步）：

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

各任务类型的 `task` 字段见 [任务类型与价格](https://docs.yescaptcha.com/zh/tasks/) 下的各页。

## 返回结果

异步类型：

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

记下 `taskId`，5 秒后开始用 `getTaskResult` 查询。

同步类型：

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

失败：

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

## 检查顺序

服务端按这个顺序检查请求，遇到第一个问题就返回对应的错误码，不扣点：

1.  请求体是合法的 JSON：`ERROR_REQUEST_FORMATS`
2.  带了 `clientKey`：`ERROR_REQUIRED_FIELDS`
3.  `clientKey` 存在：`ERROR_KEY_DOES_NOT_EXIST`
4.  没有被自动暂停：`ERROR_IP_BLOCKED_5MIN`（见 [并发限制与自动暂停](https://docs.yescaptcha.com/zh/api/rate-limits/)）
5.  余额大于 10 点：`ERROR_ZERO_BALANCE`
6.  带了 `task`：`ERROR_TASK_ABSENT`
7.  `task.type` 存在：`ERROR_TASK_NOT_SUPPORTED`
8.  必填字段齐全：`ERROR_REQUIRED_FIELDS`（`errorDescription` 里写了缺哪个字段）
9.  图片类任务的图片合法：`ERROR_ZERO_CAPTCHA_FILESIZE`、`ERROR_IMAGE_TYPE_NOT_SUPPORTED` 等

## 完整示例

创建任务并轮询结果（异步类型）：

**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-"
  }
}'
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"]  # 从环境变量读取 clientKey

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):  # 每 5 秒查询一次，最多等约 3 分钟
        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; // 从环境变量读取 clientKey

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++) { // 每 5 秒查询一次，最多等约 3 分钟
    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);
```