Caila Async Predict API

Async Predict API позволяет отправлять асинхронные запросы к Caila-сервису. Запросы ставятся в очередь на обработку, их статус и результат можно получить отдельными запросами. Такой режим полезен для долгих predict-запросов, когда синхронный HTTP-вызов может прерваться по таймауту клиента или соединения.

Async Predict API описывает только протокол асинхронного взаимодействия с Caila. Формат входных и выходных данных зависит от конкретного Caila-сервиса. За подробной информацией обратитесь к описанию сервиса в каталоге.

Когда использовать

Используйте Async Predict API, если:

обработка запроса может занять десятки минут или часы;
не нужно держать HTTP-соединение открытым все время обработки;
результат можно получить позже, когда обработка завершится.

Для коротких запросов используйте синхронный Predict API. Он возвращает результат сразу в ответе на POST /predict или POST /predict-with-config.

Жизненный цикл задачи

В Async Predict API задача — это асинхронный predict-запрос, который платформа поставила в очередь на обработку. У задачи есть идентификатор taskId: по нему можно проверить текущее состояние обработки, получить результат или отменить выполнение.

Создайте задачу одним из методов POST …/async/predict (см. Методы ниже).
Сохраните taskId из ответа.
Проверяйте статус с помощью GET …/async/task/{taskId}.
Когда статус станет COMPLETED, получите результат с помощью GET …/async/task/{taskId}/response.
Если нужно прервать выполнение задачи, вызовите метод POST …/async/task/{taskId}/cancel.

Статусы

Статус задачи показывает, на каком этапе выполнения она находится и можно ли получить результат.

Статус	Финальный	Описание
`QUEUED`	Нет	Задача создана и ожидает обработки.
`PROCESSING`	Нет	Задача выполняется: запрос отправляется в сервис или ожидается ответ.
`COMPLETED`	Да	Задача завершилась, можно запросить результат с помощью `GET …/async/task/{taskId}/response`.
`CANCELED`	Да	Задача отменена или завершилась с ошибкой во время обработки.

Методы

В таблице перечислены методы для создания задачи, проверки ее состояния, получения результата и отмены выполнения.

Для каждого метода указано право доступа, которое должно быть назначено API-ключу в разделе Моё пространство → API-ключи. Если у API-ключа нет нужного права, запрос завершится ошибкой 403 TOKEN_PERMISSION_REQUIRED.

Метод	Путь	Право API-ключа	Назначение
`POST`	`/api/mlpgateway/account/{account}/model/{model}/async/predict`	Запросы к моделям	Создать задачу с raw body
`POST`	`/api/mlpgateway/account/{account}/model/{model}/async/predict-with-config`	Запросы к моделям	Создать задачу с телом `PredictRequestData`
`POST`	`/api/mlpgateway/account/{account}/model/{model}/async/predict-with-config-v2`	Запросы к моделям	Создать задачу с телом `Predict2RequestData`
`GET`	`/api/mlpgateway/account/{account}/async/task/{taskId}`	Чтение данных	Получить статус задачи
`GET`	`/api/mlpgateway/account/{account}/async/task/{taskId}/response`	Чтение данных	Получить результат задачи
`POST`	`/api/mlpgateway/account/{account}/async/task/{taskId}/cancel`	Изменение данных	Отменить задачу

Создать задачу с raw body

Метод: POST

Путь: /api/mlpgateway/account/{account}/model/{model}/async/predict

Право доступа API-ключа: «Запросы к моделям»

Path-параметры

Параметр	Тип	Описание
`account`	`string`	ID или имя аккаунта — владельца сервиса.
`model`	`string`	ID или имя сервиса.

Query-параметры

Параметр	Тип	Обязательный	Описание
`configId`	`integer`	Нет	ID конфигурации predict. Если параметр не указан, используется конфигурация сервиса по умолчанию.
`dataType`	`string`	Нет	Тип данных запроса, например `application/json`.

Тело запроса

Тело запроса содержит данные predict-запроса, передаваемого в сервис. Формат данных зависит от сервиса.

Ответ

При успешном создании задачи метод возвращает 200 OK и строку taskId.

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Пример

