Для запросов, которые занимают больше нескольких секунд, что типично для приложений ИИ, мы разработали систему очередей. Эта система предлагает вам детальный контроль для управления всплесками трафика, отмены запросов при необходимости и мониторинга статуса вашего запроса в очереди. Она также устраняет необходимость обработки длительных HTTP-запросов.

​
Конечные точки очереди

Вы можете получить доступ ко всем функциям очереди через следующие конечные точки:
Конечная точкаМетодОписание
api.sunra.ai/v1/queue/{идентификатор-модели}POSTДобавляет запрос в очередь
api.sunra.ai/v1/queue/requests/{идентификатор-запроса}/statusGETПолучает статус запроса
api.sunra.ai/v1/queue/requests/{идентификатор-запроса}/status/streamGETПотоковая передача статуса до завершения
api.sunra.ai/v1/queue/requests/{идентификатор-запроса}GETПолучает ответ на запрос
api.sunra.ai/v1/queue/requests/{идентификатор-запроса}/cancelPUTОтменяет запрос
Например, чтобы отправить запрос с помощью curl и добавить его в очередь: 
curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Приморский городок в стиле студии Ghibli с разноцветными домами, развевающимся бельем и кошками, спящими на подоконниках."}'
Вот пример ответа, включающий request_id: 
{
  "request_id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/cancel"
}
Полезная нагрузка включает request_id и предоставляет URL-адреса для проверки статуса, отмены или получения ответа, что упрощает ваш рабочий процесс без дополнительной разработки конечных точек.

​
Статус запроса

Для отслеживания хода выполнения вашего запроса используйте предоставленную конечную точку с вашим уникальным идентификатором запроса. Это позволяет отслеживать статус, положение в очереди или получать ответ, как только он будет готов.

​
Использование конечной точки

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

​
Пример ответа

Когда ваш запрос находится в очереди, вы получите ответ, подобный этому: 
{
  "status": "IN_QUEUE",
  "metrics": {},
  "queue_position": 0,
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/cancel"
}

​
Возможные статусы

Ваш запрос может находиться в одном из трех состояний:
  • IN_QUEUE: указывает, что запрос ожидает обработки.
    • queue_position: показывает ваше место в очереди.
    • response_url: URL-адрес для получения ответа после завершения обработки.
  • IN_PROGRESS: запрос в настоящее время обрабатывается.
    • logs: подробные журналы (если включены), показывающие этапы обработки.
    • response_url: где будет доступен окончательный ответ.
  • COMPLETED: обработка завершена.
    • logs: журналы с подробным описанием всего процесса.
    • response_url: прямая ссылка на ваш готовый ответ.

​
Включение журналов

Журналы предоставляют информацию об обработке запросов. По умолчанию они отключены, но их можно включить с помощью параметра запроса: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
Каждая запись журнала включает:
  • message: описание события.
  • level: серьезность (например, INFO, ERROR).
  • source: источник журнала.
  • timestamp: время создания журнала.

​
Мониторинг в реальном времени

Для непрерывного обновления используйте потоковую конечную точку: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream
Это обеспечивает обновление статуса в реальном времени в формате text/event-stream до завершения запроса.

​
Отмена запросов

Если ваш запрос все еще находится в очереди, вы можете отменить его с помощью: 
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

​
Получение ответов

Как только ваш запрос будет COMPLETED, получите ответ, используя: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
Эта конечная точка также предоставляет журналы для просмотра.

​
Упрощенная интеграция с клиентом Sunra

Клиент Sunra автоматизирует отслеживание статуса, упрощая разработку приложений с функциями Sunra.

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

Чтобы обеспечить справедливое использование и стабильность системы, наши конечные точки API подлежат следующим ограничениям скорости:
Тип конечной точкиОграничение скоростиПредел всплеска
Отправить в очередь10 запросов/секунду100 запросов/минуту
Все остальные конечные точки100 запросов/секунду1800 запросов/минуту
Если вы превысите эти лимиты, вы получите ответ 403 Forbidden. Мы рекомендуем реализовать механизм повторных попыток с экспоненциальной задержкой для обработки таких случаев.