Справочник API

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

Эта страница переведена с китайской версии машинным переводом и может содержать ошибки. Приоритет имеет китайская версия.

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

Запрос

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 (для Китая), см. Адреса подключения.
Тело запроса — JSON с заголовком Content-Type: application/json, не более 6 MB. Комментарии в JSON недопустимы.
Каждый запрос должен содержать clientKey; копируйте значение из Панели целиком.

Ответ

Успех:

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

Ошибка:

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

Поле	Описание
`errorId`	0 — успех, 1 — ошибка
`errorCode`	Код ошибки; значения и способы решения см. в разделе Коды ошибок
`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 секунд	Больше ничего делать не нужно

К какому виду относится каждый тип, показывает столбец «Способ возврата» на странице Типы задач и цены.

Опрос

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

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

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

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

Дальше

createTask — создание задачи
getTaskResult — получение результата
Лимит параллельных задач и автоматическая приостановка: при слишком большом числе ошибок ключ приостанавливается на несколько минут