curl --request POST 'https://caila.io/api/mlpgateway/account/{account}/model/{model}/async/predict?dataType=application/json' \
  --header 'MLP-API-KEY: {api_token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "text": "Привет"
  }'

Создать задачу с PredictRequestData

Метод: POST

Путь: /api/mlpgateway/account/{account}/model/{model}/async/predict-with-config

Право доступа API-ключа: «Запросы к моделям»

Path-параметры

Параметр	Тип	Описание
`account`	`string`	ID или имя аккаунта — владельца сервиса.
`model`	`string`	ID или имя сервиса.

Тело запроса

Тело запроса имеет формат PredictRequestData.

Поле	Тип	Обязательное	Описание
`data`	`object`	Да	Данные predict-запроса. Формат зависит от сервиса.
`config`	`object`	Нет	Конфигурация predict-запроса. Если поле не указано, используется конфигурация сервиса по умолчанию.
`dataType`	`string`	Нет	Тип данных запроса, например `application/json`.

{
  "data": {
    "text": "Привет"
  },
  "config": {
    "temperature": 0.2
  },
  "dataType": "application/json"
}

Ответ

При успешном создании задачи метод возвращает 200 OK и строку taskId.

Пример

curl --request POST 'https://caila.io/api/mlpgateway/account/{account}/model/{model}/async/predict-with-config' \
  --header 'MLP-API-KEY: {api_token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "data": {
      "text": "Привет"
    },
    "config": {
      "temperature": 0.2
    },
    "dataType": "application/json"
  }'

Создать задачу с Predict2RequestData

Метод: POST

Путь: /api/mlpgateway/account/{account}/model/{model}/async/predict-with-config-v2

Право доступа API-ключа: «Запросы к моделям»

predict-with-config-v2 используется, когда клиенту удобнее передавать data и config в виде строк. Обычно это JSON, сериализованный в строку.

Path-параметры

Параметр	Тип	Описание
`account`	`string`	ID или имя аккаунта — владельца сервиса.
`model`	`string`	ID или имя сервиса.

Тело запроса

Тело запроса имеет формат Predict2RequestData.

Поле	Тип	Обязательное	Описание
`data`	`string`	Да	Данные predict-запроса в виде строки.
`config`	`string`	Нет	Конфигурация predict в виде строки. Если поле не указано, используется конфигурация сервиса по умолчанию.
`dataType`	`string`	Нет	Тип данных запроса, например `application/json`.

{
  "data": "{\"text\":\"Привет\"}",
  "config": "{\"temperature\":0.2}",
  "dataType": "application/json"
}

Ответ

При успешном создании задачи метод возвращает 200 OK и строку taskId.

Пример

curl --request POST 'https://caila.io/api/mlpgateway/account/{account}/model/{model}/async/predict-with-config-v2' \
  --header 'MLP-API-KEY: {api_token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "data": "{\"text\":\"Привет\"}",
    "config": "{\"temperature\":0.2}",
    "dataType": "application/json"
  }'

Получить статус задачи

Метод: GET

Путь: /api/mlpgateway/account/{account}/async/task/{taskId}

Право доступа API-ключа: «Чтение данных»

Path-параметры

Параметр	Тип	Описание
`account`	`string`	ID или имя аккаунта, от имени которого создана задача.
`taskId`	`string`	Идентификатор задачи.

Ответ

Метод возвращает 200 OK и объект AsyncTaskData.

{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "callerId": 123,
  "status": "PROCESSING",
  "createdAt": 1715000000000,
  "completedAt": null
}

Пример

curl --request GET 'https://caila.io/api/mlpgateway/account/{account}/async/task/{taskId}' \
  --header 'MLP-API-KEY: {api_token}'

Получить результат задачи

Метод: GET

Путь: /api/mlpgateway/account/{account}/async/task/{taskId}/response

Право доступа API-ключа: «Чтение данных»

Path-параметры

Параметр	Тип	Описание
`account`	`string`	ID или имя аккаунта, от имени которого создана задача.
`taskId`	`string`	Идентификатор задачи.

Ответ

