# Запросы и ответы

> Общие правила YesCaptcha API: POST JSON, аутентификация по clientKey, формат ответа с errorId, синхронные и асинхронные задачи, опрос каждые 5 секунд, тайм-аут 110 секунд, результат хранится около 10 минут, язык сообщений по Accept-Language.

Source: https://docs.yescaptcha.com/ru/api/overview/ · 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/overview/

Все методы принимают HTTPS `POST` с JSON в теле (только `/useragent` — это `GET`), аутентифицируются по `clientKey` в теле запроса и возвращают JSON: `errorId` равен 0 при успехе и 1 при ошибке, при этом в ответе есть `errorCode`. Решение капчи состоит из двух шагов: `createTask` создаёт задачу, а `getTaskResult` нужно опрашивать каждые 5 секунд, чтобы получить результат. Синхронные типы возвращают результат сразу в `createTask`.

## Запрос

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```

-   Endpoint: `https://api.yescaptcha.com` (глобальный) или `https://cn.yescaptcha.com` (для Китая), см. [Адреса подключения](https://docs.yescaptcha.com/ru/getting-started/endpoints.md).
-   Тело запроса — JSON с заголовком `Content-Type: application/json`, не более 6 MB. Комментарии в JSON недопустимы.
-   Каждый запрос должен содержать `clientKey`; копируйте значение из Панели целиком.

> **Осторожно:** В Python requests используйте `json=data`, а не `data=data`. Во втором случае отправляется форма, и в ответ придёт `ERROR_TASK_ABSENT` или `ERROR_REQUIRED_FIELDS`.

## Ответ

Успех:

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

Ошибка:

```json
{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}
```

| Поле | Описание |
| --- | --- |
| `errorId` | 0 — успех, 1 — ошибка |
| `errorCode` | Код ошибки; значения и способы решения см. в разделе [Коды ошибок](https://docs.yescaptcha.com/ru/api/errors.md) |
| `errorDescription` | Текстовое описание причины ошибки (для большинства кодов — на китайском) |
| `taskId` | ID задачи |
| `status` | `processing` (в обработке) или `ready` (готово) |
| `solution` | Результат; набор полей зависит от типа задачи, см. страницы отдельных типов задач |

В коде проверяйте `errorId` и `errorCode`, а не текст `errorDescription`: он может измениться.

## Синхронные и асинхронные задачи

|  | Асинхронные | Синхронные |
| --- | --- | --- |
| Какие типы | Задачи, возвращающие токен (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), страница проверки Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | Распознавание изображений (названия заканчиваются на `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` возвращает | `taskId` | `status: "ready"` и `solution` |
| Как получить результат | Вызывать `getTaskResult` каждые 5 секунд | Больше ничего делать не нужно |

К какому виду относится каждый тип, показывает столбец «Способ возврата» на странице [Типы задач и цены](https://docs.yescaptcha.com/ru/tasks.md).

## Опрос

1.  После того как `createTask` вернул `taskId`, подождите 5 секунд и вызовите `getTaskResult`.
2.  Если вернулся `status: "processing"`, подождите ещё 5 секунд и повторите; если вернулся `status: "ready"`, результат находится в `solution`.
3.  Если вернулся `errorId: 1`, прекратите опрос этой задачи и обработайте `errorCode`.

-   Повторные запросы по одному `taskId` в течение 5 секунд сразу возвращают `processing`; более частый опрос не ускорит получение результата.
-   Задача обрабатывается не дольше 110 секунд (для некоторых типов — 180–220 секунд); по истечении времени возвращается `ERROR_TASK_TIMEOUT`, а баллы автоматически возвращаются.
-   Результат хранится на сервере около 10 минут, после чего `taskId` становится недействительным, а запрос возвращает `ERROR_TASKID_INVALID`.
-   Запрос результата не списывает баллы; списание происходит только при создании задачи.

## Язык сообщений

Для сообщений об автоматической приостановке, кэшированных недопустимых параметрах и прекращении опроса язык `errorDescription` выбирается по заголовку запроса `Accept-Language`: если значение начинается с `zh`, возвращается китайский, для любого другого языка — английский, а без этого заголовка возвращаются оба варианта. Описания для остальных кодов ошибок от заголовка не зависят.

## Дальше

-   [createTask — создание задачи](https://docs.yescaptcha.com/ru/api/create-task.md)
-   [getTaskResult — получение результата](https://docs.yescaptcha.com/ru/api/get-task-result.md)
-   [Лимит параллельных задач и автоматическая приостановка](https://docs.yescaptcha.com/ru/api/rate-limits.md): при слишком большом числе ошибок ключ приостанавливается на несколько минут