HTTP-статус	Описание
`200 OK`	Задача завершена, в теле находится ответ сервиса.
`204 No Content`	Задача еще не завершена.
`404 Not Found`	Задача или сохраненный результат не найдены. Например, результат мог быть удален после истечения TTL.
Другой статус	Ошибка, которую вернул сервис.

примечание

Текущая реализация сохраняет результат Async Predict API с Content-Type: application/json. Не используйте dataType исходного запроса как гарантию Content-Type ответа.

Пример

curl --request GET 'https://caila.io/api/mlpgateway/account/{account}/async/task/{taskId}/response' \
  --header 'MLP-API-KEY: {api_token}'

Пример готового результата:

{
  "result": "Готово"
}

Если задача еще выполняется:

HTTP/1.1 204 No Content

Отменить задачу

Метод: POST

Путь: /api/mlpgateway/account/{account}/async/task/{taskId}/cancel

Право доступа API-ключа: «Изменение данных»

Path-параметры

Параметр	Тип	Описание
`account`	`string`	ID или имя аккаунта, от имени которого создана задача.
`taskId`	`string`	Идентификатор задачи.

Ответ

Если задача найдена и запрос на отмену принят, метод возвращает 200 OK без тела. После отмены проверьте статус с помощью метода GET /api/mlpgateway/account/{account}/async/task/{taskId}.

Пример

curl --request POST 'https://caila.io/api/mlpgateway/account/{account}/async/task/{taskId}/cancel' \
  --header 'MLP-API-KEY: {api_token}'

Модели данных

AsyncTaskData

AsyncTaskData возвращается методом GET /api/mlpgateway/account/{account}/async/task/{taskId}.

Поле	Тип	Описание
`taskId`	`string`	Идентификатор задачи.
`callerId`	`integer`	ID аккаунта, от имени которого создана задача.
`status`	`string`	Один из статусов: `QUEUED`, `PROCESSING`, `COMPLETED`, `CANCELED`.
`createdAt`	`integer`	Время создания задачи, Unix timestamp в миллисекундах.
`completedAt`	`integer` или `null`	Время завершения задачи, Unix timestamp в миллисекундах. Для незавершенной задачи значение `null`.

PredictRequestData

PredictRequestData используется в POST /api/mlpgateway/account/{account}/model/{model}/async/predict-with-config.

Поле	Тип	Обязательное	Описание
`data`	`object`	Да	Данные predict-запроса.
`config`	`object`	Нет	Конфигурация predict-запроса.
`dataType`	`string`	Нет	Тип данных запроса.

Predict2RequestData

Predict2RequestData используется в POST /api/mlpgateway/account/{account}/model/{model}/async/predict-with-config-v2.

Поле	Тип	Обязательное	Описание
`data`	`string`	Да	Данные predict-запроса в виде строки.
`config`	`string`	Нет	Конфигурация predict-запроса в виде строки.
`dataType`	`string`	Нет	Тип данных запроса.

Пример полного цикла вызовов для получения результата

curl --request POST 'https://caila.io/api/mlpgateway/account/{account}/model/{model}/async/predict' \
  --header 'MLP-API-KEY: {api_token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{"text":"Привет"}'

TASK_ID='a1b2c3d4-e5f6-7890-abcd-ef1234567890'

while true; do
  STATUS=`curl --silent --request GET "https://caila.io/api/mlpgateway/account/{account}/async/task/${TASK_ID}" \
    --header 'MLP-API-KEY: {api_token}' | jq --raw-output '.status'`

  echo "Status: ${STATUS}"

  if [ "${STATUS}" = "COMPLETED" ] || [ "${STATUS}" = "CANCELED" ]; then
    break
  fi

  sleep 5
done

if [ "${STATUS}" = "COMPLETED" ]; then
  curl --request GET "https://caila.io/api/mlpgateway/account/{account}/async/task/${TASK_ID}/response" \
    --header 'MLP-API-KEY: {api_token}'
fi

Ограничения и квоты

Доступ к аккаунту. Получать статус, результат и отменять задачу может только аккаунт, которому принадлежит задача.
Права доступа API-ключа. API-ключу должно быть назначено право для выполняемой операции: для создания задачи — «Запросы к моделям», для получения статуса и результата — «Чтение данных», для отмены — «Изменение данных».
Доступ к сервису. При создании задачи аккаунт, от имени которого выполняется запрос, должен иметь доступ к целевому Caila-сервису. Для публичных сервисов применяются правила публичного тестирования.
Idle jobs. Количество задач в очереди ограничено лимитом количества запросов в секунду из настроек аккаунта, но не больше системного лимита 250.
Active jobs. Количество одновременно выполняемых задач ограничено лимитом количества запросов в секунду из настроек аккаунта, но не больше системного лимита 50.
Rate limiting. Запросы на создание задач входят в лимит запросов в секунду, заданный в настройках аккаунта.
Хранение и TTL результата. Ответы длиннее 150 символов сохраняются в хранилище файлов и имеют TTL 7 дней. После удаления сохраненного результата запрос GET …/async/task/{taskId}/response вернет 404 Not Found.
Streaming. Async Predict API не отправляет частичный результат по мере обработки: результат доступен только после завершения задачи.

Ошибки

Async-specific ошибки

Код ошибки	HTTP status	Когда возникает
`TOO_MANY_IDLE_ASYNC_TASKS`	`429`	Превышен лимит задач, ожидающих обработки.
`ASYNC_REQUEST_BODY_WAS_LOST`	`404`	Не удалось восстановить тело асинхронного запроса во время обработки.
`ASYNC_RESPONSE_IS_CORRUPTED`	`404`	Не удалось прочитать сохраненный результат задачи.
`ENTITY_NOT_FOUND_BY_ID`	`404`	Задача с указанным `taskId` не найдена.
`ACCESS_TO_ANOTHER_ACCOUNT_DENIED` или `ACCESS_TO_ANOTHER_ACCOUNT_NOT_PUBLIC_DENIED`	`403`	Запрос обращается к задаче или аккаунту, к которым у клиента нет доступа.
`TOKEN_PERMISSION_REQUIRED`	`403`	У API-ключа нет права доступа, нужного для метода.

Общие ошибки predict-запросов

HTTP status	Когда возникает
`400 Bad Request`	Некорректный запрос, несуществующий сервис или отсутствие активных инстансов.
`401 Unauthorized`	API-ключ отсутствует или не найден.
`402 Payment Required`	Аккаунт заблокирован биллингом.
`403 Forbidden`	У клиента нет доступа к аккаунту, сервису или операции.
`429 Too Many Requests`	Превышен лимит запросов в секунду или лимит асинхронных задач.
`504 Gateway Timeout`	Сервис не ответил в пределах таймаута для predict-запросов.

Когда использовать​

Жизненный цикл задачи​

Статусы​

Методы​

Создать задачу с raw body​

Path-параметры​

Query-параметры​

Тело запроса​

Ответ​

Пример​

Создать задачу с PredictRequestData​

Path-параметры​

Тело запроса​

Ответ​

Пример​

Создать задачу с Predict2RequestData​

Path-параметры​

Тело запроса​

Ответ​

Пример​

Получить статус задачи​

Path-параметры​

Ответ​

Пример​

Получить результат задачи​

Path-параметры​

Ответ​

Пример​

Отменить задачу​

Path-параметры​

Ответ​

Пример​

Модели данных​

AsyncTaskData​

PredictRequestData​

Predict2RequestData​

Пример полного цикла вызовов для получения результата​

Ограничения и квоты​

Ошибки​

Async-specific ошибки​

Общие ошибки predict-запросов​

Когда использовать

Жизненный цикл задачи

Статусы

Методы

Создать задачу с raw body

Path-параметры

Query-параметры

Тело запроса

Ответ

Пример

Создать задачу с PredictRequestData

Path-параметры

Тело запроса

Ответ

Пример

Создать задачу с Predict2RequestData

Path-параметры

Тело запроса

Ответ

Пример

Получить статус задачи

Path-параметры

Ответ

Пример

Получить результат задачи

Path-параметры

Ответ

Пример

Отменить задачу

Path-параметры

Ответ

Пример

Модели данных

AsyncTaskData

PredictRequestData

Predict2RequestData

Пример полного цикла вызовов для получения результата

Ограничения и квоты

Ошибки

Async-specific ошибки

Общие ошибки predict-запросов